branch: elpa/php-mode
commit 79ddc578f5f2625847a7f2539ba77e0765873044
Author: USAMI Kenta <[email protected]>
Commit: USAMI Kenta <[email protected]>
Document HTML template major mode selection
Explain in both READMEs that php-mode targets pure PHP scripts, that
files mixing HTML and PHP are handled by php-html-template-major-mode,
how php-mode-maybe chooses the major mode, and the
php-mode-warn-if-html-template prompt.
---
README.ja.md | 32 ++++++++++++++++++++++++++++++++
README.md | 32 ++++++++++++++++++++++++++++++++
2 files changed, 64 insertions(+)
diff --git a/README.ja.md b/README.ja.md
index 81c0f5104d..2222cbb379 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -75,6 +75,38 @@ M-x package-install php-mode
(php-project-coding-style . psr2)))
```
+## HTMLとPHPが混在するファイルの編集
+
+`php-mode`は純粋なPHPスクリプトのためのメジャーモードです。テンプレートのようにHTMLの中にPHPを埋め込んだファイルは、両方の言語を理解するメジャーモードで編集するほうが適しています。特にインデントは、HTML部分を素の`php-mode`で編集すると正しく動作しません。
+
+そうしたファイルのために、PHP
Modeは`php-html-template-major-mode`(既定は[`web-mode`](https://web-mode.org/))へ処理を委ねます。好みのモードを設定できます。
+
+```lisp
+(setopt php-html-template-major-mode 'web-mode)
+```
+
+### メジャーモードの選ばれ方
+
+拡張子`.php`のファイルは`php-mode-maybe`を通して開かれ、ファイル名と内容からメジャーモードが決まります。
+
+- `php-template-mode-alist`にマッチするファイル名(例:
`.phtml`や`.blade.php`)は、対応するテンプレート用モードで開きます。
+- それ以外は、ディレクトリローカル変数`php-project-php-file-as-template`に従います。
+ - `auto`(既定): HTMLタグを含むファイルを`php-html-template-major-mode`に切り替えます。
+ - `t`: そのディレクトリのすべての`.php`ファイルをテンプレートとして扱います。
+ - `nil`: すべての`.php`ファイルを素のPHPスクリプトとして扱います。
+- いずれにも当てはまらない場合は`php-default-major-mode`(`php-mode`)で開きます。
+
+`php-project-php-file-as-template`は`.dir-locals.el`でプロジェクトごとに設定できます。
+
+```lisp
+((nil
+ (php-project-php-file-as-template . nil)))
+```
+
+### php-modeからの切り替え
+
+すでに`php-mode`でHTMLタグを含むファイルをインデントしようとすると、PHP
Modeは警告し、`php-html-template-major-mode`への切り替えを尋ねます。このプロンプトを無効にするには`php-mode-warn-if-html-template`を`nil`に設定してください。
+
## 不具合を報告する
バグ報告の際には `M-x php-mode-debug` の出力を含めてください。この情報は問題の再現に役立ちます。
diff --git a/README.md b/README.md
index 490b3f0888..94421fb85b 100644
--- a/README.md
+++ b/README.md
@@ -77,6 +77,38 @@ You can add project-specific settings by creating a
`.dir-locals.el` or `.dir-lo
(php-project-coding-style . psr2)))
```
+## Editing files that mix HTML and PHP
+
+`php-mode` is designed for pure PHP scripts. Files that embed PHP inside
HTML, such as templates, are better edited in a major mode that understands
both languages. Indentation in particular is unreliable when the HTML part of
a file is edited in plain `php-mode`.
+
+For such files, PHP Mode defers to `php-html-template-major-mode`, which
defaults to [`web-mode`](https://web-mode.org/). Set it to any mode you prefer:
+
+```lisp
+(setopt php-html-template-major-mode 'web-mode)
+```
+
+### How the major mode is chosen
+
+Files with a `.php` extension are opened through `php-mode-maybe`, which picks
the major mode from the file name and its content:
+
+- File names matching `php-template-mode-alist` (for example `.phtml` and
`.blade.php`) open in the matching template mode.
+- Otherwise the choice follows `php-project-php-file-as-template`, a
directory-local variable:
+ - `auto` (default): switch to `php-html-template-major-mode` when the file
contains an HTML tag.
+ - `t`: treat every `.php` file in the directory as a template.
+ - `nil`: treat every `.php` file as a plain PHP script.
+- When nothing else applies, the file opens in `php-default-major-mode`
(`php-mode`).
+
+Set `php-project-php-file-as-template` per project in `.dir-locals.el`:
+
+```lisp
+((nil
+ (php-project-php-file-as-template . nil)))
+```
+
+### Switching away from php-mode
+
+If you are already in `php-mode` and indent a file that contains HTML tags,
PHP Mode warns you and offers to switch to `php-html-template-major-mode`. Set
`php-mode-warn-if-html-template` to `nil` to turn off this prompt.
+
## Reporting Bugs
When reporting a bug, please run `M-x php-mode-debug` and include its output
in your bug report. This helps us reproduce any issues you may be experiencing.
