アノテーション

Flexagon は実行時に PHPDoc タグを読み取り、動作を変更します（PhpDocUtil）。

正式な表記は snake_case です。

/** @encrypt */
/** @db_auto_timestamp insert|update */
/** @exclude_from_get_array */

タグ名では大文字・小文字と区切り文字が区別されません。次の表記はすべて同じ意味になります。

@db_auto_timestamp    @DbAutoTimestamp    @DB_AUTO_TIMESTAMP    @dbautotimestamp

タグの値は大文字・小文字を区別しませんが、区切り文字は区別されます（insert = INSERT ですが、my_value ≠ myvalue です）。

1 行の docblock（/** @db_auto_timestamp insert */）と複数行の docblock のどちらにも対応しています。

@db_auto_timestamp#

INSERT と UPDATE の際に Unix タイムスタンプを自動で設定します。BaseModel の createdAt と updatedAt にはすでに適用されています。

/**
 * @var int|null
 * @db_auto_timestamp insert
 */
protected ?int $createdAt = null;

/**
 * @var int|null
 * @db_auto_timestamp insert|update
 */
protected ?int $updatedAt = null;

@encrypt#

プロパティを AES-256-CBC で自動的に暗号化・復号します。値はデータベースに保存される前に暗号化され、クエリ結果がオブジェクトにマッピングされる際に復号されます。

暗号文の形式は base64(version || IV || HMAC-SHA256 || ciphertext) です。IV は鍵付き HMAC によって平文から導出される合成 IV であるため、同じ平文からは常に同じ暗号文が生成され、暗号化されたカラムも WHERE col = :COL で照合できます（その代わり、データベース上では同じ値を持つ行同士が同じであると判別できてしまいます）。復号の前には hash_equals() で HMAC を検証し、改ざんされたデータを拒否します。暗号化キーと認証キーは、hash_hkdf() を使ってパスフレーズからそれぞれ別々に導出されます。

/**
 * @var string
 * @encrypt
 */
private string $residentNumber = '';

_Global::$CLASS_PROPERTY_ENCRYPTION_PASSPHRASE は 10 文字以上である必要があり、満たさない場合は例外がスローされます。データベースのカラムには、暗号文を格納できる十分なサイズを確保してください。

@exclude_from_get_array#

ゲッターを getArray() / getJson() の出力から除外します。パスワードハッシュのように、シリアライズすべきでない値に使用します。

/**
 * @exclude_from_get_array
 */
public function getPasswordHash(): string { return $this->passwordHash; }

getArray(forceAll: true) を呼び出すと、除外指定を無視してすべての値を返します。DAO はデータベースへの書き込み時に、内部でこのモードを使用します。

アノテーションの完全な一覧、制約、独自アノテーションの定義方法については、ANNOTATIONS.md を参照してください。