doom-emacs/modules/lang/php/README.org

:lang php

• Description
  • Maintainers
  • Module flags
  • Packages
  • Hacks
  • Changelog
• Installation
  • PHP
    • MacOS
    • Arch Linux
    • openSUSE
    • Debian
  • LSP Support
  • Dependencies
• Usage
  • PHPUnit
  • Composer
• Configuration
  • Docker Compose
• Troubleshooting
  • "I'm missing functionality on lsp-mode"
• Frequently asked questions
• Appendix

Description   unfold

This module adds support for PHP 5.3+ (including PHP8) to Doom Emacs.

• ctags-based code completion (company-php and phpctags)
• eldoc support (ac-php and php-extras)
• REPL (psysh)
• Code refactoring commands (php-refactor-mode)
• Unit-test commands (phpunit)
• Support for laravel and composer projects (with project-specific snippets)
• File templates
• Snippets

󰟶 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.

Maintainers

• @elken

Become a maintainer?

Module flags

+hack

Add support for the Hack dialect of PHP by Facebook.

+lsp

Enable LSP support for php-mode. Requires doom-module::tools lsp and a langserver (supports phpactor and intelephense).

+tree-sitter

Leverages tree-sitter for better syntax highlighting and structural text editing. Requires doom-module::tools tree-sitter.

Packages

• doom-package:async
• doom-package:hack-mode if doom-module:+hack
• doom-package:psysh
• doom-package:php-cs-fixer if doom-package::editor format
• doom-package:php-extras
• doom-package:php-mode
• doom-package:php-refactor-mode
• doom-package:phpunit

• if doom-module:+lsp

  • doom-package:phpactor
  • doom-package:company-phpactor

Hacks

No hacks documented for this module.

TODO Changelog

This module does not have a changelog yet.

Installation

Enable this module in your doom! block.

This module requires php (5.3+) and composer.

If doom-module:+lsp is enabled, you'll also need one of these LSP servers:

• Phpactor requires php 7.3+.
• Intelephense requires node and npm.

PHP

MacOS

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

brew tap homebrew/homebrew-php
brew install php@8.0  # or php53, php54, php55
brew install composer

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

Arch Linux

sudo pacman --needed --noconfirm -S php composer  # or php53, php54, php55

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

openSUSE

sudo zypper install php-composer

# If you use intelephense:
sudo zypper install nodejs npm

Debian

sudo apt-get install php php-common

# If you use intelephense:
sudo apt-get install nodejs npm

LSP Support

There are a number of currently supported LSP servers:

• Intelephense (Recommended)
• phpactor
• Serenata
• felixbecker (Considered unsupported)

Intelephense is currently the only server that supports automatic installation, which will trigger either when you open a PHP project or manually invoke lsp-install-server through M-x.

The others have to be installed manually and added to your $PATH.

Dependencies

• pysh (REPL)
• phpctags (better code completion)
• phpunit (unit test commands)
• php-cs-fixer and @prettier/plugin-php (for code formatting)
• phpactor (for LSP if intelephense isn't desired)

composer global require \
    psy/psysh \
    phpunit/phpunit \
    techlivezheng/phpctags \
    friendsofphp/php-cs-fixer \
    phpactor/phpactor

# Needed by php-cs-fixer, otherwise you'll get "Couldn't resolve parser
# 'php'" errors
npm install -g @prettier/plugin-php

You must ensure that $HOME/.composer/vendor/bin is in $PATH, so these executables are visible to Emacs:

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

You may also need to regenerate your envvar file by running $ doom env on the command line.

NOTE phpactor doesn't have to be installed via composer, just has to exist in your $PATH.

NOTE Phpactor cannot be installed, globally at least, with PHP ^8.

TODO Usage

󱌣 This module's usage documentation is incomplete. Complete it?

PHPUnit

This module provides an interface to PHPUnit through a number of commands as detailed below. By default, it loads configuration from the root phpunit.xml.

• phpunit-current-project Launch all tests for the project
• phpunit-current-class Launch all tests for the current class/fixture
• phpunit-current-test Launch the current test at point

If for some reason, the default phpunit.xml is in a different location (or you use the phpunit.xml.dist convention) , the path can be changed via phpunit-configuration-file

(setq phpunit-configuration-file "phpunit.xml")

Composer

This module provides several convenience methods for triggering composer commands:

Binding	Function
<localleader> m c c	composer
<localleader> m c i	composer-install
<localleader> m c r	composer-require
<localleader> m c u	composer-update
<localleader> m c d	composer-dump-autoload
<localleader> m c s	composer-run-scripts
<localleader> m c v	composer-run-vendor-bin-command
<localleader> m c o	composer-find-json-file
<localleader> m c l	composer-view-lock-file

These are all run via M-x too.

TODO Configuration

󱌣 This module's configuration documentation is incomplete. Complete it?

Docker Compose

A lot of projects rely on running inside docker compose (ie Laravel), and as such a minor mode has been configured to attempt to run tests inside the php-fpm (by default) container.

This mode is disabled by default, to opt-in set +php-run-tests-in-docker to t in your config. If this is done during Emacs running, you will also have to reload php-mode (i.e. through M-x php-mode)

If you wish to specify a different container, modify the +php-default-docker-container variable (ideally inside a .dir-locals.el file)

((php-mode . ((+php-default-docker-container . "php-octane"))))

Troubleshooting

Report an issue?

"I'm missing functionality on lsp-mode"

Unfortunately, intelephense currently operates under a "freemium" model, and as such requires a license for extended features. Once purchased, this can be (insecurely) added directly to your config:

(setq lsp-intelephense-licence-key "<key>")

A more recommended approach would be to utilise Emacs' own auth-sources for storing authentication info, which can also be encrypted.

Create a file in your home directory (which can optionally be encrypted, verify your auth-sources has the correct values) called ~/.authinfo:

machine * login intelephense password <key>

And add the following to your config:

(defun my-fetch-password (&rest params)
  (require 'auth-source)
  (let ((match (car (apply #'auth-source-search params))))
    (if match
        (let ((secret (plist-get match :secret)))
          (if (functionp secret)
              (funcall secret)
            secret))
      (error "Password not found for %S" params))))

(setq lsp-intelephense-licence-key (my-fetch-password :user intelephense))

Frequently asked questions

This module has no FAQs yet. Ask one?

TODO Appendix

󱌣 This module has no appendix yet. Write one?