【PHP8.x】valueプロパティの使い方

Copy
1<?php
2
3/**
4 * Dom\AdjacentPosition の値に基づいて、特定の操作を実行しようとします。
5 * この関数は、Dom\AdjacentPosition の値が特定の要件を満たさない場合に ValueError をスローする例を示します。
6 *
7 * Dom\AdjacentPosition は、DOMノードの挿入位置を示す組み込みのクラスです。
8 * その `value` プロパティは、位置に対応する整数値（1〜4）を返します。
9 * `value` プロパティ自体は常に有効な整数を返すため、直接 ValueError は発生しませんが、
10 * その `value` を使用するロジックで無効な値として扱われる場合に ValueError をスローできます。
11 *
12 * @param Dom\AdjacentPosition $position DOMの挿入位置を示すオブジェクト
13 * @return string 処理結果メッセージ
14 * @throws ValueError 指定された位置の値が許可されていない場合
15 */
16function performDomOperation(Dom\AdjacentPosition $position): string
17{
18    // Dom\AdjacentPosition オブジェクトから、対応する整数値を取得します。
19    // この $positionValue は、1 (BeforeBegin), 2 (AfterBegin), 3 (BeforeEnd), 4 (AfterEnd) のいずれかです。
20    $positionValue = $position->value;
21
22    // ここでは、ビジネスロジックとして「BeforeBegin (1)」と「AfterEnd (4)」のみを許可すると仮定します。
23    // それ以外の値（AfterBegin (2) や BeforeEnd (3)）が渡された場合は、無効な値として扱います。
24    // ValueError は、引数の型は正しいが、その値が期待される範囲外やセット外である場合にスローされます。
25    if ($positionValue !== Dom\AdjacentPosition::BeforeBegin->value &&
26        $positionValue !== Dom\AdjacentPosition::AfterEnd->value) {
27        // 無効な値が渡されたため、ValueError をスローします。
28        throw new ValueError(
29            sprintf(
30                'Unsupported Dom\AdjacentPosition value: %d. Only %d (BeforeBegin) or %d (AfterEnd) are allowed for this operation.',
31                $positionValue,
32                Dom\AdjacentPosition::BeforeBegin->value,
33                Dom\AdjacentPosition::AfterEnd->value
34            )
35        );
36    }
37
38    // 許可された値の場合の処理
39    switch ($positionValue) {
40        case Dom\AdjacentPosition::BeforeBegin->value:
41            return "Operation performed successfully: Inserting element BeforeBegin (value: {$positionValue}).";
42        case Dom\AdjacentPosition::AfterEnd->value:
43            return "Operation performed successfully: Inserting element AfterEnd (value: {$positionValue}).";
44        default:
45            // 上記のif文でValueErrorがスローされるため、このケースには通常到達しません。
46            return "Unexpected position (value: {$positionValue}).";
47    }
48}
49
50// --- サンプルコードの実行 ---
51
52echo "--- Valid Cases ---\n";
53
54// 1. 許可された位置 (BeforeBegin) で関数を呼び出す例
55try {
56    $result = performDomOperation(Dom\AdjacentPosition::BeforeBegin);
57    echo $result . "\n";
58} catch (ValueError $e) {
59    echo "Caught ValueError: " . $e->getMessage() . "\n";
60}
61
62// 2. 許可された別の位置 (AfterEnd) で関数を呼び出す例
63try {
64    $result = performDomOperation(Dom\AdjacentPosition::AfterEnd);
65    echo $result . "\n";
66} catch (ValueError $e) {
67    echo "Caught ValueError: " . $e->getMessage() . "\n";
68}
69
70echo "\n--- Invalid Cases (will throw ValueError) ---\n";
71
72// 3. 許可されていない位置 (AfterBegin) で関数を呼び出し、ValueError を発生させる例
73try {
74    $result = performDomOperation(Dom\AdjacentPosition::AfterBegin); // value: 2
75    echo $result . "\n";
76} catch (ValueError $e) {
77    echo "Caught ValueError: " . $e->getMessage() . "\n";
78}
79
80// 4. 許可されていない別の位置 (BeforeEnd) で関数を呼び出し、ValueError を発生させる例
81try {
82    $result = performDomOperation(Dom\AdjacentPosition::BeforeEnd); // value: 3
83    echo $result . "\n";
84} catch (ValueError $e) {
85    echo "Caught ValueError: " . $e->getMessage() . "\n";
86}
87

PHP 8のDom\AdjacentPositionクラスは、ウェブページの構造（DOM）を操作する際に、新しい要素をどこに挿入するかを示すための組み込みクラスです。このクラスのvalueプロパティは、その挿入位置に対応する整数値を返します。具体的には、BeforeBeginが1、AfterBeginが2、BeforeEndが3、AfterEndが4といった数値です。

サンプルコードのperformDomOperation関数は、Dom\AdjacentPosition型のオブジェクトを引数に受け取ります。この関数は、引数で渡されたオブジェクトのvalueプロパティから整数値を取得し、その値に基づいて特定の操作を実行します。この例では、ビジネスロジックとしてBeforeBegin（値1）とAfterEnd（値4）のみを許可しています。

もし引数で許可されていない位置、例えばAfterBegin（値2）やBeforeEnd（値3）が渡された場合、関数はValueErrorをスローします。ValueErrorは、関数の引数の型は正しいものの、その値が期待される範囲やセットに含まれない場合に発生するPHPの例外です。このようにvalueプロパティで取得した値をチェックし、ビジネスルールに反する場合にValueErrorをスローすることで、無効なデータによる処理の続行を防ぎ、堅牢なプログラムを作成できます。関数は処理結果を示す文字列を返し、ValueErrorが発生した場合は、呼び出し元でエラーを捕捉して対処する必要があります。

Copy
1<?php
2
3/**
4 * Dom\AdjacentPosition クラスの `value` プロパティの使用例を示す関数です。
5 *
6 * Dom\AdjacentPosition は、DOM操作における要素の隣接位置（例: 要素の前、要素内の一番初めなど）
7 * を表すための組み込みクラスです。PHP 8 以降で利用可能です。
8 * このクラスの静的プロパティ（例: Dom\AdjacentPosition::BeforeBegin）は、
9 * Dom\AdjacentPosition のインスタンスを返します。
10 * そのインスタンスが持つ `value` プロパティは、対応する整数値を返します。
11 * これは、特定の値を持つオブジェクト（Value Object）の一種として理解できます。
12 */
13function demonstrateDomAdjacentPositionValue(): void
14{
15    // Dom\AdjacentPosition::BeforeBegin は、現在の要素の直前を表す定数です。
16    // この定数にアクセスすると、Dom\AdjacentPosition のインスタンスが返されます。
17    $positionBeforeBegin = Dom\AdjacentPosition::BeforeBegin;
18
19    // Dom\AdjacentPosition::AfterEnd は、現在の要素の直後を表す定数です。
20    $positionAfterEnd = Dom\AdjacentPosition::AfterEnd;
21
22    // 取得した Dom\AdjacentPosition インスタンスの `value` プロパティにアクセスします。
23    // このプロパティは、その位置に対応する整数値を返します。
24    $valueBeforeBegin = $positionBeforeBegin->value;
25    $valueAfterEnd = $positionAfterEnd->value;
26
27    // 結果を出力して、それぞれの位置がどのような整数値に対応しているかを確認します。
28    echo "Dom\\AdjacentPosition::BeforeBegin の値: " . $valueBeforeBegin . "\n";
29    echo "Dom\\AdjacentPosition::AfterEnd の値: " . $valueAfterEnd . "\n";
30
31    // `value` プロパティが実際に整数型であることも確認できます。
32    echo "Dom\\AdjacentPosition::BeforeBegin->value の型: " . gettype($valueBeforeBegin) . "\n";
33    echo "Dom\\AdjacentPosition::AfterEnd->value の型: " . gettype($valueAfterEnd) . "\n";
34
35    // これらの整数値は、DOM操作（例: insertAdjacentElement() メソッドなど）で
36    // 要素を挿入する際の位置指定に内部的に使用されます。
37}
38
39// 関数を実行して、サンプルコードの動作を確認します。
40demonstrateDomAdjacentPositionValue();

PHP 8で導入されたDom\AdjacentPositionクラスは、Webページの構造（DOM）を操作する際に、新しい要素をどこに挿入するかといった「隣接する位置」を表す組み込みクラスです。このクラスはBeforeBeginやAfterEndのような静的プロパティを持っており、これらにアクセスするとDom\AdjacentPositionクラスのインスタンスが返されます。

サンプルコードでは、まずDom\AdjacentPosition::BeforeBeginとDom\AdjacentPosition::AfterEndという静的プロパティから、それぞれの位置を表すインスタンスを取得しています。次に、これらのインスタンスが持つvalueプロパティにアクセスすることで、その位置に対応する整数値を取得できます。このvalueプロパティは引数を取らず、常にint型の整数値を返します。

実行結果として、BeforeBeginとAfterEndがそれぞれ異なる整数値（例: 1, 4など）に対応していること、そしてその値が確かに整数型であることが確認できます。これらの整数値は、insertAdjacentElement()のようなDOM操作メソッドが内部的に位置を指定する際に利用されるもので、Dom\AdjacentPositionインスタンスは、これらの意味のある整数値をオブジェクトとして表現する「Value Object」の一種として機能します。