install.fairie/dotfiles/.vim/plugged/php.vim/README.md

php.vim

An up-to-date Vim syntax for PHP.

This project is a fork of php.vim--Garvin which in turn is an update of the php.vim 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 for help):

Plug 'StanAngeloff/php.vim'

If you are using Git, please be aware the original repository this project was forked from contains bad timezone in some of the commits. You'll need to fetch with fsckObjects disabled:

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.

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 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 should be. The format of the Vim variable follows the PHP predefined 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: Automatic folding of PHP functions, classes, … (also folds related PhpDoc)
• 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.

Example: Overriding PHP @tags and $parameters in comments to appear as a different highlighting group, giving them distinct colouring:

" 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):

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):

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:

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.