PHPDocとは？
PHPDocとはコードに詳細な情報を記述することができる、特別な種類のコメント文です。
これを書くことで下記のメリットがあります。
- 型チェックされる。（予期しない値が渡されないか確認できる）
- IDEで補完が効きやすくなる。
- 静的解析がより正確に実行できる。（PHPStan 等）
タグの説明
-
propaty
各クラスでModelクラスや別クラスを呼びだしている場合に必要。
また、定義しないと未定義のプロパティとなり、アクセスできない。 -
param、return
引数、戻り値の情報を記載するためのタグ。 -
var
変数、オブジェクトのプロパティの情報を記述する。 -
method
クラスのメソッドに関する情報を補足する。
マジックメソッドなどアクセス不可なものを保管する。
（例）findBy、findAllBy等
開発環境
- PHP 7.4.12
- CakePHP 4.2.5
サンプルコード
MainController.php
/**
* ○○デフォルトページ用のコントローラーのファイル
*
* @property \App\Model\Table\ArticlesTable $Articles
*/
class MainController extends AppController
{
/**
* メインページ
*
* @return void
*/
public function index(): void
{
$this->loadModel('Articles');
$date = $this->Articles->findDate(id: 1, inputDate: new FrozenDate());
}
/**
* サンプル
*
* @return void
*/
public function sample(): void
{
try {
/** @var string|false $foo */
$foo = json_encode([1, 2]);
if ($foo === false) {
throw new Exception('Exception発生');
}
/** @var string $foo */
$this->test($foo);
} catch (Exception $e) {
echo $e->getMessage();
}
}
}
ArticlesTable.php
/**
* @method \Cake\ORM\Query findById(int $id)
* @method \Cake\ORM\Query findAllById(int $id)
*/
class ArticlesTable extends AppTable
{
/**
* イニシャライズ
*
* @param array $config コンフィグ
* @return void
*/
public function initialize(array $config): void
{
parent::initialize($config);
$this->setTable('articles');
$this->setEntityClass('App\Model\Entity\Article');
$this->setPrimaryKey('id');
}
/**
* データを取得
*
* @param int $id Id
* @param \Cake\I18n\FrozenDate $inputDate 日付
* @return \App\Model\Entity\Article|null データ
*/
public function findDate(int $id, FrozenDate $inputDate): ?Article
{
return $this->find()
->where([
"{$this->getAlias()}.id" => $id,
"{$this->getAlias()}.input_date" => $inputDate,
])
->first();
}
}
VSCodeでは、このように関数が表示される
最後に
型の指定を明確にすると、可読性が各段と上がるため、
開発の際は、ぜひ活用してみてください。