Validatorの拡張について

a-blog cms のフォーム（メールフォーム・お問い合わせフォーム等）の入力チェックは、標準のバリデータに加えてユーザー独自のバリデータで拡張できます。

このページでは次の2つを説明します。

• 独自バリデータの追加 — 標準にないチェックロジックを足す

• 管理画面の選択肢への表示 — 追加したバリデータを、管理画面のフォーム編集画面にある「入力チェック」のプルダウンに表示する（Ver. 3.2.24 ~）

独自バリデータの追加について

Acms\Custom\Validator クラス（extension/acms/Validator.php）にメソッドを追加することで、フォームのバリデーションに独自のチェックを使用できるようになります。標準のバリデータにないチェックを使いたい場合にご利用ください。

メソッドは次のルールで実装します。

• メソッド名が、テンプレート側で指定するバリデーションメソッド名になります。

• 第1引数 $val にフィールドの入力値、第2引数 $arg にフォームオプションで指定した値が渡されます。

• 入力が正しければ true、正しくなければ false を return してください。

<?php

namespace Acms\Custom;

use Acms\Services\Validator\Attribute\AsValidationOption;

/**
 * extension/acms/Validator.php
 *
 * バリデータにユーザー定義のメソッドを追加します。
 * 同名メソッドがある場合、ユーザー定義のメソッドが優先されます。
 */
class Validator
{
    /**
     * @param  string $val 入力値
     * @param  string $arg <input type="hidden" name="var:v#sample" value="ここの値">
     * @return bool   入力が正しい場合は true、そうでない場合は false を返す
     */
    public function sample($val, $arg)
    {
        // name="var:v#sample" value="cms" で指定した文字列が
        // 含まれていなかったらエラーにする
        return strpos($val, $arg) !== false;
    }
}

テンプレート上の指定との対応

テンプレート側では、フォームオプション名と Validator クラスのメソッド名を一致させます。

<input type="text" name="var" value="{var}">
<input type="hidden" name="field[]" value="var">
<input type="hidden" name="var:v#sample" value="cms">

<!-- BEGIN var:validator#sample -->
  <p class="acms-admin-text-error">cms という文字列を含めてください。</p>
<!-- END var:validator#sample -->

• field[] … バリデーション対象のフィールド名を宣言します。

• var:v#sample … var フィールドに対し sample メソッドを適用し、value がメソッドの第2引数 $arg に渡されます。

• var:validator#sample … バリデーションに失敗したときに表示するエラーメッセージのブロックです。

管理画面の選択肢に表示する（Ver. 3.2.24 ~）

独自バリデータを追加しただけでは、実行時のチェックには使われますが、管理画面のフォーム編集画面の「入力チェック」プルダウンには表示されません。メソッドに #[AsValidationOption] 属性を付与すると、そのメソッドが選択肢として動的に表示されるようになります。

組み込みバリデータも拡張バリデータも同じ仕組みで選択肢を生成するため、属性を1つ付けるだけで、運用担当者が管理画面から独自バリデータを選べるようになります。

<?php

namespace Acms\Custom;

use Acms\Services\Validator\Attribute\AsValidationOption;

class Validator
{
    /**
     * @param  string $val 入力値
     * @param  string $arg バリデーション引数
     * @return bool
     */
    #[AsValidationOption(label: 'サンプルチェック', group: '形式チェック')]
    public function sample($val, $arg)
    {
        return strpos($val, $arg) !== false;
    }
}

属性の引数

Acms\Services\Validator\Attribute\AsValidationOption は次の引数を取ります。

選択肢の key（メソッドの内部識別子）はメソッド名から自動取得されるため、属性での指定は不要です。

グループと表示順

選択肢は次の既知グループ順で表示されます。

1. 入力値の制限

2. 形式チェック

3. その他

既知グループ以外を group に指定した場合（拡張バリデータ独自のグループ名など）は、選択肢一覧の末尾に出現順で追加されます。

同名メソッドの優先順位

バリデータは system（組み込み） → user → custom（Acms\Custom\Validator）→ 拡張プラグインが登録したもの、の順で収集されます。同じ key（メソッド名）が複数のバリデータに存在する場合、後勝ちで custom が user / system を上書きします（実行時の解決順と一致）。表示位置は最初に出現した位置を維持します。

属性を付けないメソッドの扱い

#[AsValidationOption] を付けないメソッドは、選択肢には現れませんが、テンプレートから明示的に呼び出せば実行時バリデーションとしては動作します。管理画面から選ばせる必要のない内部用チェックは、属性を付けないでおく使い分けができます。