PHP入門：Attributes（属性）について -vol.4-

よっしー

こんにちは。よっしーです(^^)

今日は、PHPのAttributes（属性）についてご紹介します。

背景
Attributes（属性）クラスの宣言
サンプル1
サンプル2
サンプル3
おわりに

背景

PHP8.2を利用したAPIを開発しているときにAttributes（属性）を利用したので、そのときの調査内容を備忘としてのこしました。

こちらのサイトを参考にしています。

PHP: Attributes - Manual

Attributes（属性）クラスの宣言

属性を使用する際、必ずしも属性用のクラスを作成することは厳密に必要ではありませんが、一般的には推奨されています。最も単純な場合では、空のクラスが必要で、このクラスには #[Attribute] 属性が宣言され、グローバル名前空間から use ステートメントを使用してインポートできます。

このアプローチの利点は、属性が他のコードと分離されているため、コードの整理と理解が容易になります。属性クラスは属性固有のロジックや機能を提供できる場合があり、それが必要な場合に活用できます。

以下は、このアプローチの簡単な例です：

use MyNamespace\MyAttribute; // カスタム属性クラスをインポート

#[MyAttribute]
class MyClass
{
    // クラスの定義
}

このように、カスタム属性クラスを作成し、それを使用することで、属性の利用がより構造化され、コードが見やすくなります。また、カスタム属性クラスにロジックを追加することで、属性がさらに柔軟になることがあります。

サンプル1

<?php

namespace Example;

use Attribute;

#[Attribute]
class MyAttribute
{
}

提供されたPHPコードは、名前空間 Example で定義されたシンプルな属性クラス MyAttribute の例です。この属性クラスは、空のクラスであり、#[Attribute] 属性が付いています。これにより、この属性は他の宣言に適用できるようになります。

この属性クラス MyAttribute はメタデータ情報を提供するための基本的な構造を持ち、他のクラスや関数にメタデータを関連付けるのに使用できます。属性はコードに追加の情報を組み込む手段として非常に強力で、名前空間を使用して属性クラスを区別し、整理することができます。

このシンプルな属性クラスは、他の宣言にメタデータ情報を追加する際に使用する基本のテンプレートとして機能します。属性クラス内には、より高度なロジックや情報を追加することもできます。

サンプル2

アトリビュートが割り当てられる宣言のタイプを制限するには、#[アトリビュート]宣言の第1引数にビットマスクを渡します。

<?php

namespace Example;

use Attribute;

#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION)]
class MyAttribute
{
}

提供されたPHPコードは、名前空間 Example で定義されたカスタム属性クラス MyAttribute の例です。この属性クラスは、属性をメソッドと関数に適用するために Attribute::TARGET_METHOD および Attribute::TARGET_FUNCTION を指定しています。

以下はコードの要点です：

namespace Example;: このコードは Example という名前空間内に配置されています。名前空間を使用することで、クラスや属性が他のコードと衝突しないように隔離されます。
use Attribute;: Attribute クラスを使用するために、グローバルな Attribute クラスを名前空間にインポートしています。これは属性クラスで使用する基本的な属性クラスです。
#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION)]: MyAttribute 属性クラスは Attribute 属性を適用しており、Attribute::TARGET_METHOD および Attribute::TARGET_FUNCTION を指定しています。これにより、この属性はメソッドと関数に適用できます。

このカスタム属性クラス MyAttribute は、メソッドや関数に対してカスタムのメタデータ情報を追加する場合に使用できます。名前空間を使用して属性クラスを隔離することで、名前の衝突を回避し、コードを整理するのに役立ちます。

サンプル3

提供された情報に基づいて、PHPの属性を特定の対象に適用する際のルールについて説明します。

属性の適用対象 (Attribute Targets): 属性は特定の宣言（クラス、関数、メソッド、プロパティ、クラス定数、パラメータ）に適用できます。以下は属性を適用できる対象の一覧です：

Attribute::TARGET_CLASS: クラスに対して属性を適用できます。
Attribute::TARGET_FUNCTION: 関数に対して属性を適用できます。
Attribute::TARGET_METHOD: メソッドに対して属性を適用できます。
Attribute::TARGET_PROPERTY: プロパティに対して属性を適用できます。
Attribute::TARGET_CLASS_CONSTANT: クラス定数に対して属性を適用できます。
Attribute::TARGET_PARAMETER: パラメータに対して属性を適用できます。
Attribute::TARGET_ALL: すべての宣言に属性を適用できます。

属性の繰り返し適用 (Repeatable Attributes): 通常、属性は同一の宣言に対して一度しか適用できません。ただし、同じ属性を同一の宣言に複数回適用したい場合、#[Attribute] 宣言の一部としてビットマスクとして指定することができます。

例えば、繰り返し適用可能な属性を定義する場合、以下のようにビットマスクを指定できます：

use Attribute;

#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION | Attribute::IS_REPEATABLE)]
class MyRepeatableAttribute
{
}

ここで、Attribute::IS_REPEATABLE を指定することで、この属性を同一の宣言に複数回適用できるようになります。

属性の適用対象や繰り返し適用に関するルールに従って、属性を柔軟に使用できます。これにより、メタデータ情報をさまざまな宣言に関連付けることが可能となり、コードの柔軟性が向上します。

<?php

namespace Example;

use Attribute;

#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION | Attribute::IS_REPEATABLE)]
class MyAttribute
{
}