spacemacs/layers/+lang/php/README.org

#+TITLE: PHP layer

#+TAGS: general|layer|multi-paradigm|programming

[[file:img/php.png]]

* Table of Contents                     :TOC_5_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#install][Install]]
  - [[#layer][Layer]]
  - [[#backends][Backends]]
    - [[#intelephense][intelephense]]
    - [[#php-language-server][php-language-server]]
    - [[#ac-php-core][ac-php-core]]
      - [[#setup][Setup]]
- [[#key-bindings][Key bindings]]

* Description
This layer adds PHP language support to Spacemacs.

** Features:
- Edit PHP files using [[https://github.com/ejmr/php-mode][php-mode]]
- Edit Drupal files
- Complete and jump to define with [[https://github.com/xcwen/ac-php][company-php]]
- Run tests with PHPUnit
- Reformat code with PHP CBF
- Support for the [[https://langserver.org/][Language Server Protocol]] (experimental)

The =gtags= layer is recommended to benefit from better =eldoc= and
=helm-gtags=.

* Install
** Layer
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =php= to the existing =dotspacemacs-configuration-layers= list in this
file.

** Backends
For php you have the choice between a set of possible LSP backends with
different setup instructions and different capabilities.

Note that you'll need to use the =lsp= layer to enable these backends.

*** intelephense
This is the recommended LSP server solution. To activate it set the
layer variable =php-backend=:

#+BEGIN_SRC elisp
  (php :variables php-backend 'lsp)
#+END_SRC

and install the npm server with:

#+BEGIN_SRC sh
  npm install -g intelephense
#+END_SRC

You can find further information on the project's [[http://intelephense.net/][website]] and [[https://github.com/bmewburn/vscode-intelephense][GitHub page]].

*** php-language-server
This is an alternative LSP server implementation working on PHP basis rather than nodejs.
To activate it set the layer variable =php-backend= like for the intelephense backend and
install the server via [[https://getcomposer.org/][composer]]:

#+BEGIN_SRC sh
  composer require felixfbecker/language-server
  composer run-script --working-dir=vendor/felixfbecker/language-server parse-stubs
#+END_SRC

You can find further information on the project's [[https://github.com/felixfbecker/php-language-server][GitHub page]].

*** ac-php-core
This is a non server solution working entirely from an elisp package.
This requires no installation of external services but also delivers
the least amount of IDE like integrations with spacemacs.

To activate it just don't set the variable =php-backend= in your dotfile.
Remember that additional setup instructions are necessary on a per
project basis which you can find below.

**** Setup
Because of the way that the ac-php-core package works, there are a couple of simple
initialization tasks which must occur to get the completion working as it should.
On any new project make sure to perform the following initialization tasks:
1. Run the following

   #+BEGIN_SRC shell
     cd /root/of/project
     touch .ac-php-conf.json
   #+END_SRC

2. Inside of spacemacs run:
   = ac-php-remake-tags =

The =.ac-php-conf.json= file is required to enable auto-completion. When you run
=ac-php-remake-tags= and your =.ac-php-conf.json= file is empty the default configuration
will be used and inserted in the file.

If your project contains the following files at the root folder:
1. =.projectile=
2. =vendor/autoload.php=

the necessary configuration file (=.ac-php-conf.json=) will be created automatically
if it does not exist. 

* Key bindings

| Key binding | Description             |
|-------------+-------------------------|
| ~SPC m g g~ | jump to define at point |
| ~C-t~       | jump back               |