1 | <p align="center">
|
2 | :construction: Work in Progress! :construction:
|
3 | </p>
|
4 |
|
5 | <div align="center">
|
6 | <img alt="Prettier"
|
7 | src="https://raw.githubusercontent.com/prettier/prettier-logo/master/images/prettier-icon-light.png">
|
8 | <img alt="PHP" height="180" hspace="25" vspace="15"
|
9 | src="https://upload.wikimedia.org/wikipedia/commons/thumb/2/27/PHP-logo.svg/500px-PHP-logo.svg.png">
|
10 | </div>
|
11 |
|
12 | <h2 align="center">Prettier PHP Plugin</h2>
|
13 |
|
14 | <p align="center">
|
15 | <a href="https://github.com/prettier/plugin-php/actions">
|
16 | <img alt="GitHub Workflow Status" src="https://img.shields.io/github/workflow/status/prettier/plugin-php/Node CI?style=flat-square">
|
17 | </a>
|
18 | <a href="https://www.npmjs.com/package/@prettier/plugin-php">
|
19 | <img alt="npm version" src="https://img.shields.io/npm/v/@prettier/plugin-php.svg?style=flat-square">
|
20 | </a>
|
21 | <a href="https://codecov.io/gh/prettier/plugin-php">
|
22 | <img alt="Codecov Coverage Status" src="https://img.shields.io/codecov/c/github/prettier/plugin-php.svg?style=flat-square">
|
23 | </a>
|
24 |
|
25 | <img alt="monthly downloads" src="https://img.shields.io/npm/dm/@prettier/plugin-php.svg?style=flat-square">
|
26 | </a> -->
|
27 | <a href="#badge">
|
28 | <img alt="code style: prettier" src="https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square">
|
29 | </a>
|
30 | <a href="https://gitter.im/jlongster/prettier">
|
31 | <img alt="Gitter" src="https://img.shields.io/gitter/room/jlongster/prettier.svg?style=flat-square">
|
32 | </a>
|
33 | <a href="https://twitter.com/PrettierCode">
|
34 | <img alt="Follow+Prettier+on+Twitter" src="https://img.shields.io/twitter/follow/prettiercode.svg?label=follow+prettier&style=flat-square">
|
35 | </a>
|
36 | </p>
|
37 |
|
38 | ## Intro
|
39 |
|
40 | Prettier is an opinionated code formatter. It enforces a consistent style by parsing your code and re-printing it with its own rules that take the maximum line length into account, wrapping code when necessary.
|
41 |
|
42 | This plugin adds support for the PHP language to Prettier.
|
43 |
|
44 | ### Can this be used in production?
|
45 |
|
46 | We're considering the plugin to be stable when pure PHP files are formatted. Formatting of files that contain mixed PHP and HTML is still considered unstable - please see [open issues with the tag "inline"](https://github.com/prettier/plugin-php/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Ainline) for details.
|
47 |
|
48 | If you want to use the plugin in production, we recommend limiting its scope to pure PHP files.
|
49 |
|
50 | ### Input
|
51 |
|
52 | ```php
|
53 | array_map(function($arg1,$arg2) use ( $var1, $var2 ) {
|
54 | return $arg1+$arg2/($var+$var2);
|
55 | }, array("complex"=>"code","with"=>"inconsistent","formatting"=>"is", "hard" => "to", "maintain"=>true));
|
56 | ```
|
57 |
|
58 | ### Output
|
59 |
|
60 | ```php
|
61 | array_map(
|
62 | function ($arg1, $arg2) use ($var1, $var2) {
|
63 | return $arg1 + $arg2 / ($var + $var2);
|
64 | },
|
65 | array(
|
66 | "complex" => "code",
|
67 | "with" => "inconsistent",
|
68 | "formatting" => "is",
|
69 | "hard" => "to",
|
70 | "maintain" => true
|
71 | )
|
72 | );
|
73 | ```
|
74 |
|
75 | ## Playground
|
76 |
|
77 | You can give the plugin a try in our [playground](https://loilo.github.io/prettier-php-playground/)!
|
78 |
|
79 | ## Install
|
80 |
|
81 | yarn:
|
82 |
|
83 | ```bash
|
84 | yarn add --dev prettier @prettier/plugin-php
|
85 | # or globally
|
86 | yarn global add prettier @prettier/plugin-php
|
87 | ```
|
88 |
|
89 | npm:
|
90 |
|
91 | ```bash
|
92 | npm install --save-dev prettier @prettier/plugin-php
|
93 | # or globally
|
94 | npm install --global prettier @prettier/plugin-php
|
95 | ```
|
96 |
|
97 | ## Use
|
98 |
|
99 | ### With Node.js
|
100 |
|
101 | If you installed prettier as a local dependency, you can add prettier as a script in your `package.json`,
|
102 |
|
103 | ```json
|
104 | {
|
105 | "scripts": {
|
106 | "prettier": "prettier"
|
107 | }
|
108 | }
|
109 | ```
|
110 |
|
111 | and then run it via
|
112 |
|
113 | ```bash
|
114 | yarn run prettier path/to/file.php --write
|
115 | # or
|
116 | npm run prettier -- path/to/file.php --write
|
117 | ```
|
118 |
|
119 | If you installed globally, run
|
120 |
|
121 | ```bash
|
122 | prettier path/to/file.php --write
|
123 | ```
|
124 |
|
125 | ### In the Browser
|
126 |
|
127 | This package exposes a `standalone.js` that can be used alongside Prettier's own `standalone.js` to make the PHP plugin work in browsers without a compile step.
|
128 |
|
129 | First, grab both standalone scripts from an npm CDN like [unpkg](https://unpkg.com/):
|
130 |
|
131 | ```html
|
132 | <script src="https://unpkg.com/prettier/standalone.js"></script>
|
133 | <script src="https://unpkg.com/@prettier/plugin-php/standalone.js"></script>
|
134 | ```
|
135 |
|
136 | Then use Prettier with PHP, just like this:
|
137 |
|
138 | ```js
|
139 | prettier.format(YOUR_CODE, {
|
140 | plugins: prettierPlugins,
|
141 | parser: "php"
|
142 | });
|
143 | ```
|
144 |
|
145 | See this code in action [in this basic demo](https://jsbin.com/butoruw/edit?html,output).
|
146 |
|
147 | ### With Bundlers
|
148 |
|
149 | Bundlers like webpack, Rollup or browserify automatically recognize how to handle the PHP plugin. Remember that even when using a bundler, you still have to use the standalone builds:
|
150 |
|
151 | ```js
|
152 | import prettier from "prettier/standalone";
|
153 | import phpPlugin from "@prettier/plugin-php/standalone";
|
154 |
|
155 | prettier.format(YOUR_CODE, {
|
156 | plugins: [phpPlugin],
|
157 | parser: "php"
|
158 | });
|
159 | ```
|
160 |
|
161 | ## Configuration
|
162 |
|
163 | Prettier for PHP supports the following options. We recommend that all users set the `phpVersion` option.
|
164 |
|
165 | | Name | Default | Description |
|
166 | | ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
167 | | `phpVersion` | `"5.4"` | Allows specifying the PHP version you're using. If you're using PHP 7.1 or later, setting this option will make use of modern language features in the printed output. If you're using PHP 5.3 or lower, you'll have to set this option or Prettier will generate incompatible code. |
|
168 | | `printWidth` | `80` | Same as in Prettier ([see prettier docs](https://prettier.io/docs/en/options.html#print-width)) |
|
169 | | `tabWidth` | `4` | Same as in Prettier ([see prettier docs](https://prettier.io/docs/en/options.html#tab-width)) |
|
170 | | `useTabs` | `false` | Same as in Prettier ([see prettier docs](https://prettier.io/docs/en/options.html#tabs)) |
|
171 | | `singleQuote` | `false` | If set to `"true"`, strings that use double quotes but do not rely on the features they add, will be reformatted. Example: `"foo" -> 'foo'`, `"foo $bar" -> "foo $bar"`. |
|
172 | | `trailingCommaPHP` | `"all"` | If set to `"all"`, trailing commas will be added wherever possible. <br> If set to `"none"`, no trailing commas are printed. |
|
173 | | `braceStyle` | `"psr-2"` | If set to `"psr-2"`, prettier will move open brace for code blocks (classes, functions and methods) onto new line. <br> If set to `"1tbs"`, prettier will move open brace for code blocks (classes, functions and methods) onto same line. |
|
174 | | `requirePragma` | `false` | Same as in Prettier ([see prettier docs](https://prettier.io/docs/en/options.html#require-pragma)) |
|
175 | | `insertPragma` | `false` | Same as in Prettier ([see prettier docs](https://prettier.io/docs/en/options.html#insert-pragma)) |
|
176 |
|
177 | ## Ignoring code
|
178 |
|
179 | A comment `// prettier-ignore` will exclude the next node in the abstract syntax tree from formatting.
|
180 |
|
181 | For example:
|
182 |
|
183 | ```php
|
184 | matrix(
|
185 | 1, 0, 0,
|
186 | 0, 1, 0,
|
187 | 0, 0, 1
|
188 | );
|
189 |
|
190 | // prettier-ignore
|
191 | matrix(
|
192 | 1, 0, 0,
|
193 | 0, 1, 0,
|
194 | 0, 0, 1
|
195 | );
|
196 | ```
|
197 |
|
198 | will be transformed to
|
199 |
|
200 | ```php
|
201 | matrix(1, 0, 0, 0, 1, 0, 0, 0, 1);
|
202 |
|
203 | // prettier-ignore
|
204 | matrix(
|
205 | 1, 0, 0,
|
206 | 0, 1, 0,
|
207 | 0, 0, 1
|
208 | )
|
209 | ```
|
210 |
|
211 | ## Editor integration
|
212 |
|
213 | ### Atom
|
214 |
|
215 | The official [prettier plugin for atom](https://github.com/prettier/prettier-atom) supports plugins.
|
216 |
|
217 | ### VScode
|
218 |
|
219 | The official [prettier plugin for vscode](https://github.com/prettier/prettier-vscode) supports plugins since Version 1.10.0. To enable it, install the extension and make sure the plugin is installed _locally_ (in your project folder). After restarting VScode the plugin should work as expected.
|
220 |
|
221 | ### Sublime Text
|
222 |
|
223 | Sublime Text support is available through Package Control and the [JsPrettier](https://packagecontrol.io/packages/JsPrettier) plugin.
|
224 |
|
225 | ### Vim
|
226 |
|
227 | Regarding plugin support in the official plugin vim-prettier see [this issue](https://github.com/prettier/vim-prettier/issues/119).
|
228 |
|
229 | #### ALE
|
230 |
|
231 | The linting plugin ALE has built-in support for prettier and its plugins. Just add prettier to your [list of fixers](https://github.com/w0rp/ale#2ii-fixing). For example:
|
232 |
|
233 | ```vim
|
234 | let g:ale_fixers={
|
235 | \'javascript': ['prettier'],
|
236 | \'json': ['prettier'],
|
237 | \'php': ['prettier'],
|
238 | \}
|
239 | ```
|
240 |
|
241 | #### Custom
|
242 |
|
243 | Alternatively, adding the following to `.vimrc` will define a custom command `:PrettierPhp` that runs the plugin while preserving the cursor position and run it on save.
|
244 |
|
245 | ```vim
|
246 | " Prettier for PHP
|
247 | function PrettierPhpCursor()
|
248 | let save_pos = getpos(".")
|
249 | %! prettier --stdin --parser=php
|
250 | call setpos('.', save_pos)
|
251 | endfunction
|
252 | " define custom command
|
253 | command PrettierPhp call PrettierPhpCursor()
|
254 | " format on save
|
255 | autocmd BufwritePre *.php PrettierPhp
|
256 | ```
|
257 |
|
258 | ## Integration for other tools
|
259 |
|
260 | ### PHP-CS-Fixer
|
261 |
|
262 | See `docs/recipes/php-cs-fixer` for integration help, code can also be found in https://gist.github.com/Billz95/9d5fad3af728b88540fa831b73261733
|
263 |
|
264 | ## Contributing
|
265 |
|
266 | If you're interested in contributing to the development of Prettier for PHP, you can follow the [CONTRIBUTING guide from Prettier](https://github.com/prettier/prettier/blob/master/CONTRIBUTING.md), as it all applies to this repository too.
|
267 |
|
268 | To test it out on a PHP file:
|
269 |
|
270 | - Clone this repository.
|
271 | - Run `yarn`.
|
272 | - Create a file called `test.php`.
|
273 | - Run `yarn prettier test.php` to check the output.
|
274 |
|
275 | ## Maintainers
|
276 |
|
277 | <table>
|
278 | <tbody>
|
279 | <tr>
|
280 | <td align="center">
|
281 | <a href="https://github.com/czosel">
|
282 | <img width="150" height="150" src="https://github.com/czosel.png?v=3&s=150">
|
283 | </br>
|
284 | Christian Zosel
|
285 | </a>
|
286 | </td>
|
287 | <td align="center">
|
288 | <a href="https://github.com/evilebottnawi">
|
289 | <img width="150" height="150" src="https://github.com/evilebottnawi.png?v=3&s=150">
|
290 | </br>
|
291 | Evilebot Tnawi
|
292 | </a>
|
293 | </td>
|
294 | </tr>
|
295 | <tbody>
|
296 | </table>
|