doomemacs/modules/lang/php/README.org

#+TITLE:   lang/php
#+DATE:    January 16, 2017
#+SINCE:   v1.3
#+STARTUP: inlineimages nofold

* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
  - [[#maintainers][Maintainers]]
  - [[#module-flags][Module Flags]]
  - [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
  - [[#php][PHP]]
    - [[#macos][MacOS]]
    - [[#arch-linux][Arch Linux]]
    - [[#opensuse][openSUSE]]
  - [[#dependencies][Dependencies]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]

* Description
This module adds support for PHP 5.3+ (including PHP7).

+ ctags-based code completion (~company-php~ and ~phpctags~)
+ eldoc support (~ac-php~ and ~php-extras~)
+ REPL (~php-boris~)
+ Code refactoring commands (~php-refactor-mode~)
+ Unit-test commands (~phpunit~)
+ Support for ~laravel~ and ~composer~ projects (with project-specific snippets)
+ [[../../editor/file-templates/templates/php-mode][File templates]]
+ [[https://github.com/hlissner/doom-snippets/tree/master/php-mode][Snippets]]

#+begin_quote
PHP was the first programming language I got paid to code in, back in the
Cretaceous period (2003). My sincerest apologies go out to all the programmers
who inherited my earliest PHP work. I know you're out there, writhing in your
straitjackets.

Save a programmer today. Stop a friend from choosing PHP as their first
language.
#+end_quote

** Maintainers
This module has no dedicated maintainers.

** Module Flags
+ =+hack= Add support for the [[https://hacklang.org/][Hack dialect of PHP]] by Facebook.
+ =+lsp= Enable LSP support through phpactor or intelephense. Requires the
  ~:tools lsp~ module and the [[https://phpactor.readthedocs.io/en/develop/usage/standalone.html][phpactor server]] to be installed on your system.
** Plugins
+ [[https://github.com/tomterl/php-boris][async]]
+ [[https://github.com/tomterl/php-boris][php-boris]]
+ [[https://github.com/arnested/php-extras][php-extras]]
+ [[https://github.com/emacs-php/php-mode][php-mode]]
+ [[https://github.com/keelerm84/php-refactor-mode.el][php-refactor-mode]]
+ [[https://github.com/nlamirault/phpunit.el][phpunit]]
+ =+hack=
  + [[https://github.com/hhvm/hack-mode][hack-mode]]
+ =+lsp=
  + [[https://github.com/emacs-php/phpactor.el][phpactor]]
  + [[https://github.com/emacs-php/phpactor.el][company-phpactor]]
+ =:editor format=
  + [[https://github.com/OVYA/php-cs-fixer][php-cs-fixer]]

* Prerequisites
** PHP
To get started with PHP, you'll need ~php~ (5.3+) and ~composer~.

Note for =+lsp=:
1. In order to make full use of phpactor server, ~php~ (7.3+) is recommended.
2. If you use intelephense, ~node~ and ~npm~ are needed.

*** MacOS
PHP 5.5 comes prepackaged with newer versions of MacOS. These instructions are provided for reference:

#+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes")
brew tap homebrew/homebrew-php
brew install php71  # or php53, php54, php55
brew install composer

# If you use intelephense:
brew install node
brew install npm
#+END_SRC

*** Arch Linux
#+BEGIN_SRC sh :dir /sudo:: :tangle (if (doom-system-os 'arch) "yes")
sudo pacman --needed --noconfirm -S php composer  # or php53, php54, php55

# If you use intelephense:
sudo pacman -S nodejs npm
#+END_SRC

*** openSUSE
#+BEGIN_SRC sh :dir /sudo::
sudo zypper install php-composer

# If you use intelephense:
sudo zypper install nodejs npm
#+END_SRC

** Dependencies
The features in this module optionally depend on the following php packages:

+ ~boris~ (REPL)
+ ~phpctags~ (better code completion)
+ ~phpunit~ (unit test commands)
+ ~php-cs-fixer~ (for code formatting)

#+BEGIN_SRC sh
composer global require \
    d11wtq/boris \
    phpunit/phpunit \
    techlivezheng/phpctags
#+END_SRC

Ensure that ~\~/.composer/vendor/bin~ is in ~PATH~:

#+BEGIN_SRC sh
# place this in your profile file, like ~/.bash_profile or ~/.zshenv
export PATH="~/.composer/vendor/bin:$PATH"
#+END_SRC

By the way, if you use intelephense, running =M-x lsp-install-server= and
choose ~iph~ to install lsp-intelephense.
* TODO Features
# An in-depth list of features, how to use them, and their dependencies.

* TODO Configuration
# How to configure this module, including common problems and how to address them.

* TODO Troubleshooting
# Common issues and their solution, or places to look for help.