Emacs PHP Modeユーザーマニュアル (Draft)

**Emacs PHP Mode**(`php-mode`)はEmacsでのPHPスクリプトの編集のためのメジャーモードです。

> あと、この記事は書きかけです。

## インストール方法

`php-mode`は[開発の歴史的経緯][Will GNU Emacs Ever Include php mode?]から、Emacs本体に標準添付されていません。しかし、標準のパッケージ機能を使って[MELPA](https://melpa.org/)から簡単にインストールできます。

### package / use-package を使ったインストール

`~/.emacs.d/init.el` に以下のような記述(どちらか、または両方)があることを確認してください。

```init.el
(add-to-list 'package-archives '("melpa-stable" . "https://stable.melpa.org/packages/") t)
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
```

その上で、[use-package](https://github.com/jwiegley/use-package)が導入済みであればインストールは簡単です。

```init.el
(use-package php-mode :ensure t)
```

Emacsで`init.el`を編集しているなら、 `(use-package php-mode :ensure t)`の直後にカーソルを移動してキーボードで`C-x C-e`(<kbd><kbd>control</kbd>+<kbd>e</kbd> <kbd>control</kbd>+x</kbd>を順に押す)と、その場でPHP Modeのインストールが始まります。

packageまたはuse-packageでインストールしたパッケージは、通常`~/.emacs.d/elpa/`に配置されます。もし`.emacs.d`ディレクトリをGitで管理しているなら、このファイルは[`.gitignore`](https://git-scm.com/docs/gitignore)で管理の対象外にすることを推奨します。

Lispパッケージは継続的な更新によって改善されているので、よりよいユーザー体験を求めるにはインストールよりも定期的にアップデートすることが重要です。Emacs標準のパッケージ機能またはuse-packageでインストールした場合、以下の手順でパッケージを更新できます。

 1. `M-x list-packages` でパッケージ一覧を表示する
 2. このリスト上でキーボードの `U` (<kbd>Shift + u</kbd>)を押して、更新されたパッケージをマークする
 3. 続いてキーボードの `x` を押して更新を実行する
 4. Emacsを再起動する

MELPA版のPHP Modeには実験的な実装が含まれていることがあります。より安定性を求める場合は `:pin melpa-stable` を設定することで、正式な[バージョンリリース版](https://github.com/emacs-php/php-mode/releases)がインストールされるようになります。

```init.el
(use-package php-mode :ensure t :pin melpa-stable)
```

### 手動インストール

[emacs-php/php-mode](https://github.com/emacs-php/php-mode)を `git clone` するか、[Releases · emacs-php/php-mode](https://github.com/emacs-php/php-mode/releases)からzipまたはtarをダウンロードして展開してください。展開したあと `make` コマンドを実行すると、Lispファイルのバイトコンパイルと`php-mode-autoloads.el`が生成されます。

```init.el
(when (file-directory-p "~/path/to/php-mode")
  (load "~/path/to/php-mode/php-mode-autoloads.el"))

;; 通常、以下のコードはどれも書く必要がありません
;; (require 'php-mode)
;; (add-to-list 'load-path (expand-file-name "~/path/to/php-mode"))
;; (add-to-list 'auto-mode-alist '("\\.php\\'" . php-mode))
```

### OSのパッケージシステムからのインストール

**Debian 10**(Buster)または**Ubuntu 19.04**(Disco Dingo)以降では、 `apt install elpa-php-mode` でインストールすることができます。しかしこれらのパッケージは少々古いため注意が必要です。Emacsの個人設定を持ち込めないサーバー運用作業での一時的な利用などには利用できますが、それ以外の環境ではEmacsのパッケージ機能などで最新バージョンの利用を強く推奨します。

 * [Debian -- buster の elpa-php-mode パッケージに関する詳細](https://packages.debian.org/buster/elpa-php-mode)
 * [Ubuntu – disco の elpa-php-mode パッケージに関する詳細](https://packages.ubuntu.com/disco/elpa-php-mode)

> 以前のDebianおよびUbuntuにはPHP Modeは[`php-elisp`というパッケージ名で収録されていました](https://github.com/emacs-php/php-mode/issues/430)。しかしこのパッケージは2014年から更新されていなかったため問題が多く、強く非推奨です。

## 関連パッケージの導入

 * [editorconfig-emacs] - プロジェクト単位でのインデント設定は[EditorConfig]での設定を推奨
 * [exec-path-from-shell] - シェルから環境変数を引き継ぐ
 * [Flycheck] - 編集中のファイルの構文エラーなどをオンザフライでチェックする
 * [flycheck-phpstan] - PHPStanを使った静的解析
 * [composer.el] - EmacsからComposerを操作するインターフェイス

PHPStanを適切に設定することで、PhpStormなどの商用製品を上回る精度のコーディング時エラーチェックが可能になります。[PHPで開発が捗るリアルタイムエラーチェック](https://qiita.com/tadsan/items/16aaaaaf4e99d0a994c9)に書きました。

## カスタマイズ

### 設定例

```init.el
(defun my-php-mode-setup ()
  "My PHP-mode hook."
  (subword-mode 1)
  (setq show-trailing-whitespace t)

  (setq-local page-delimiter "\\_<\\(class\\|function\\|namespace\\)\\_>.+$")

  (require 'flycheck-phpstan)
  (flycheck-mode t)
  (add-to-list 'flycheck-disabled-checkers 'php-phpmd)
  (add-to-list 'flycheck-disabled-checkers 'php-phpcs))

(use-package php-mode
  :hook ((php-mode . my-php-mode-setup))
  :custom
  (php-manual-url 'ja)
  (php-mode-coding-style 'psr2)
  (php-mode-template-compatibility nil)
  :config
  (bind-key "[" (smartchr "[]" "array()" "[[]]") php-mode-map)
  (bind-key "]" (smartchr "array " "]" "]]")     php-mode-map)
  ;; (bind-key "C-}" 'cedit-barf php-mode-map)
  ;; (bind-key "C-)" 'cedit-slurp php-mode-map)
  (bind-key "C-c C-c" 'psysh-eval-region         php-mode-map)
  (bind-key "<f6>" 'phpunit-current-project      php-mode-map)
  (bind-key "C-c C--" 'php-current-class php-mode-map)
  (bind-key "C-c C-=" 'php-current-namespace php-mode-map))
```

[composer.el]: https://github.com/emacs-php/composer.el
[EditorConfig]: https://editorconfig.org/
[editorconfig-emacs]: https://github.com/editorconfig/editorconfig-emacs
[exec-path-from-shell]: https://github.com/purcell/exec-path-from-shell
[Flycheck]: https://www.flycheck.org/
[flycheck-phpstan]: https://github.com/emacs-php/phpstan.el
[Will GNU Emacs Ever Include php mode?]: https://github.com/emacs-php/php-mode/wiki/Will-GNU-Emacs-Ever-Include-php-mode%3F