20b4a91fbb
subrepo: subdir: "dotfiles/.vim/plugged/php.vim" merged: "930aec5c" upstream: origin: "https://github.com/stanangeloff/php.vim.git" branch: "master" commit: "930aec5c" git-subrepo: version: "0.4.3" origin: "???" commit: "???"
143 lines
6.8 KiB
Markdown
143 lines
6.8 KiB
Markdown
php.vim
|
|
=======
|
|
|
|
An up-to-date Vim syntax for PHP.
|
|
|
|
_This project is a fork of [php.vim--Garvin][php.vim-garvin] which in turn is an update of the [php.vim][php.vim-original] script which in turn is an updated version of the php.vim syntax file distributed with Vim. **Whew!**_
|
|
|
|
Installation
|
|
------------
|
|
|
|
If you don't have a preferred installation method, [vim-plug] is quick and simple. With [vim-plug installed], add the following to your `vimrc` (if you are a NeoVim user, see the [FAQ page][neovim-faq] for help):
|
|
|
|
```vim
|
|
Plug 'StanAngeloff/php.vim'
|
|
```
|
|
|
|
If you are using Git, please be aware [the original repository this project was forked from][php.vim-garvin] contains bad timezone in some of the commits. You'll need to fetch with `fsckObjects` disabled:
|
|
|
|
```sh
|
|
git clone -c fetch.fsckObjects=false git@github.com:StanAngeloff/php.vim.git
|
|
```
|
|
|
|
Unless you specify `-c fetch.fsckObjects=false` as an option to `git clone`, you may see `badTimezone: invalid author/committer line - bad time zone` in the output and the cloning will [fail](https://github.com/StanAngeloff/php.vim/issues/96).
|
|
|
|
Configuration
|
|
-------------
|
|
|
|
`php.vim` comes with sensible defaults for most use cases. Below is a list of some interesting configuration options you may tweak. Refer to the [source code][php.vim-source] for additional options.
|
|
|
|
- `g:php_version_id`,
|
|
`b:php_version_id`
|
|
|
|
Default: `g:php_version_id = 70300`
|
|
|
|
The PHP version the Vim syntax should adhere to. This currently determines how strict [Heredoc/Nowdoc syntax](https://www.php.net/manual/en/migration73.new-features.php#migration73.new-features.core.heredoc) should be. The format of the Vim variable follows the [PHP predefined constant `PHP_VERSION_ID`](https://www.php.net/manual/en/reserved.constants.php#constant.php-version-id).
|
|
|
|
- `g:php_syntax_extensions_enabled`, `g:php_syntax_extensions_disabled`
|
|
`b:php_syntax_extensions_enabled`, `b:php_syntax_extensions_disabled`
|
|
|
|
Default: `g:php_syntax_extensions_enabled = ["bcmath", "bz2", "core", "curl", "date", "dom", "ereg", "gd", "gettext", "hash", "iconv", "json", "libxml", "mbstring", "mcrypt", "mhash", "mysql", "mysqli", "openssl", "pcre", "pdo", "pgsql", "phar", "reflection", "session", "simplexml", "soap", "sockets", "spl", "sqlite3", "standard", "tokenizer", "wddx", "xml", "xmlreader", "xmlwriter", "zip", "zlib"]`
|
|
|
|
A list of PHP extension names (lowercase) for which highlighting of built-in functions, constants, classes and interfaces is enabled / disabled.
|
|
|
|
If you are **not** interested in highlighting **any** built-in functions/constants/etc., set `g:php_syntax_extensions_enabled` to an empty list `[]`.
|
|
|
|
If you are **not** interested in highlighting built-in functions/constants/etc. for a subset of PHP extensions, set `g:php_syntax_extensions_enabled` to a list of extensions you wish to disable, e.g., `["mcrypt"]`.
|
|
|
|
- `php_var_selector_is_identifier`
|
|
|
|
Default: `0`
|
|
|
|
Set this to a truthy value (e.g., `1`) to include the dollar sign `$` as part of the highlighting group for a PHP variable.
|
|
|
|
- `php_html_load`, `php_html_in_heredoc`, `php_html_in_nowdoc`
|
|
|
|
Default: `1` (NOTE: setting `php_html_load` to a truthy value takes precedence and overrides both `php_html_in_heredoc` & `php_html_in_nowdoc`)
|
|
|
|
Set to a falsy value (e.g., `0`) to disable embedding HTML in PHP. Doing so may yield significant speed-ups of syntax highlighting.
|
|
|
|
This should not affect HTML highlighting in templating languages, such as [Blade].
|
|
|
|
- `php_sql_query`, `php_sql_heredoc`, `php_sql_nowdoc`
|
|
|
|
Default: `1`
|
|
|
|
Set to a falsy value (e.g., `0`) to disable SQL syntax in PHP. Doing so may yield moderate speed-ups of syntax highlighting.
|
|
|
|
### Projects of interest
|
|
|
|
`php.vim` pairs nicely with:
|
|
|
|
- [`phpfolding.vim`](https://github.com/rayburgemeestre/phpfolding.vim): _Automatic folding of PHP functions, classes, … (also folds related PhpDoc)_
|
|
- [`PHP-Indenting-for-VIm`](https://github.com/2072/PHP-Indenting-for-VIm): _The official VIm indent script for PHP_
|
|
|
|
### Overriding highlighting
|
|
|
|
Syntax highlighting can be controlled at a fine-grained level. For example, all text in PHP comments is highlighted as `phpComment` by default, however there are smaller syntax groups you can tweak, e.g., how PHPDoc `@tags` appear. There are [several syntax groups you can choose from](syntax-groups).
|
|
|
|
Example: Overriding PHP `@tags` and `$parameters` in comments to appear as a different highlighting group, giving them distinct colouring:
|
|
|
|
```vim
|
|
" Put this function at the very end of your vimrc file.
|
|
|
|
function! PhpSyntaxOverride()
|
|
" Put snippet overrides in this function.
|
|
hi! link phpDocTags phpDefine
|
|
hi! link phpDocParam phpType
|
|
endfunction
|
|
|
|
augroup phpSyntaxOverride
|
|
autocmd!
|
|
autocmd FileType php call PhpSyntaxOverride()
|
|
augroup END
|
|
```
|
|
|
|
#### Snippets
|
|
|
|
You may add the code snippets below to your `PhpSyntaxOverride` function (see above for instructions on how to create this function).
|
|
|
|
##### Colourising namespace separator in `use`, `extends` and `implements`
|
|
|
|
If you wish to highlight the namespace separator `\` differently ([original request](https://github.com/StanAngeloff/php.vim/issues/63)):
|
|
|
|
```vim
|
|
hi phpUseNamespaceSeparator guifg=#808080 guibg=NONE gui=NONE
|
|
hi phpClassNamespaceSeparator guifg=#808080 guibg=NONE gui=NONE
|
|
```
|
|
|
|
##### Colourising parentheses
|
|
|
|
If you wish to highlight `(` and `)` differently ([original request](https://github.com/StanAngeloff/php.vim/issues/31#issuecomment-52879108)):
|
|
|
|
```vim
|
|
syn match phpParentOnly "[()]" contained containedin=phpParent
|
|
hi phpParentOnly guifg=#f08080 guibg=NONE gui=NONE
|
|
```
|
|
|
|
Developing
|
|
----------
|
|
|
|
When you install `php.vim` using your preferred installation method, all the needed files are already in place.
|
|
|
|
If you wish to rebuild the syntax file with a more recent version of PHP available on the [Docker Hub], you should use the provided `Dockerfile` to do so:
|
|
|
|
```bash
|
|
docker build --no-cache --force-rm -f attic/Dockerfile -t php.vim .
|
|
cat syntax/php.vim | docker run --rm -i php.vim > syntax/php.vim.new
|
|
docker rmi php.vim
|
|
mv syntax/php.vim.new syntax/php.vim
|
|
```
|
|
|
|
NOTE: If the updated syntax file fails to load and is corrupted, try loading `syntax/php.vim` in your favourite editor and ensure line endings are set to Unix `\n`.
|
|
|
|
|
|
[php.vim-garvin]: https://github.com/vim-scripts/php.vim--Garvin
|
|
[php.vim-original]: http://www.vim.org/scripts/script.php?script_id=2874
|
|
[vim-plug]: https://github.com/junegunn/vim-plug
|
|
[vim-plug installed]: https://github.com/junegunn/vim-plug#installation
|
|
[neovim-faq]: https://github.com/neovim/neovim/wiki/FAQ#where-should-i-put-my-config-vimrc
|
|
[php.vim-source]: https://github.com/StanAngeloff/php.vim/blob/master/syntax/php.vim#L35
|
|
[Blade]: https://github.com/jwalton512/vim-blade
|
|
[syntax-groups]: https://github.com/StanAngeloff/php.vim/blob/41c36f7f/syntax/php.vim#L804
|
|
[Docker Hub]: https://docs.docker.com/samples/library/php/
|