a-blog cms PHP API Reference

Field
in package

Application

PHP8.2対応以前にシリアライズされたFieldオブジェクトをデシリアライズすると、 PHP8.2以上の環境でエラーが発生するため、 #[\AllowDynamicProperties] を付与している。

#[AllowDynamicProperties]

Properties

$_aryChild : array<string, Field>
$_aryField : array<string, array<string|int, mixed>>
$_aryMeta : array<string, array<string|int, mixed>>

Methods

__construct() : mixed: constructor
add() : bool: alias for addField
addChild() : true: 指定した名前の子フィールドを設定する
addField() : bool: 指定したフィールド名のフィールドに値を追加する
addGroupRow() : void: グループに 1 行追加する。
boolean() : bool|null: 真偽値に変換して取得する（a-blog cms 慣用）。 - true 扱い : 'on' / '1' / 'true' / 'yes'（大小無視） - false 扱い: 'off' / '0' / 'false' / 'no' / ''（空文字） - キー不在・上記以外 : デフォルト
cloneWith() : static: 指定したフィールドをコピーして、新しいオブジェクトを生成します。
convertValueType() : mixed: '@' で始まる単一値などをひとまとめにせず純粋な値だけを型変換する。
defineGroup() : void: グループに属するフィールド名のリストを宣言する。 '@$groupName' キーに上書きする。既存のフィールドの値はそのまま残る。
delete() : bool: alias for deleteField
deleteField() : bool: 指定したフィールド名のフィールドを削除する
deleteGroup() : void: グループと、それに属する全フィールドを削除する。宣言外のフィールドには触らない。
deleteGroupRow() : void: グループの指定インデックスの行を削除し、後続行を前へ詰める。
dig() : Field: 指定されたスコープ名に基づいてフィールド構造を深掘りし、関連するフィールドデータを整理します。
float() : float|null: 浮動小数点数に変換して取得する。数値文字列でなければデフォルト。
fromArray() : static: toArray() の逆変換。Field::fromArray() は class キーで復元先クラスを選ぶ。サブクラスの fromArray() は呼び出されたクラスでインスタンスを生成し、内部状態を復元する。
get() : T is string ? string : false): 指定したフィールド名の値を取得するフィールド名に文字列以外を指定した場合はfalseを返す
getArray() : array<string|int, mixed>: 指定したフィールド名の値を配列で取得する
getChild() : Field: 指定した名前の子フィールドを取得する
getGroupRows() : array<int, array<string, mixed>>: グループの全行を連想配列の配列として返す。
getMeta() : T is non-empty-string ? mixed : array): 指定したフィールド名のフィールドに設定されたメタ情報を取得する $keyを指定しない場合は、指定したフィールド名のメタ情報すべてを配列で返す
integer() : int|null: 整数に変換して取得する。数値文字列でなければデフォルト。先頭 0 や指数表記も int 化されるため、電話番号・郵便番号は string() を使うこと。
isChildExists() : bool: 指定した名前の子フィールドが存在するかどうかを判定する名前を指定しない場合は、子フィールドが一つも存在しない場合にtrueを返す
isExists() : bool: 指定した名前のフィールドが存在するかどうかを判定する
isGroup() : bool: 指定したフィールド名のフィールドがフィールドグループかどうかを判定する
isGroupKey() : bool: '@' で始まる「グループ宣言キー」かどうかを判定する。
isNull() : bool: 指定したフィールド名のフィールドがnullかどうかを判定する $fdにnullを指定した場合は、フィールドが一つも存在しない場合にtrueを返す
listChildren() : array<string|int, string>: 子フィールド名を列挙する
listFields() : array<string|int, string>: フィールド名を列挙する
listGroupFields() : array<string|int, string>: 指定したグループに属するフィールド名のリストを返す。未宣言の場合は空配列。
listGroupNames() : array<string|int, string>: このフィールドに宣言されているグループ名の配列を返す。 '@xxx' キーの 'xxx' 部分を返す。
overload() : void: オブジェクトを上書きする
parse() : void: フィールドクエリを解析する
parseMultiFieldKey() : array{0: string, 1: string}|null: 'image@path' のような `baseName@subKey` 形式のキーを分解する。形式に合致しない場合は null。グループ宣言キー（'@xxx'）も null を返す。
removeChild() : true: 指定した名前の子フィールドを削除する
reset() : true
retouchCustomUnit() : void: カスタムユニットのフィールド名と値を調整します。
serialize() : string: シリアライズされた文字列を返す
set() : bool: フィールドの値を設定する
setField() : bool: フィールドの値を設定する
setGroupRows() : void: グループの全行を一括差し替えする。
setMeta() : true: 指定したフィールド名のフィールドにメタ情報を設定する
singleton() : Field: シングルトンパターンでオブジェクトを生成する
string() : string|null: 文字列として取得する。値が無ければデフォルト。
toArray() : array<string, mixed>: Field の内部状態を「シリアライゼーション用」の構造化配列にダンプする。
toStructured() : array<string, mixed>: Field の内部状態を、扱いやすい構造化配列に変換する。
updateGroupRow() : void: グループの指定インデックスの行を $row で置き換える。
restoreFromArray() : static: fromArray() の復元処理本体。class キーによるディスパッチは行わない。
buildGroupRows() : array<int, array<string, mixed>>: グループに属するキー群から行配列を組み立てる。
buildMultiEntry() : array<string, mixed>: マルチ項目フィールド（baseName@subKey 形式）のエントリを組み立てる。
buildSingleEntry() : array<string, mixed>: 単一値フィールドのエントリを組み立てる。
partitionFieldKeys() : array{0: string[], 1: array}: フィールドキーのリストを「単一値」「マルチ項目（baseName 別）」に分類する。
rawScalar() : string|null: 指定フィールドの生の文字列値を返す。値が無い / 空文字 / 配列なら null。型付きアクセサ共通の「値あり判定」に使う（boolean だけは空文字を別扱いするため使わない）。
resolveClassFromArray() : string: 配列内の 'class' キーから復元先の Field 系クラスを解決する。 class キー未指定なら Field として復元。

$_aryChild


        public
            array<string, Field>
    $_aryChild
     = []

$_aryField


        public
            array<string, array<string|int, mixed>>
    $_aryField
     = []

$_aryMeta


        public
            array<string, array<string|int, mixed>>
    $_aryMeta
     = []

__construct()

constructor


    public
        final            __construct([Field|array<string, mixed>|string|null $Field = null ][, bool $isDeep = false ]) : mixed

Parameters

$Field : Field|array<string, mixed>|string|null = null
$isDeep : bool = false

add()

alias for addField


    public
                    add(string $fd, array<string|int, mixed>|string|int|float|null $vals) : bool

Parameters

$fd : string: フィールド名
$vals : array<string|int, mixed>|string|int|float|null

Return values

bool

addChild()

指定した名前の子フィールドを設定する


    public
                    addChild(string $name, Field &$Field) : true

Parameters

$name : string
$Field : Field

Return values

true

addField()

指定したフィールド名のフィールドに値を追加する


    public
                    addField(string $fd, array<string|int, mixed>|string|int|float|null $vals) : bool

Parameters

$fd : string: フィールド名
$vals : array<string|int, mixed>|string|int|float|null

Return values

bool

addGroupRow()

グループに 1 行追加する。


    public
                    addGroupRow(string $groupName, array<string, mixed> $row) : void

グループ未宣言なら $row のキー順で自動的に宣言する。 $row に宣言外のキーが含まれていれば InvalidArgumentException。

Parameters

$groupName : string
$row : array<string, mixed>

boolean()

真偽値に変換して取得する（a-blog cms 慣用）。 - true 扱い : 'on' / '1' / 'true' / 'yes'（大小無視） - false 扱い: 'off' / '0' / 'false' / 'no' / ''（空文字） - キー不在・上記以外 : デフォルト


    public
                    boolean(string $fd[, bool|null $default = null ][, int $i = 0 ]) : bool|null

Parameters

$fd : string
$default : bool|null = null
$i : int = 0

Return values

bool|null

cloneWith()

指定したフィールドをコピーして、新しいオブジェクトを生成します。


    public
                    cloneWith(array<string|int, string> $fieldNames) : static

Parameters

$fieldNames : array<string|int, string>

Return values

static

convertValueType()

'@' で始まる単一値などをひとまとめにせず純粋な値だけを型変換する。


    public
            static        convertValueType(mixed $value) : mixed

空文字 / null → null
文字列 "true" / "false"（大小文字無視）→ bool
数値文字列 → int / float（先頭 0 で 2 文字以上は電話番号・郵便番号扱いで文字列保持）
それ以外 → 元の値をそのまま返す

Parameters

$value : mixed

defineGroup()

グループに属するフィールド名のリストを宣言する。 '@$groupName' キーに上書きする。既存のフィールドの値はそのまま残る。


    public
                    defineGroup(string $groupName, array<string|int, string> $fieldNames) : void

Parameters

$groupName : string
$fieldNames : array<string|int, string>

delete()

alias for deleteField


    public
                    delete(string $fd) : bool

Parameters

$fd : string

Return values

bool

deleteField()

指定したフィールド名のフィールドを削除する


    public
                    deleteField(string $fd) : bool

Parameters

$fd : string

Return values

bool

deleteGroup()

グループと、それに属する全フィールドを削除する。宣言外のフィールドには触らない。


    public
                    deleteGroup(string $groupName) : void

Parameters

$groupName : string

deleteGroupRow()

グループの指定インデックスの行を削除し、後続行を前へ詰める。


    public
                    deleteGroupRow(string $groupName, int $index) : void

インデックスは getGroupRows() のビュー（最大長に揃えた行配列）に対応する。範囲外のインデックスなら OutOfBoundsException。グループ宣言（@$groupName）自体は残し、行を全削除した場合は各宣言フィールドが空になる。

Parameters

$groupName : string
$index : int

dig()

指定されたスコープ名に基づいてフィールド構造を深掘りし、関連するフィールドデータを整理します。


    public
                &    dig([string $scp = 'field' ]) : Field

指定されたスコープ名の子フィールドを生成または取得し、そのスコープ内で定義されているフィールドの値を元フィールドから新しい子フィールドに追加します。返り値として、新しい子フィールドを返します。

Parameters

$scp : string = 'field': スコープ名

Return values

Field —

新たに生成された子フィールドの参照を返す

float()

浮動小数点数に変換して取得する。数値文字列でなければデフォルト。


    public
                    float(string $fd[, float|null $default = null ][, int $i = 0 ]) : float|null

Parameters

$fd : string
$default : float|null = null
$i : int = 0

Return values

float|null

fromArray()

toArray() の逆変換。Field::fromArray() は class キーで復元先クラスを選ぶ。サブクラスの fromArray() は呼び出されたクラスでインスタンスを生成し、内部状態を復元する。


    public
            static        fromArray(array<string, mixed> $data) : static

Parameters

$data : array<string, mixed>

Return values

static

get()

指定したフィールド名の値を取得するフィールド名に文字列以外を指定した場合はfalseを返す


    public
                    get(T $fd[, string|int|null $def = null ][, int $i = 0 ]) : T is string ? string : false)

Parameters

$fd : T
$def : string|int|null = null
$i : int = 0

Return values

T is string ? string : false)

getArray()

指定したフィールド名の値を配列で取得する


    public
                    getArray(string $fd[, bool $strict = false ]) : array<string|int, mixed>

Parameters

$fd : string
$strict : bool = false: falseの場合、空文字、null、フィールドグループを削除した配列を返す。デフォルトはfalse

Return values

array<string|int, mixed>

getChild()

指定した名前の子フィールドを取得する


    public
                &    getChild(string $name) : Field

Parameters

$name : string

Return values

Field

getGroupRows()

グループの全行を連想配列の配列として返す。


    public
                    getGroupRows(string $groupName[, bool $autoConvert = false ]) : array<int, array<string, mixed>>

フィールドごとに長さがズレている場合は最大長に合わせ、足りない値は空文字で埋める。 $autoConvert が true なら convertValueType() で型変換を適用する。

Parameters

$groupName : string
$autoConvert : bool = false

Return values

array<int, array<string, mixed>>

getMeta()

指定したフィールド名のフィールドに設定されたメタ情報を取得する $keyを指定しない場合は、指定したフィールド名のメタ情報すべてを配列で返す


    public
                    getMeta(string $fd[, T $key = null ]) : T is non-empty-string ? mixed : array)

Parameters

$fd : string: フィールド名
$key : T = null: メタ情報のキー

Return values

T is non-empty-string ? mixed : array)

integer()

整数に変換して取得する。数値文字列でなければデフォルト。先頭 0 や指数表記も int 化されるため、電話番号・郵便番号は string() を使うこと。


    public
                    integer(string $fd[, int|null $default = null ][, int $i = 0 ]) : int|null

Parameters

$fd : string
$default : int|null = null
$i : int = 0

Return values

int|null

isChildExists()

指定した名前の子フィールドが存在するかどうかを判定する名前を指定しない場合は、子フィールドが一つも存在しない場合にtrueを返す


    public
                    isChildExists([string|null $name = null ]) : bool

Parameters

$name : string|null = null

Return values

bool

isExists()

指定した名前のフィールドが存在するかどうかを判定する


    public
                    isExists(string $fd[, int|null $i = null ]) : bool

Parameters

$fd : string
$i : int|null = null

Return values

bool

isGroup()

指定したフィールド名のフィールドがフィールドグループかどうかを判定する


    public
                    isGroup(string $fd) : bool

Parameters

$fd : string

Return values

bool

isGroupKey()

'@' で始まる「グループ宣言キー」かどうかを判定する。


    public
            static        isGroupKey(string $key) : bool

Parameters

$key : string

Return values

bool

isNull()

指定したフィールド名のフィールドがnullかどうかを判定する $fdにnullを指定した場合は、フィールドが一つも存在しない場合にtrueを返す


    public
                    isNull([string|null $fd = null ][, int $i = 0 ]) : bool

Parameters

$fd : string|null = null
$i : int = 0

Return values

bool

listChildren()

子フィールド名を列挙する


    public
                    listChildren() : array<string|int, string>

Return values

array<string|int, string>

listFields()

フィールド名を列挙する


    public
                    listFields() : array<string|int, string>

Return values

array<string|int, string>

listGroupFields()

指定したグループに属するフィールド名のリストを返す。未宣言の場合は空配列。


    public
                    listGroupFields(string $groupName) : array<string|int, string>

Parameters

$groupName : string

Return values

array<string|int, string>

listGroupNames()

このフィールドに宣言されているグループ名の配列を返す。 '@xxx' キーの 'xxx' 部分を返す。


    public
                    listGroupNames() : array<string|int, string>

Return values

array<string|int, string>

overload()

オブジェクトを上書きする


    public
                    overload(Field|array<string, mixed>|string $Field[, bool $isDeep = false ]) : void

Parameters

$Field : Field|array<string, mixed>|string
$isDeep : bool = false

parse()

フィールドクエリを解析する


    public
                    parse(string $query) : void

Parameters

$query : string

parseMultiFieldKey()

'image@path' のような `baseName@subKey` 形式のキーを分解する。形式に合致しない場合は null。グループ宣言キー（'@xxx'）も null を返す。


    public
            static        parseMultiFieldKey(string $key) : array{0: string, 1: string}|null

Parameters

$key : string

Return values

array{0: string, 1: string}|null

removeChild()

指定した名前の子フィールドを削除する


    public
                    removeChild(mixed $name) : true

Parameters

$name : mixed

Return values

true

reset()


    public
                    reset([bool $isDeep = false ]) : true

Parameters

$isDeep : bool = false: 非推奨の引数です。使用しないでください。

Return values

true

retouchCustomUnit()

カスタムユニットのフィールド名と値を調整します。


    public
                    retouchCustomUnit([string $id = '' ]) : void

フィールド名と値のペアを走査し、フィールド名に指定されたIDが含まれている場合に、そのIDを除去して新しいフィールド名として設定します。IDがフィールド値にも含まれている場合（フィールド名が'@'で始まる場合）、値に対しても同様の処理を行います。

処理の結果、フィールド名からIDが除去された新しい配列が_aryFieldプロパティに設定されます。また、メタデータを格納する_aryMetaプロパティは空の配列にリセットされます。

Parameters

$id : string = '': ユニットID。デフォルトは空文字列です。

serialize()

シリアライズされた文字列を返す


    public
                    serialize() : string

Return values

string

set()

フィールドの値を設定する


    public
                    set(string $fd[, array<string|int, mixed>|string|int|float|null $vals = null ]) : bool

Parameters

$fd : string: フィールド名
$vals : array<string|int, mixed>|string|int|float|null = null

Return values

bool

setField()

フィールドの値を設定する


    public
                    setField(string $fd[, array<string|int, mixed>|string|int|float|null $vals = null ]) : bool

Parameters

$fd : string: フィールド名
$vals : array<string|int, mixed>|string|int|float|null = null

Return values

bool

setGroupRows()

グループの全行を一括差し替えする。


    public
                    setGroupRows(string $groupName, array<int, array<string, mixed>> $rows) : void

グループ未宣言で $rows が空でない場合、先頭行のキー順で自動的に宣言する。各行に宣言外のキーが含まれていれば InvalidArgumentException。

Parameters

$groupName : string
$rows : array<int, array<string, mixed>>

setMeta()

指定したフィールド名のフィールドにメタ情報を設定する


    public
                    setMeta(string $fd[, string|null $key = null ][, mixed $val = null ]) : true

Parameters

$fd : string: フィールド名
$key : string|null = null: メタ情報のキー
$val : mixed = null: メタ情報の値

Return values

true

singleton()

シングルトンパターンでオブジェクトを生成する


    public
            static    &    singleton(string $key[, null|Field $Field = null ]) : Field

Parameters

$key : string
$Field : null|Field = null

Return values

Field

string()

文字列として取得する。値が無ければデフォルト。


    public
                    string(string $fd[, string|null $default = null ][, int $i = 0 ]) : string|null

Parameters

$fd : string
$default : string|null = null
$i : int = 0

Return values

string|null

toArray()

Field の内部状態を「シリアライゼーション用」の構造化配列にダンプする。


    public
                    toArray() : array<string, mixed>

fromArray() でビット等価に復元できる形式。永続化・転送・JSON 化など、 Field をそのまま「保存して後から復元したい」用途で使う。人間可読な表示用には toStructured() を使うこと。

class : ダンプ元のクラス名（fromArray() のディスパッチに使う）
fields : _aryField の生の値（@groupName キーや baseName@subKey 形式の生キーを保持）
children : 子フィールドを再帰的にダンプ（class キーで型情報も保持）
meta : _aryMeta の値

Return values

array<string, mixed>

toStructured()

Field の内部状態を、扱いやすい構造化配列に変換する。


    public
                    toStructured([bool $autoConvert = true ][, bool $withValidation = false ][, bool $recursive = true ]) : array<string, mixed>

テンプレート描画・V2 API レスポンス・デバッグ表示など、人間が読み書きする用途で使う。永続化やラウンドトリップ復元には向かないため、その用途では toArray() / fromArray() を使うこと。

単一値フィールド : ['value' => x, 'array' => [...]]
マルチ項目フィールド : ['value' => ['sub' => x, ...], 'array' => [['sub' => x, ...], ...]] （baseName@subKey 形式が同じ baseName でまとまる）
フィールドグループ : ['groupName' => [0 => [...], 1 => [...]]] （@groupName 宣言の値で zip した行配列）

メディア（@media）・@html・block-editor 等のテンプレート出力固有の前処理は行わない（FieldTrait 側に残す責務）。URL 解決や HTML 絶対化も同様。

出力形式は Acms\Traits\Utilities\FieldTrait::buildFieldTrait と互換性がある。

Parameters

$autoConvert : bool = true: 既定で有効。"true"/"false" → bool、数値 → int/float（先頭 0 は文字列保持）。false にすると生の文字列のまま返す
$withValidation : bool = false: Field_Validation のとき各エントリに 'invalid' / 'v' キーを上乗せ
$recursive : bool = true: 子フィールドを toStructured した結果を合流させる

Return values

array<string, mixed>

updateGroupRow()

グループの指定インデックスの行を $row で置き換える。


    public
                    updateGroupRow(string $groupName, int $index, array<string, mixed> $row) : void

インデックスは getGroupRows() のビュー（最大長に揃えた行配列）に対応する。 addGroupRow() と同じ全置換セマンティクスで、$row に含まれない宣言フィールドは空文字で更新される（部分更新ではない）。宣言外のキーが含まれていれば InvalidArgumentException、範囲外のインデックスなら OutOfBoundsException。

Parameters

$groupName : string
$index : int
$row : array<string, mixed>

restoreFromArray()

fromArray() の復元処理本体。class キーによるディスパッチは行わない。


    protected
            static        restoreFromArray(array<string, mixed> $data) : static

Parameters

$data : array<string, mixed>

Return values

static

buildGroupRows()

グループに属するキー群から行配列を組み立てる。


    private
                    buildGroupRows(array<string|int, string> $belongs, bool $autoConvert, bool $withValidation) : array<int, array<string, mixed>>

Parameters

$belongs : array<string|int, string>
$autoConvert : bool
$withValidation : bool

Return values

array<int, array<string, mixed>>

buildMultiEntry()

マルチ項目フィールド（baseName@subKey 形式）のエントリを組み立てる。


    private
                    buildMultiEntry(string $baseName, array<string|int, string> $subKeys, bool $autoConvert, bool $withValidation) : array<string, mixed>

Parameters

$baseName : string
$subKeys : array<string|int, string>
$autoConvert : bool
$withValidation : bool

Return values

array<string, mixed>

buildSingleEntry()

単一値フィールドのエントリを組み立てる。


    private
                    buildSingleEntry(string $key, bool $autoConvert, bool $withValidation) : array<string, mixed>

Parameters

$key : string
$autoConvert : bool
$withValidation : bool

Return values

array<string, mixed>

partitionFieldKeys()

フィールドキーのリストを「単一値」「マルチ項目（baseName 別）」に分類する。


    private
            static        partitionFieldKeys(array<string|int, string> $keys) : array{0: string[], 1: array}

Parameters

$keys : array<string|int, string>

Return values

array{0: string[], 1: array}

rawScalar()

指定フィールドの生の文字列値を返す。値が無い / 空文字 / 配列なら null。型付きアクセサ共通の「値あり判定」に使う（boolean だけは空文字を別扱いするため使わない）。


    private
                    rawScalar(string $fd, int $i) : string|null

Parameters

$fd : string
$i : int

Return values

string|null

resolveClassFromArray()

配列内の 'class' キーから復元先の Field 系クラスを解決する。 class キー未指定なら Field として復元。


    private
            static        resolveClassFromArray(array<string, mixed> $data) : string

Parameters

$data : array<string, mixed>

Return values

string

Field in package Application

Attributes

Table of Contents

Properties

Methods

Properties

$_aryChild

$_aryField

$_aryMeta

Methods

__construct()

Parameters

add()

Parameters

Return values

addChild()

Parameters

Return values

addField()

Parameters

Return values

addGroupRow()

Parameters

boolean()

Parameters

Return values

cloneWith()

Parameters

Return values

convertValueType()

Parameters

defineGroup()

Parameters

delete()

Parameters

Return values

deleteField()

Parameters

Return values

deleteGroup()

Parameters

deleteGroupRow()

Parameters

dig()

Parameters

Return values

float()

Parameters

Return values

fromArray()

Parameters

Return values

get()

Parameters

Tags

Return values

getArray()

Parameters

Return values

getChild()

Parameters

Return values

getGroupRows()

Parameters

Return values

getMeta()

Parameters

Tags

Return values

integer()

Parameters

Return values

isChildExists()

Parameters

Return values

isExists()

Parameters

Return values

isGroup()

Parameters

Field
in package

Application