Skip to content

Latest commit

 

History

History
256 lines (205 loc) · 8.51 KB

README.org

File metadata and controls

256 lines (205 loc) · 8.51 KB
Raw

:lang php

Description

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.

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 [email protected]  # 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 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.

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:

BindingFunction
<localleader> m c ccomposer
<localleader> m c icomposer-install
<localleader> m c rcomposer-require
<localleader> m c ucomposer-update
<localleader> m c dcomposer-dump-autoload
<localleader> m c scomposer-run-scripts
<localleader> m c vcomposer-run-vendor-bin-command
<localleader> m c ocomposer-find-json-file
<localleader> m c lcomposer-view-lock-file

These are all run via M-x too.

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?

Appendix

🔨 This module has no appendix yet. Write one?