[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[nongnu] elpa/php-mode 9cb550c501 3/3: Merge pull request #768 from emac
|
From: |
ELPA Syncer |
|
Subject: |
[nongnu] elpa/php-mode 9cb550c501 3/3: Merge pull request #768 from emacs-php/update/documentations |
|
Date: |
Sat, 18 Nov 2023 13:00:05 -0500 (EST) |
branch: elpa/php-mode
commit 9cb550c501939d6a49e0569c25e7a79c8f106dbc
Merge: 1565b0db7d d3e0467bfb
Author: USAMI Kenta <tadsan@pixiv.com>
Commit: GitHub <noreply@github.com>
Merge pull request #768 from emacs-php/update/documentations
Update documentations
---
CONTRIBUTING.md | 49 +++++----
README.ja.md | 300 +++++---------------------------------------------------
README.md | 288 +++++++----------------------------------------------
3 files changed, 93 insertions(+), 544 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f7c36c85be..58c3d13be3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -11,19 +11,25 @@ This project accepts contributions in various languages.
Not only development b
## English
+### Setup (en)
+
+[Eask] is required to build the package. You need to install it using node.js
and npm, or [download a prebuilt executable][eask-releases]. See [Eask
Introduction][eask-introduction] and [Install Eask][eask-install] for more
details.
+
+You can run the tests using the following command:
+
+```sh
+make test
+```
+
### Guideline (en)
-All contributions to PHP Mode are welcome. But please try to do the following
when sending improvements or bug fixes:
+All contributions to PHP Mode are welcome. But please try to do the following
when submitting enhancements or bug fixes:
- 1. Add your name to the list of ‘Contributors’ in this `README.md` file if it
is not there already. If you have a GitHub page and/or personal site then
please feel free to link your name to it so people can see your other work.
- 2. If your contribution addresses an issue on the GitHub project page then
include a single line like `GitHub-Issue: #16` with the appropriate issue
number.
- 3. Make sure to update the constant `php-mode-modified` *only if you patch
affects `php-mode.el`,* which means this step is unnecessary for patches
related to unit tests.
- 4. However, please do not modify `php-mode-version-number`. The maintainers
will decide what constitutes a bump in the version number.
- 5. Open the `php-mode-test.el` file and [run all of the tests] to ensure they
still pass as expected. Sometimes we expect for a test to fail, and those unit
tests have the appropriate configuration so their failure will not raise any
warnings. You can use `make test` script to run all tests from a terminal,
which is also useful in conjunction with [`git bisect run`].
- 6. Send us a pull request here on GitHub.
- 7. Please make your commit messages as detailed as possible. It is better to
be too verbose than to write too little. Look at the commits of the
maintainers to see many examples of the level of detail that we feel is ideal.
Please never assume that your patch is so simple that future developers will be
able to understand the *reason* for the change without comment. And that is
important: your commit message should always strive to answer *"Why"* the patch
exists, *"What*" does it ac [...]
+ 1. Open `php-mode-test.el` and run all the tests to make sure they pass as
expected. You can also check this by running `make test` from the terminal.
+ 2. Please commit with a concise and clear message that effectively achieves a
simple purpose.
+ 3. Submit a pull request here on GitHub.
-If you are fixing a bug related to a GitHub issue, then first of all, thank
you for the help improving PHP Mode. Second, there is a `tests/` directory
which contains PHP scripts for issues (although not all of them). Please
consider adding a test script to that directory that documents the expected
behavior and provides code that allows others to see if said behavior works
properly. Then create a unit test within `php-mode-test.el` using [ERT].
Please try to follow the format of the e [...]
+If you are fixing a bug related to a GitHub issue, then first of all, thank
you for helping to improve PHP Mode. Second, there is a `tests/` directory
that contains PHP scripts for issues (though not all). Please consider adding
a test script to that directory that documents the expected behavior and
provides code that allows others to see if that behavior works properly. Then
create a unit test within `php-mode-test.el' using [ERT]. Try to follow the
format of the existing tests.
### Regression test for Face (en)
@@ -55,17 +61,23 @@ Please contribute.
## Japanese
+### Setup (ja)
+
+パッケージをビルドするにはEaskが必要です。node.jsとnpmからインストールするか、ビルド済み実行ファイルをダウンロードする必要があります。Easkの詳細は[Eask
Introduction][eask-introduction]と[Install Eask][eask-install]をお読みください。
+
+以下のコマンドでテストを実行できます。
+
+```sh
+make test
+```
+
### Guideline (ja)
**Emacs PHP Mode**はどなたからの貢献も歓迎です。改善やバグ修正を行う前に以下の手順を行ってください。
- 1.
あなたの名前が`README.md`の“Contributors”のリストになければ追加してください。あなたの名前とGitHubアカウントや個人サイトをリンクして構いません。
- 2. もし既にissueとして提起された問題に対処するならば、コミットメッセージに`GitHub-Issue: #16`のような行を含めてください。
- 3.
`php-mode.el`に影響する変更をした場合、`php-mode-modified`定数を更新してください。テストやドキュメントのみの修正の場合は不要です。
- 4. しかし、 `php-mode-version-number` は変更しないでください。メンテナがバージョンを決定します。
- 5. `php-mode-test.el`を開いて[すべてのテストを実行][run all of the
tests]し、期待通りにテストを通過することを確認します。端末から`make test`で確認することもでき、[`git bisect
run`]と併用すると便利です。
- 6. GitHubからプルリクエストを送信します
- 7.
可能な限り詳細なコミットメッセージを作成してください。不足するよりも冗長すぎる方が良いです。メンテナーのコミットを参照して、私たちが理想的だと期待するコミットメッセージの詳細度として参考にしてください。シンプルすぎるパッチだからと決めつけずにコミットメッセージを書けば、コード中にコメントを書かなくても将来の開発者がコミットの「理由」「経緯」を理解できるようになります。コミットメッセージには「なぜ」コミットを作成したか、「何を」解決するものなのかを記述することが重要です。メンテナーはほかの開発者のプルリクエストに詳細なコミットメッセージを書き込むことがありますが、常に一貫して行われるとは期待しないでください。
+ 1. `php-mode-test.el`を開いて[すべてのテストを実行][run all of the
tests]し、期待通りにテストを通過することを確認します。端末から`make test`で確認することもできます。
+ 2. 簡潔でシンプルな目的を達成するための、明示的なメッセージでコミットしてください。
+ 3. GitHubからプルリクエストを送信してください。
**GitHubのissueに関連するバグを修正する場合**： PHPモードの改善に協力いただきありがとうございます！
`tests/`ディレクトリには(すべてではありませんが)issueに関連のあるPHPスクリプトが配置されています。そこに予期される挙動と他のひとが動作を適切に確認できるテストコードを追加することを検討してください。そして`php-mode-test.el`に既存のテストと同じように[ERT]を使ったテストコードを追加してください。
@@ -76,7 +88,10 @@ Please contribute.
このテストに必要な`.face`ファイルの生成方法は[How to generate face file]を参考にしてください。
[run all of the tests]:
http://www.gnu.org/software/emacs/manual/html_node/ert/Running-Tests-Interactively.html#Running-Tests-Interactively
-[`git bisect run`]: http://git-scm.com/book/en/Git-Tools-Debugging-with-Git
+[Eask]: https://emacs-eask.github.io/
+[eask-introduction]: https://emacs-eask.github.io/Getting-Started/Introduction/
+[eask-install]: https://emacs-eask.github.io/Getting-Started/Install-Eask/
+[eask-releases]: https://github.com/emacs-eask/cli/releases
[ERT]: http://www.gnu.org/software/emacs/manual/html_node/ert/index.html
[Font Lock]:
https://www.gnu.org/software/emacs/manual/html_node/elisp/Font-Lock-Mode.html
[How to generate face file]:
https://github.com/emacs-php/php-mode/issues/509#issuecomment-491528968
diff --git a/README.ja.md b/README.ja.md
index 1f8767e23e..54b6ba7ddd 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -15,73 +15,55 @@ A powerful and flexible Emacs major mode for editing PHP
scripts
</div>
-[PHP ModeのGitHubプロジェクト][php-mode]にissueを作成してバグ報告や機能リクエストを送ってください。
+[GitHubプロジェクト][php-mode]にissueを作成してバグ報告や機能リクエストを送ってください。
-> **Note**
+> [!NOTE]
> [最新版][releases]のPHP ModeはEmacs 29をサポートしています。<br
> />アップグレードに伴うトラブルは[Discussions][disscussions-emacs29]に気軽に書き込んでください。
[releases]: https://github.com/emacs-php/php-mode/releases
[disscussions-emacs29]: https://github.com/emacs-php/php-mode/discussions/751
-インストール
-------------
+## インストール
-**PHP ModeはEmacs 26.1以降で動作します**。古いバージョンのEmacsでも動作するかもしれませんが、保証外です。
古いバージョンのEmacsのPHPモードを使用することによる問題のバグ報告は積極的に対応しません。現在のサポートポリシーは[Supported
Version]のページをご覧ください。
+**PHP ModeはEmacs 26.1以降で動作します**。対応バージョンの詳細は[Supported Version]をお読みください。Emacs
28以降では単に以下のコマンドを実行するだけでインストールできます。
-### **(推奨)** NonGNU ELPAからのインストール
-
-[![NonGNU ELPA][nongnu-elpa-badge]][nongnu-elpa] [![NonGNU-devel
ELPA][nongnu-devel-elpa-badge]][nongnu-devel-elpa]
-
-Emacs 28 (最新安定版) では[NonGNU
ELPA](https://elpa.nongnu.org/)がデフォルトのパッケージリポジトリとして追加されています。
-
-
-### MELPAからのインストール
-
-[![melpa badge][melpa-badge]][melpa-link] [![melpa stable
badge][melpa-stable-badge]][melpa-stable-link]
-
-GNU Emacs 24以降では、[package][]機能(または[Cask][])を使って[MELPA][]/[MELPA Stable][]からPHP
Modeをインストールできます。
-
-### OSのパッケージマネージャからのインストール
-
-PHP
Modeは[いくつかのOSが提供するパッケージシステム][php-mode-packages]からインストール可能です。DebianおよびUbuntuのようなDebian派生のOSではEmacsにPHPを追加する最も簡単な方法で、`sudo
apt install elpa-php-mode` で導入できます。これらの "Stable" リリースは最新のPHP
Modeよりも古いものの、十分にテストされた固定バージョンが提供されます。オートロードとバイトコンパイルは自動で行われます。
-
-最新のPHP Modeの機能とパフォーマンス改善を活用するために**sid**
("unstable"としても知られるローリングリリース)で提供されるバージョンのインストールを検討してください。最新バージョンは[`elpa-php-mode`][elpa-php-mode]にあります。"apt-pinning"を使ってアップデートを自動化することもできます。
-
-また、[Debian 9 (stretch)][php-elisp-stretch]や[Ubuntu
18.10][php-elisp-ubuntu1810]以前で提供されていた `php-elisp`
パッケージは[あまりにも古い][issue-430]ので、 **くれぐれもインストールしないでください**。
-
-### 手動でインストール
-
-もしパッケージマネージャに依存したくなければ、伝統的な方法によってLispファイルを直接インストールすることもできます。詳細なセットアップ方法は[手動でのインストール][wiki-manual-installation-ja]ページをご覧ください。
+```
+M-x package-install php-mode
+```
-バグを報告する
---------------
+[`package-archives`にMELPAを追加][melpa-getting-started]することで、Web上の多くのパッケージでEmacsを強化できます。
-報告の際には `M-x php-mode-debug` コマンドを実行して、その出力をバグレポートに含めてください。問題を再現するための手がかりになります。
+パッケージマネージャへの依存なしでインストールしたい場合は、Lispファイルを直接配置する伝統的な方法も可能です。詳しくは[Manual
installation][wiki-manual-installation]をお読みください。
-Settings
---------
+## 設定
### 個人設定
-.emacsファイル(`~/.emacs.d/init.el`)にPHPモードでの設定を記述できます。
+.emacsファイル(`~/.emacs.d/init.el`)にPHPモードの設定を記述できます。
```lisp
(defun my-php-mode-init ()
+ (subword-mode 1)
(setq-local show-trailing-whitespace t)
(setq-local ac-disable-faces '(font-lock-comment-face font-lock-string-face))
- (setq-local page-delimiter "\\_<\\(class\\|function\\|namespace\\)\\_>.+$")
+ (add-hook 'hack-local-variables-hook 'php-ide-turn-on nil t))
- ;; If you feel phumped and phpcs annoying, invalidate them.
- (when (boundp 'flycheck-disabled-checkers)
+(with-eval-after-load 'php-mode
+ (add-hook 'php-mode-hook #'my-php-mode-init)
+ (custom-set-variables
+ '(php-mode-coding-style 'psr2)
+ '(php-mode-template-compatibility nil)
+ '(php-imenu-generic-expression 'php-imenu-generic-expression-simple))
+
+ ;; If you find phpcs to be bothersome, you can disable it.
+ (when (require 'flycheck nil)
(add-to-list 'flycheck-disabled-checkers 'php-phpmd)
(add-to-list 'flycheck-disabled-checkers 'php-phpcs)))
-
-(add-hook 'php-mode-hook #'my-php-mode-init)
```
### プロジェクトローカル設定
-プロジェクトのトップディレクトリに`.dir-locals.el`を記述すると、プロジェクト単位の設定を追加することができます。このファイルはユーザー自身のEmacsにインストールされたパッケージに依存するため、バージョン管理の対象に含めないことを推奨します。
+プロジェクトのトップディレクトリに`.dir-locals.el`または`.dir-locals-2.el`を記述すると、プロジェクト単位の設定を追加することができます。このファイルはユーザー自身のEmacsにインストールされたパッケージに依存するため、バージョン管理の対象に含めないことを推奨します。
```lisp
((nil
@@ -89,226 +71,15 @@ Settings
(php-project-coding-style . psr2)))
```
-実験的および作業中の機能
--------------------------------------
-
-### CC Mode, CEDET, EDE, and Semantic
-
-In 2013 Daniel Haxney began rewriting parts of PHP Mode in terms of Emacs'
built-in CC Mode. This laid the foundation for incorporating some of the
inherit IDE-ish features of Emacs, such as CEDET, EDE, and Semantic. Support
for these tools continues to improve thanks to the work of Andrea Turso, Steven
Rémot, Joris Steyn, and others. If you wish to test, contribute to, or simply
experiment with such features then [this thread is a good place to
start](https://github.com/emacs-php/php [...]
-
-### PHP7サポート
-
-PHP7がリリースされました。PHPモードはPHP7からの以下の文法をサポートします。
-
- 1. 返り値の型宣言
- 2. `yield from` キーワード
- 3. `declare(strict_types=1)` 宣言
-
-機能
---------
-
-### 新しいキーワード
-
-現在のPHPモードはトレイト関連の`insteadof`などのPHP5.4で導入された新しいキーワードを構文強調表示します。また、従来のキーワード`clone`や`default`などもサポートします。
-
-### 定数
-
-強調表示には公式のPHPマニュアルに記載があるすべてのマジック定数と定義済み定数が含まれます。ただし、特定の拡張機能の定数は現在のところ含みません。
-
-### トレイト、インターフェイスと名前空間
-
-トレイト、インターフェイス、名前空間がImenuリストに表示されるようになりました。フォント表示は名前空間でも正しく動作するようになり、`namespace
Foo\Bar\Baz`のようなコードはもはや警告されません。`use <namespace> as
<alias>`のような名前空間のエイリアスも同様です。現在のところエイリアス名はImenuのリストには含まれませんが、将来のバージョンでは対応予定です。
-
-### アンダースコアの取り扱い
-
-PHPモードは`$foo_bar_baz`のような変数名の単語のそれぞれの部分を移動できるように、アンダースコア(`_`)を「シンボル構成要素
(symbol constituents)」(Emacs用語)として取り扱います。
-
-### メソッドチェーン呼び出し
-
-複数行にわたるメソッド呼び出しを`->`の位置に揃えること(アライメント)ができます。
-
-```php
-$object->foo()
- ->bar()
- ->baz();
-```
-
-この動作はデフォルトでは無効ですが、カスタマイズ変数 `php-mode-lineup-cascaded-calls` をセットすることで有効化できます。
-
-**注意**: アライメントは、PHPモードのコーディングスタイルのひとつを使用するか、それを継承した場合のみ機能します。
-
-### ネストされた配列の整形
-
-ネストされた関数呼び出しと `array()` 構文は現在デフォルトで(少くとも私の意見では)よく見えるようになりました。例として、このようなスタイルです：
-
-```php
-$results = Post::model()->find(
- array(
- 'select' => 'title',
- 'condition' => 'postID=:postID',
- 'params' => array(':postID' => 10),
- )
-);
-```
-
-### 無名関数
-
-以下のような無名関数
-
-```php
-$greet = function($name) { ... };
-```
-
-これは現在、Imenuで`$greet`として表示します。
-
-### Flymakeサポート
-
-カスタマイズ変数`php-executable`をセットすることで、コーディング中に警告とエラーをリアルタイムで見るためにFlymakeモードを有効にすることができます。
-
-### ローカルのドキュメントを検索する
-
-コマンド`C-c
C-f`でカーソル位置のシンボルをPHP公式サイトのドキュメントから検索できます。また、[ローカルにドキュメントをダウンロード](http://us2.php.net/download-docs.php)してあれば、それを優先します。`php-manual-path`をセットするだけです。もしローカルで発見できなければPHPのWebサイトにフォールバックします。
-
-### 選択範囲内のコードを実行する
-
-`php-send-region`コマンド(デフォルトでは`C-c C-r`)はリージョンで選択された範囲のPHPコードを実行します。`C-x
h`と組合せてコード全体を実行することもできます。出力は `*PHP*` バッファに現れます。
-
-### PHPDoc タグ／アノテーション
-
-PHPDocは[JavaDoc](https://en.wikipedia.org/wiki/Javadoc)に似たドキュメンテーションの形式です。
-
-`@param`, `@return`, `@var`... などの表記は**タグ**と呼ばれ、[list of tags defined by
phpDocumentor2](https://phpdoc.org/docs/latest/references/phpdoc/tags/index.html)で定義されます。
(これらのタグはPhpStormや[Phan](https://github.com/etsy/phan)といった型チェッカーと互換性があります。)
-
-**アノテーション**と呼ばれる記法は部分的にサポートしています。アノテーションの文法はタグとは少し異なり、`@Annotation(attr1="vvv",
attr2="zzz")` のような形式です。
-
-[Symfony](https://symfony.com/)プロジェクトや[Go!
AOP](https://github.com/goaop/framework)などいくつかのプロジェクト・フレームワークは[Doctrine
Annotations](https://www.doctrine-project.org/projects/doctrine-annotations/en/latest/index.html)の文法を元にしています。
-
-```php
-/**
- * Summary of Product class
- *
- * @copyright 2112 John Doe
- * @license https://spdx.org/licenses/Apache-2.0.html Apache License 2.0
- * @ORM\Entity
- * @ORM\Table(name="product")
- */
-class Product
-{
- /**
- * @ORM\Id
- * @ORM\Column(type="integer")
- * @ORM\GeneratedValue(strategy="AUTO")
- */
- protected $id;
-
- /**
- * @ORM\Column(type="string", length=100)
- */
- protected $name;
-
- /**
- * @ORM\Column(type="decimal", scale=2)
- */
- protected $price;
-
- /**
- * @ORM\Column(type="text")
- */
- protected $description;
-}
-```
-
-アノテーションは `@` から始まる行で、わかりやすく強調表示されます。ただしPHPモードは[PSR-5: PHPDoc
(草案)](https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md)の完全なサポートは実装していません。我々は将来的にこれらの強調表示を厳密にサポートしたいと考えていますが、現在の実装は限定的です。詳しくは[#478](https://github.com/emacs-php/php-mode/issues/478)をご覧ください。
-
-### コーディングスタイル
-
-PHPモードはデフォルトでは`php-enable-default-coding-style`関数で設定される合理的なインデントと整形スタイルを提供します。また、ほかの有用なコーディングスタイルも提供しているので、以下の関数を通じて設定することができます。
-
-1. `php-enable-pear-coding-style`
-2. `php-enable-drupal-coding-style`
-3. `php-enable-wordpress-coding-style`
-4. `php-enable-symfony2-coding-style`
-5. `php-enable-psr2-coding-style`
-
-`M-x customize-group <RET> php`で‘PHP Mode Coding
Style’を探してカスタマイズメニューを探して、デフォルトのコーディングスタイルの設定を有効化することができます。以下のように、コーディングスタイルごとにフックを有効化することもできます。
-
-```lisp
-(add-hook 'php-mode-hook 'php-enable-default-coding-style)
-```
-
-#### Symfony2 Style
-
-このスタイルではメソッドチェーンのインデントの継続とぶらさがったセミコロンを整形できます。
-
-
-```php
- $user1
- ->setCreateDate(new \DateTime('2007-05-07 01:34:45'))
- ->setLastDate(new \DateTime('2012-08-18 19:03:02'))
- ->setUsername('jay')
- ;
-```
-
-このスタイルはSymfony2のコードベースで広く利用されていますが、慣習についての文書で明示的に言及されているものではありません。
-
-### HTMLテンプレートのサポートを無効化する
-
-多くの開発者はPHPモードで純粋なPHPスクリプト(HTMLテンプレートを含まないもの)を編集します。HTMLとの互換レイヤーはPHPモードの歴史的な機能ですが、完全には機能していません。速度の低下や強調表示を破壊するおそれがあるなどの副作用があります。変数`php-template-compatibility`を`nil`にセットすると、HTMLとの互換性を無効化することができます。HTMLやその他のマークアップ言語のテンプレートエンジンを含むPHPスクリプトを開発する際は[Web
Mode][]は優れた選択肢です。
-
-### Subword Mode
-
-GNU Emacsには[Subword
Mode][]という機能があり、このマイナーモードは[キャメルケース][camelCase]の部分を別の単語のように移動することができます。たとえば、PHPモードはデフォルトでは変数`$fooBarBaz`を一つの単語として扱います。しかしSubword
Modeを有効にすればEmacsはこの変数名を3つの単語として扱い、単語関係のコマンド(`M-f`, `M-b`,
`M-d`など)はカーソル位置のキャメルケースの各部分に影響します。
-
-もしPHPファイルで常にSubword Modeを有効化したいならば、以下のように設定できます。
-
-```lisp
-(add-hook 'php-mode-hook (lambda () (subword-mode 1)))
-```
-
-キーバインド `C-c C-w` はSubword Modeのオンとオフを切り替えます。
-
-### 現在のclass/namespaceを挿入する
-
-```el
-(with-eval-after-load 'php-mode
- (define-key php-mode-map (kbd "C-c C--") 'php-current-class)
- (define-key php-mode-map (kbd "C-c C-=") 'php-current-namespace))
-```
-
-PHPプログラミングのためのパッケージ
-----------------------------------
-
-- 入力補完
- - [ac-php](https://github.com/xcwen/ac-php):
[company-mode](https://github.com/company-mode/company-mode) and
[auto-complete](https://github.com/auto-complete/auto-complete) for PHP
-- 構文チェック
- - [flycheck](https://github.com/flycheck/flycheck/): On the fly syntax
checker
- - [flymake-php](https://github.com/purcell/flymake-php): flymake for PHP
files
-- スニペット
- - [php-auto-yasnippets](https://github.com/ejmr/php-auto-yasnippets):
Dynamically Generated YASnippets for PHP Code
-- ドキュメント
- - [ggtags](https://github.com/leoliu/ggtags): eldoc by using GNU global tags
- - [php-eldoc](https://github.com/sabof/php-eldoc): eldoc backend for PHP
-- テスト
- - [phpunit](https://github.com/nlamirault/phpunit.el): phpunit test command
tool
-- コーディングスタイル
- - [phpcbf](https://github.com/nishimaki10/emacs-phpcbf): PHP_CodeSniffer for
Emacs
-- Semantic
- - [ede-php-autoload](https://github.com/stevenremot/ede-php-autoload):
Semantic for PHP
-- フレームワーク
- - [cake](https://github.com/k1LoW/emacs-cake): minor-mode for CakePHP
- - [cake2](https://github.com/k1LoW/emacs-cake2): minor-mode for CakePHP2
+## 不具合を報告する
+バグ報告の際には `M-x php-mode-debug` の出力を含めてください。この情報は問題の再現に役立ちます。
貢献するには
-----------------
[CONTRIBUTING.md](CONTRIBUTING.md#japanese)をご覧ください。
-Wiki
---------
-
-GitHubのプロジェクトページには[wiki][]があり、自由に編集して構いません。このWikiには今後追加する計画のある機能やバグが掲載されています。また、PHPモードをより使いやすくするためのTipsを追加できます。
-
## 著作権
PHP Modeは[GNU General Public License Version 3][gpl-v3] (GPLv3) でライセンスされています。
@@ -342,31 +113,14 @@ PHP Modeは[GNU General Public License Version 3][gpl-v3]
(GPLv3) でライセ
[@haxney]: https://github.com/haxney
[@turadg]: https://github.com/turadg
[Authors]: https://github.com/emacs-php/php-mode/wiki/Authors
-[Cask]: https://github.com/cask/cask
[Contributors]: https://github.com/emacs-php/php-mode/graphs/contributors
-[MELPA Stable]: https://stable.melpa.org/
-[MELPA]: https://melpa.org/
-[Subword Mode]:
https://www.gnu.org/software/emacs/manual/html_node/ccmode/Subword-Movement.html
[Supported Version]:
https://github.com/emacs-php/php-mode/wiki/Supported-Version
-[Web Mode]: http://web-mode.org/
-[camelCase]:
https://ja.wikipedia.org/wiki/%E3%82%AD%E3%83%A3%E3%83%A1%E3%83%AB%E3%82%B1%E3%83%BC%E3%82%B9
-[cc mode]: https://www.gnu.org/software/emacs/manual/html_mono/ccmode.html
-[elpa-php-mode]: https://packages.debian.org/sid/elpa-php-mode
[gpl-v3]: https://www.gnu.org/licenses/quick-guide-gplv3.html
-[issue-430]: https://github.com/emacs-php/php-mode/issues/430
-[nongnu-devel-elpa-badge]: https://elpa.nongnu.org/nongnu-devel/php-mode.svg
-[nongnu-devel-elpa]: https://elpa.nongnu.org/nongnu-devel/php-mode.html
[nongnu-elpa-badge]: https://elpa.nongnu.org/nongnu/php-mode.svg
[nongnu-elpa]: https://elpa.nongnu.org/nongnu/php-mode.html
[melpa-badge]: http://melpa.org/packages/php-mode-badge.svg
+[melpa-getting-started]: https://melpa.org/#/getting-started
[melpa-link]: http://melpa.org/#/php-mode
-[melpa-stable-badge]: http://stable.melpa.org/packages/php-mode-badge.svg
-[melpa-stable-link]: http://stable.melpa.org/#/php-mode
-[package]:
https://www.gnu.org/software/emacs/manual/html_node/emacs/Packages.html
-[php-elisp-stretch]: https://packages.debian.org/stretch/php-elisp
-[php-elisp-ubuntu1810]: https://packages.ubuntu.com/cosmic/php-elisp
-[php-mode-packages]: https://repology.org/project/emacs:php-mode/versions
[php-mode]: https://github.com/emacs-php/php-mode
-[php-suite]: https://github.com/emacs-php/php-suite
[wiki]: https://github.com/emacs-php/php-mode/wiki
-[wiki-manual-installation-ja]:
https://github.com/emacs-php/php-mode/wiki/Manual-installation-ja
+[wiki-manual-installation]:
https://github.com/emacs-php/php-mode/wiki/Manual-installation-ja
diff --git a/README.md b/README.md
index 38180d9724..38ef01b082 100644
--- a/README.md
+++ b/README.md
@@ -17,274 +17,68 @@ English | [日本語](README.ja.md)
Please submit any bug reports or feature requests by creating issues on [the
GitHub page for PHP Mode][php-mode].
-> **Note**
+> [!NOTE]
> The [latest version][releases] of PHP Mode supports Emacs 29. <br />Please
> feel free to [write to disucuss][disscussions-emacs29] if you have problems
> upgrading to Emacs 29.
[releases]: https://github.com/emacs-php/php-mode/releases
[disscussions-emacs29]: https://github.com/emacs-php/php-mode/discussions/751
-Installation
-------------
+## Installation
-**PHP Mode works on Emacs 26.1 or later.** PHP Mode may work with older
versions of Emacs but this is not guaranteed. Bug reports for problems related
to using PHP Mode with older versions of Emacs will most like *not* be
addressed.
+**PHP Mode works with Emacs 26.1 or later**. For details on supported
versions, see [Supported Version]. Emacs 28 or later can be installed simply by
running the following command.
-The current support policy can be found on the [Supported Version] page.
-
-### **(RECOMMENDED)** Install from NonGNU ELPA
-
-[![NonGNU ELPA][nongnu-elpa-badge]][nongnu-elpa] [![NonGNU-devel
ELPA][nongnu-devel-elpa-badge]][nongnu-devel-elpa]
-
-Emacs releases since version 28 have included [NonGNU
ELPA](https://elpa.nongnu.org/) as the default package repository.
-
-### Install from MELPA
-
-[![melpa badge][melpa-badge]][melpa-link] [![melpa stable
badge][melpa-stable-badge]][melpa-stable-link]
-
-With GNU Emacs 24 or later then you can use its [package][] feature (or
[Cask][]) to install PHP Mode from [MELPA][] or [MELPA Stable][].
-
-### Install using OS package system
-
-PHP Mode is available from [package systems provided by several
OSs][php-mode-packages]. On Debian, and operating systems derived from it,
such as Ubuntu, the easiest way to add PHP support to Emacs is `sudo apt
install elpa-php-mode`. "Stable" releases of these operating systems include a
well-tested frozen version of this package that is always older than the latest
upstream version of PHP Mode. Autoloads and byte-compilation are automatic.
-
-Please consider installing the package provided in `sid` (aka: "unstable", a
rolling release) in order to benefit from the latest PHP Mode features and
performance improvements. The latest version can be found here:
[`elpa-php-mode`][elpa-php-mode]. Investigate "apt-pinning" to make tracking
this update stream automatic.
-
-### Manual installation
-
-If you don't want to depend on a package manager, you can install Lisp files
directly in the traditional way. See [Manual
installation][wiki-manual-installation] for our recommended setup method.
-
-### Configuration
-
-PHP Mode's default style might not be what you expect. Before filing a bug,
please try the following: `C-h v php-mode-coding-style`, to get the list of
available styles. Then use `M-x php-set-style` for each of these, to check to
see if one of them is to your liking. Use `TODO: Please comment on what config
method you'd like to recommend to users`
-
-Reporting Bugs
---------------
-
-When reporting a bug please run the function `M-x php-mode-debug` and include
its output in your bug report. This helps up reproduce any problem you may
have.
-
-
-Experimental and In-Progress Features
--------------------------------------
-
-### CC Mode, CEDET, EDE, and Semantic
-
-In 2013 Daniel Haxney began rewriting parts of PHP Mode in terms of Emacs'
built-in CC Mode. This laid the foundation for incorporating some of the
inherit IDE-ish features of Emacs, such as CEDET, EDE, and Semantic. Support
for these tools continues to improve thanks to the work of Andrea Turso, Steven
Rémot, Joris Steyn, and others. If you wish to test, contribute to, or simply
experiment with such features then [this thread is a good place to
start](https://github.com/emacs-php/php [...]
-
-### PHP 7 Support
-
-PHP 7 has been released. PHP Mode supports the following features and changes
from PHP 7:
-
-1. Type-hints for return values in functions and methods receive syntax
highlighting in the same way as type-hints for function and method parameters.
-
-2. PHP Mode treats `yield from` as keyword in the same way it already does for
a sole `yield`.
-
-3. It recognizes `strict_types` as a special declaration in the same way as
`ticks`.
-
-
-Features
---------
-
-### New Keywords
-
-Now PHP Mode supports syntax highlighting for new keywords which PHP 5.4
introduced, e.g. those related to traits, such as `insteadof`. Also supported
are the older keywords `clone` and `default`.
-
-### Constants
-
-Syntax highlighting includes every magic constant and predefined constant
listed on the official PHP site. However, some constants from specific
extensions are not currently included.
-
-### Traits, Interfaces, and Namespaces
-
-Traits, interfaces, and namespaces now appear under Imenu listings.
Fontification behaves properly for namespaces as well, so that code like
`namespace Foo\Bar\Baz` no longer looks like a warning. This is also true for
namespace aliases, e.g. `use <namespace> as <alias>`; currently the aliased
name is not listed in Imenu, but future versions will address this.
-
-### Treatment of Underscores
-
-PHP Mode treats underscores as ‘symbol constituents’ (in Emacs terminology) so
that you can use keys like `M-f` and `M-b` to move through the individual parts
of a variable name like `$foo_bar_baz`.
-
-### Chained Method Calls
-
-PHP Mode can align method calls over multiple lines anchored around the `->`
operator, e.g.:
-
-```php
-$object->foo()
- ->bar()
- ->baz();
-```
-
-This behaviour is off by default, but you can customize the variable
`php-mode-lineup-cascaded-calls` to enable this.
-
-**Note:** Alignment will only work if you use one of the php-mode coding
styles or inherit one of the styles.
-
-### Nested Array Formatting
-
-Nested function calls and `array()` structures now look better by default (or
at least in my opinion). Here is an example of the style:
-
-```php
-$results = Post::model()->find(
- array(
- 'select' => 'title',
- 'condition' => 'postID=:postID',
- 'params' => array(':postID' => 10),
- )
-);
```
-
-### Anonymous Functions
-
-Anonymous functions such as
-
-```php
-$greet = function($name) { ... };
-```
-
-will now appear on Imenu; in this case the name will be `$greet`.
-
-### Flymake Support
-
-By customizing the variable `php-executable` you can enable Flymake mode in
order to see warnings and errors in real-time as you write code.
-
-### Search Local Documentation
-
-The key command `C-c C-f` will search the PHP website for documentation on the
word under the cursor. However, if you have a [local copy of the PHP
documentation](http://us2.php.net/download-docs.php) then PHP Mode will try
searching that documentation first. All you need to do is customize the
variable `php-manual-path` and give it the path to your copy of the
documentation. If PHP Mode cannot find something locally then it will still
fallback on searching the PHP website.
-
-### Executing Regions of PHP
-
-The command `php-send-region`, which is bound to `C-c C-r` by default, will
execute the selected region of PHP code. In conjunction with the Emacs command
`C-x h` you can use this to execute an entire file. Any output will appear in
a buffer called `*PHP*`.
-
-### PHPDoc Tag / Annotation Highlighting
-
-PHPDoc is a documentation format similar to
[JavaDoc](https://en.wikipedia.org/wiki/Javadoc).
-
-There are `@param`, `@return`, `@var`... etc in the notation called **tag**,
look at [list of tags defined by
phpDocumentor2](https://phpdoc.org/docs/latest/references/phpdoc/tags/index.html).
(These tags are compatible with static type checkers like PhpStorm and
[Phan](https://github.com/etsy/phan).)
-
-In addition, it also partially supports notation called **annotation**.
Annotation has a slightly different grammar from tag, and the example is
`@Annotation(attr1="vvv", attr2="zzz")`.
-
-[Symfony](https://symfony.com/) project and [Go!
AOP](https://github.com/goaop/framework) and some projects/frameworks use
annotation grammer based on [Doctrine
Annotations](https://www.doctrine-project.org/projects/doctrine-annotations/en/latest/index.html).
-
-```php
-/**
- * Summary of Product class
- *
- * @copyright 2112 John Doe
- * @license https://spdx.org/licenses/Apache-2.0.html Apache License 2.0
- * @ORM\Entity
- * @ORM\Table(name="product")
- */
-class Product
-{
- /**
- * @ORM\Id
- * @ORM\Column(type="integer")
- * @ORM\GeneratedValue(strategy="AUTO")
- */
- protected $id;
-
- /**
- * @ORM\Column(type="string", length=100)
- */
- protected $name;
-
- /**
- * @ORM\Column(type="decimal", scale=2)
- */
- protected $price;
-
- /**
- * @ORM\Column(type="text")
- */
- protected $description;
-}
+M-x package-install php-mode
```
-The annotations are the lines that begin with the `@` character, and PHP Mode
will give these special highlighting to help them stand out.
+By [adding MELPA to `package-archives`][melpa-getting-started], you can extend
Emacs with many packages from the web.
-PHP Mode has not fully supported [PSR-5: PHPDoc
(Draft)](https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md)
yet. We want to support them, but the current implementation still limited.
See issue [#478](https://github.com/emacs-php/php-mode/issues/478) for details.
-
-### Coding Styles
+If you don't want to depend on a package manager, you can install Lisp files
directly in the traditional way. See [Manual
installation][wiki-manual-installation] for our recommended setup method.
-By default PHP Mode tries to provide a reasonable style for indentation and
formatting, which you can use via the function
`php-enable-default-coding-style`. However, it provides other options suited
for particular projects which you may find useful. Other coding styles are
available through these functions:
+## Configuration
-1. `php-enable-pear-coding-style`
-2. `php-enable-drupal-coding-style`
-3. `php-enable-wordpress-coding-style`
-4. `php-enable-symfony2-coding-style`
-5. `php-enable-psr2-coding-style`
+### Personal Settings
-They will help format your code for PEAR/PSR-2 projects, or work on Drupal,
WordPress, and Symfony2 software, respectively. You may enable any of them by
default by running `M-x customize-group <RET> php` and looking for the ‘PHP
Mode Coding Style’ option. You may also enable any of these via a hook, e.g.
+You can add configurations for PHP mode in the .emacs file
(`~/.emacs.d/init.el`):
```lisp
-(add-hook 'php-mode-hook 'php-enable-default-coding-style)
-```
-
-#### Symfony2 Style
-
-With this style method call chains can be formatted with indented continuation
and a hanging semi-colon:
+(defun my-php-mode-init ()
+ (subword-mode 1)
+ (setq-local show-trailing-whitespace t)
+ (setq-local ac-disable-faces '(font-lock-comment-face font-lock-string-face))
+ (add-hook 'hack-local-variables-hook 'php-ide-turn-on nil t))
-```php
- $user1
- ->setCreateDate(new \DateTime('2007-05-07 01:34:45'))
- ->setLastDate(new \DateTime('2012-08-18 19:03:02'))
- ->setUsername('jay')
- ;
+(with-eval-after-load 'php-mode
+ (add-hook 'php-mode-hook #'my-php-mode-init)
+ (custom-set-variables
+ '(php-mode-coding-style 'psr2)
+ '(php-mode-template-compatibility nil)
+ '(php-imenu-generic-expression 'php-imenu-generic-expression-simple))
+
+ ;; If you find phpcs to be bothersome, you can disable it.
+ (when (require 'flycheck nil)
+ (add-to-list 'flycheck-disabled-checkers 'php-phpmd)
+ (add-to-list 'flycheck-disabled-checkers 'php-phpcs)))
```
-This style is used widely throughout Symfony2 source code even if it is not
explicitly mentioned in their conventions documents.
-
-### Avoid HTML Template Compatibility
-
-Many developers use PHP Mode to edit pure PHP scripts (e.g. files with only
PHP and no HTML). A basic compatibility layer with HTML has historically been
part of PHP Mode but it does not work perfectly and can cause some bad side
effects such as slowness and incorrect font locking. Configuring the
`php-template-compatibility` property with a `nil` will cancel any attempt of
HTML compatibility. [Web Mode](http://web-mode.org/) is a great alternative to
PHP Mode if you need to work with [...]
-
-### Subword Mode
-
-GNU Emacs comes with [Subword Mode][], a minor mode that allows you to
navigate the parts of a [camelCase][] as if they were separate words. For
example, PHP Mode treats the variable `$fooBarBaz` as a whole name by default.
But if you enable Subword Mode then Emacs will treat the variable name as three
separate words, and therefore word-related commands (e.g. `M-f`, `M-b`, `M-d`)
will only affect the camelCase part of the name under the cursor.
+### Project Setting
-If you want to always use Subword Mode for PHP files then you can add this to
your Emacs configuration:
+You can add project-specific settings by creating a `.dir-locals.el` or
`.dir-locals-2.el` file in the project's root directory. It is recommended not
to put these files under version control, as they depend on the packages
installed in each user's Emacs.
```lisp
-(add-hook 'php-mode-hook (lambda () (subword-mode 1)))
+((nil
+ (php-project-root . git)
+ (php-project-coding-style . psr2)))
```
-The key-binding `C-c C-w` will also toggle Subword Mode on and off.
+## Reporting Bugs
-### Insert current class/namespace
-
-```el
-(with-eval-after-load 'php-mode
- (define-key php-mode-map (kbd "C-c C--") 'php-current-class)
- (define-key php-mode-map (kbd "C-c C-=") 'php-current-namespace))
-```
+When reporting a bug please run the function `M-x php-mode-debug` and include
its output in your bug report. This helps up reproduce any problem you may
have.
-Other Packages for PHP programming
-----------------------------------
-
-- Completions
- - [ac-php](https://github.com/xcwen/ac-php):
[company-mode](https://github.com/company-mode/company-mode) and
[auto-complete](https://github.com/auto-complete/auto-complete) for PHP
-- Syntax checking
- - [flycheck](https://github.com/flycheck/flycheck/): On the fly syntax
checker
- - [flymake-php](https://github.com/purcell/flymake-php): flymake for PHP
files
-- Snippet
- - [php-auto-yasnippets](https://github.com/ejmr/php-auto-yasnippets):
Dynamically Generated YASnippets for PHP Code
-- Documentation
- - [ggtags](https://github.com/leoliu/ggtags): eldoc by using GNU global tags
- - [php-eldoc](https://github.com/sabof/php-eldoc): eldoc backend for PHP
-- Testing
- - [phpunit](https://github.com/nlamirault/phpunit.el): phpunit test command
tool
-- Style
- - [phpcbf](https://github.com/nishimaki10/emacs-phpcbf): PHP_CodeSniffer for
Emacs
-- Semantic
- - [ede-php-autoload](https://github.com/stevenremot/ede-php-autoload):
Semantic for PHP
-- Framework
- - [cake](https://github.com/k1LoW/emacs-cake): minor-mode for CakePHP
- - [cake2](https://github.com/k1LoW/emacs-cake2): minor-mode for CakePHP2
-
-
-How to Contribute
------------------
+## How to Contribute
Please see [CONTRIBUTING.md](CONTRIBUTING.md#english).
-The Wiki
---------
-
-The GitHub project page has a [wiki][] that you should feel free to edit. The
wiki lists the features and bugs that are on plan to include in upcoming
versions of PHP Mode. It is also a place to add any tips to make the mode more
useful.
## Copyright
@@ -319,28 +113,14 @@ This project was maintained by [Eric James Michael
Ritz][@ejmr] until 2017. Curr
[@haxney]: https://github.com/haxney
[@turadg]: https://github.com/turadg
[Authors]: https://github.com/emacs-php/php-mode/wiki/Authors
-[Cask]: https://github.com/cask/cask
[Contributors]: https://github.com/emacs-php/php-mode/graphs/contributors
-[MELPA Stable]: https://stable.melpa.org/
-[MELPA]: https://melpa.org/
-[Subword Mode]:
https://www.gnu.org/software/emacs/manual/html_node/ccmode/Subword-Movement.html
[Supported Version]:
https://github.com/emacs-php/php-mode/wiki/Supported-Version
-[Web Mode]: http://web-mode.org/
-[camelCase]:
https://ja.wikipedia.org/wiki/%E3%82%AD%E3%83%A3%E3%83%A1%E3%83%AB%E3%82%B1%E3%83%BC%E3%82%B9
-[cc mode]: https://www.gnu.org/software/emacs/manual/html_mono/ccmode.html
-[elpa-php-mode]: https://packages.debian.org/sid/elpa-php-mode
[gpl-v3]: https://www.gnu.org/licenses/quick-guide-gplv3.html
-[nongnu-devel-elpa-badge]: https://elpa.nongnu.org/nongnu-devel/php-mode.svg
-[nongnu-devel-elpa]: https://elpa.nongnu.org/nongnu-devel/php-mode.html
[nongnu-elpa-badge]: https://elpa.nongnu.org/nongnu/php-mode.svg
[nongnu-elpa]: https://elpa.nongnu.org/nongnu/php-mode.html
[melpa-badge]: http://melpa.org/packages/php-mode-badge.svg
+[melpa-getting-started]: https://melpa.org/#/getting-started
[melpa-link]: http://melpa.org/#/php-mode
-[melpa-stable-badge]: http://stable.melpa.org/packages/php-mode-badge.svg
-[melpa-stable-link]: http://stable.melpa.org/#/php-mode
-[package]:
https://www.gnu.org/software/emacs/manual/html_node/emacs/Packages.html
-[php-mode-packages]: https://repology.org/project/emacs:php-mode/versions
[php-mode]: https://github.com/emacs-php/php-mode
-[php-suite]: https://github.com/emacs-php/php-suite
[wiki]: https://github.com/emacs-php/php-mode/wiki
[wiki-manual-installation]:
https://github.com/emacs-php/php-mode/wiki/Manual-installation