<commit_before><sect1 id="zend.validate.introduction">

    <title>導入</title>

    <para>
        Zend_Validate コンポーネントは、一般的に必要となるバリデータを提供します。
        シンプルなバリデータチェイン機能も持っており、
        ひとつのデータに対して複数のバリデータを指定した順に適用することができます。
    </para>

    <sect2 id="zend.validate.introduction.definition">

        <title>バリデータとは?</title>

        <para>
            バリデータは、入力が何らかの要件を満たしているかどうかを調べ、
            結果を boolean 値で返します。これは、入力が要件を満たしているかどうかを表します。
            入力が要件を満たさなかった場合、バリデータは
            その入力がどのように要件を満たさなかったのかについての追加情報も提供します。
        </para>

        <para>
            たとえば、あるウェブアプリケーションでは
            「ユーザ名は 6 文字から 12 文字、かつ英数字のみが使用可能」
            という要件があるものとします。
            このような場合に入力がそれを満たしているかどうかを調べるために
            バリデータを使用できます。
            選択したユーザ名がいずれかひとつあるいは両方の要件を満たしていない場合に、
            どちらの条件に反していたのかを知ることができるので便利です。
        </para>

    </sect2>

    <sect2 id="zend.validate.introduction.using">

        <title>バリデータの基本的な使用法</title>

        <para>
            ここで考えたバリデータについての定義をもとにして
            <code>Zend_Validate_Interface</code> が作成されました。これは、
            <code>isValid()</code> および <code>getMessages()</code>
            のふたつのメソッドを定義するものです。
            <code>isValid()</code> メソッドは指定した値に対する検証を行います。
            値が検証条件を満たしている場合にのみ <code>true</code> を返します。
        </para>

        <para>
            <code>isValid()</code> が <code>false</code> を返した場合、
            <code>getMessages()</code> がメッセージの配列を提供します。
            ここには検証が失敗した理由が含まれます。
        </para>

        <para>
            <code>getErrors()</code> メソッドは、
            検証が失敗した原因について説明する文字列の配列を返します。
            この文字列の内容をもとに、エラーの原因を判断します。
            この文字列をもとに判断するのはあくまでもアプリケーションのコードであり、
            この内容を直接ユーザに見せることは想定していません。
            エラー文字列は各クラスが独自に管理しています。
            また、各クラスではそれぞれのエラーを特定するための定数を定義しています。
        </para>

        <note>
            <para>
                <code>getMessages()</code> および <code>getErrors()</code> が返す情報は、
                直近の <code>isValid()</code> コールに関するもののみです。
                <code>isValid()</code> をコールすると、それまでに実行された
                <code>isValid()</code> によるメッセージはすべて消去されます。
                なぜなら、通常は、毎回異なる値に対して <code>isValid()</code>
                をコールするであろうと考えられるからです。
            </para>
        </note>

        <para>
            以下の例では、電子メールアドレスの検証方法を説明します。

            <programlisting role="php"><![CDATA[<?php
require_once 'Zend/Validate/EmailAddress.php';

$validator = new Zend_Validate_EmailAddress();

if ($validator->isValid($email)) {
    //
    // email は妥当な形式です
    //
} else {
    //
    // email は無効な形式です。理由を表示します
    //
    foreach ($validator->getMessages() as $message) {
        echo "$message\n";
    }
}
]]></programlisting>

        </para>

    </sect2>

    <sect2 id="zend.validate.introduction.messages">

        <title>メッセージのカスタマイズ</title>

        <para>
            バリデータクラスの <code>setMessage()</code> メソッドを使用すると、
            検証に失敗した場合に <code>getMessages()</code>
            が返すメッセージの書式を設定することができます。
            最初の引数にはエラーメッセージを文字列で指定します。
            このメッセージに特定のトークンを含めると、
            バリデータがそれを実際の値に置き換えます。
            トークン <code>%value%</code> はすべてのバリデータがサポートしており、
            これは <code>isValid()</code> に渡した値に置き換えられます。
            その他、バリデータによっていろいろなトークンをサポートしています。
            たとえば、Zend_Validate_LessThan では
            <code>%max%</code> というトークンをサポートしています。
        </para>

        <para>
            二番目の引数はオプションで、<code>getErrors()</code>
            メソッドが返すエラー ID に対応する文字列を指定します。
            この引数を省略すると、バリデータクラス内で最初に宣言されているメッセージの ID を使用します。
            多くのバリデータクラスはエラーメッセージをひとつだけしか持っていないので、
            あえてどのメッセージを使用するかを指定する必要はありません。
        </para>

        <para>
            <programlisting role="php"><![CDATA[<?php
require_once 'Zend/Validate/StringLength.php';

$validator = new Zend_Validate_StringLength(8);

$validator->setMessage(
    '文字列 \'%value%\' は短すぎます。最低 %min% 文字以上必要です',
    Zend_Validate_StringLength::TOO_SHORT);

if (!$validator->isValid('word')) {
    $m = $validator->getMessages();
    echo $m[0];

    // 出力は "文字列 'word' は短すぎます。最低 8 文字以上必要です" となります
}
]]></programlisting>
        </para>
<commit_msg>sync Japanese document with r5335.<commit_after><sect1 id="zend.validate.introduction">

    <title>導入</title>

    <para>
        Zend_Validate コンポーネントは、一般的に必要となるバリデータを提供します。
        シンプルなバリデータチェイン機能も持っており、
        ひとつのデータに対して複数のバリデータを指定した順に適用することができます。
    </para>

    <sect2 id="zend.validate.introduction.definition">

        <title>バリデータとは?</title>

        <para>
            バリデータは、入力が何らかの要件を満たしているかどうかを調べ、
            結果を boolean 値で返します。これは、入力が要件を満たしているかどうかを表します。
            入力が要件を満たさなかった場合、バリデータは
            その入力がどのように要件を満たさなかったのかについての追加情報も提供します。
        </para>

        <para>
            たとえば、あるウェブアプリケーションでは
            「ユーザ名は 6 文字から 12 文字、かつ英数字のみが使用可能」
            という要件があるものとします。
            このような場合に入力がそれを満たしているかどうかを調べるために
            バリデータを使用できます。
            選択したユーザ名がいずれかひとつあるいは両方の要件を満たしていない場合に、
            どちらの条件に反していたのかを知ることができるので便利です。
        </para>

    </sect2>

    <sect2 id="zend.validate.introduction.using">

        <title>バリデータの基本的な使用法</title>

        <para>
            ここで考えたバリデータについての定義をもとにして
            <code>Zend_Validate_Interface</code> が作成されました。これは、
            <code>isValid()</code> および <code>getMessages()</code>
            のふたつのメソッドを定義するものです。
            <code>isValid()</code> メソッドは指定した値に対する検証を行います。
            値が検証条件を満たしている場合にのみ <code>true</code> を返します。
        </para>

        <para>
            <code>isValid()</code> が <code>false</code> を返した場合、
            <code>getMessages()</code> がメッセージの配列を提供します。
            ここには検証が失敗した理由が含まれます。
        </para>

        <para>
            <code>getErrors()</code> メソッドは、
            検証が失敗した原因について説明する文字列の配列を返します。
            この文字列の内容をもとに、エラーの原因を判断します。
            この文字列をもとに判断するのはあくまでもアプリケーションのコードであり、
            この内容を直接ユーザに見せることは想定していません。
            エラー文字列は各クラスが独自に管理しています。
            また、各クラスではそれぞれのエラーを特定するための定数を定義しています。
        </para>

        <note>
            <para>
                <code>getMessages()</code> および <code>getErrors()</code> が返す情報は、
                直近の <code>isValid()</code> コールに関するもののみです。
                <code>isValid()</code> をコールすると、それまでに実行された
                <code>isValid()</code> によるメッセージはすべて消去されます。
                なぜなら、通常は、毎回異なる値に対して <code>isValid()</code>
                をコールするであろうと考えられるからです。
            </para>
        </note>

        <para>
            以下の例では、電子メールアドレスの検証方法を説明します。

            <programlisting role="php"><![CDATA[<?php
require_once 'Zend/Validate/EmailAddress.php';

$validator = new Zend_Validate_EmailAddress();

if ($validator->isValid($email)) {
    //
    // email は妥当な形式です
    //
} else {
    //
    // email は無効な形式です。理由を表示します
    //
    foreach ($validator->getMessages() as $message) {
        echo "$message\n";
    }
}
]]></programlisting>

        </para>

    </sect2>

    <sect2 id="zend.validate.introduction.messages">

        <title>メッセージのカスタマイズ</title>

        <para>
            バリデータクラスの <code>setMessage()</code> メソッドを使用すると、
            検証に失敗した場合に <code>getMessages()</code>
            が返すメッセージの書式を設定することができます。
            最初の引数にはエラーメッセージを文字列で指定します。
            このメッセージに特定のトークンを含めると、
            バリデータがそれを実際の値に置き換えます。
            トークン <code>%value%</code> はすべてのバリデータがサポートしており、
            これは <code>isValid()</code> に渡した値に置き換えられます。
            その他、バリデータによっていろいろなトークンをサポートしています。
            たとえば、Zend_Validate_LessThan では
            <code>%max%</code> というトークンをサポートしています。
            <code>getMessageVariables()</code> メソッドは、
            そのバリデータがサポートする変数トークンの配列を返します。
        </para>

        <para>
            二番目の引数はオプションで、<code>getErrors()</code>
            メソッドが返すエラー ID に対応する文字列を指定します。
            この引数を省略すると、バリデータクラス内で最初に宣言されているメッセージの ID を使用します。
            多くのバリデータクラスはエラーメッセージをひとつだけしか持っていないので、
            あえてどのメッセージを使用するかを指定する必要はありません。
        </para>

        <para>
            <programlisting role="php"><![CDATA[<?php
require_once 'Zend/Validate/StringLength.php';

$validator = new Zend_Validate_StringLength(8);

$validator->setMessage(
    '文字列 \'%value%\' は短すぎます。最低 %min% 文字以上必要です',
    Zend_Validate_StringLength::TOO_SHORT);

if (!$validator->isValid('word')) {
    $m = $validator->getMessages();
    echo $m[0];

    // 出力は "文字列 'word' は短すぎます。最低 8 文字以上必要です" となります
}
]]></programlisting>
        </para>

{'fraction_non_alphanumeric': 0.11479561075605933, 'fraction_numerical': 0.0033763414928252742, 'mean_word_length': 2.204791344667697, 'pattern_counts': {'":': 0, '<': 181, '<?xml version=': 0, '>': 187, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2364592', 'n_tokens_mistral': 4488, 'n_tokens_neox': 4148, 'n_words': 365}