repo_zf1/documentation/manual/en/module_specs/Zend_Validate-Db.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect2 id="zend.validate.Db">
    <title>Db_RecordExists and Db_NoRecordExists</title>

    <para>
        <classname>Zend_Validate_Db_RecordExists</classname> and
        <classname>Zend_Validate_Db_NoRecordExists</classname> provide a means to test
        whether a record exists in a given table of a database, with a given
        value.
    </para>

    <sect3 id="zend.validate.set.db.options">
        <title>Supported options for Zend_Validate_Db_*</title>

        <para>
            The following options are supported for
            <classname>Zend_Validate_Db_NoRecordExists</classname> and
            <classname>Zend_Validate_Db_RecordExists</classname>:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis><property>adapter</property></emphasis>: The database adapter which
                    will be used for the search.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>exclude</property></emphasis>: Sets records which will be
                    excluded from the search.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>field</property></emphasis>: The database field within this
                    table which will be searched for the record.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>schema</property></emphasis>: Sets the schema which will be
                    used for the search.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>table</property></emphasis>: The table which will be
                    searched for the record.
                </para>
            </listitem>
        </itemizedlist>
    </sect3>

    <sect3 id="zend.validate.db.basic-usage">
        <title>Basic usage</title>

        <para>
            An example of basic usage of the validators:
        </para>

        <programlisting language="php"><![CDATA[
//Check that the email address exists in the database
$validator = new Zend_Validate_Db_RecordExists(
    array(
        'table' => 'users',
        'field' => 'emailaddress'
    )
);

if ($validator->isValid($emailaddress)) {
    // email address appears to be valid
} else {
    // email address is invalid; print the reasons
    foreach ($validator->getMessages() as $message) {
        echo "$message\n";
    }
}
]]></programlisting>

        <para>
            The above will test that a given email address is in the database
            table. If no record is found containing the value of
            <varname>$emailaddress</varname> in the specified column, then an error
            message is displayed.
        </para>

        <programlisting language="php"><![CDATA[
//Check that the username is not present in the database
$validator = new Zend_Validate_Db_NoRecordExists(
    array(
        'table' => 'users',
        'field' => 'username'
    )
);
if ($validator->isValid($username)) {
    // username appears to be valid
} else {
    // username is invalid; print the reason
    $messages = $validator->getMessages();
    foreach ($messages as $message) {
        echo "$message\n";
    }
}
]]></programlisting>

        <para>
            The above will test that a given username is not in the database
            table. If a record is found containing the value of
            <varname>$username</varname> in the specified column, then an error
            message is displayed.
        </para>
    </sect3>

    <sect3 id="zend.validate.db.excluding-records">
        <title>Excluding records</title>

        <para>
            <classname>Zend_Validate_Db_RecordExists</classname> and
            <classname>Zend_Validate_Db_NoRecordExists</classname> also provide a means
            to test the database, excluding a part of the table, either by
            providing a where clause as a string, or an array with the keys
            "field" and "value".
        </para>

        <para>
            When providing an array for the exclude clause, the <emphasis>!=</emphasis>
            operator is used, so you can check the rest of a table for a value
            before altering a record (for example on a user profile form)
        </para>

        <programlisting language="php"><![CDATA[
//Check no other users have the username
$user_id   = $user->getId();
$validator = new Zend_Validate_Db_NoRecordExists(
    array(
        'table' => 'users',
        'field' => 'username',
        'exclude' => array(
            'field' => 'id',
            'value' => $user_id
        )
    )
);

if ($validator->isValid($username)) {
    // username appears to be valid
} else {
    // username is invalid; print the reason
    $messages = $validator->getMessages();
    foreach ($messages as $message) {
        echo "$message\n";
    }
}
]]></programlisting>

        <para>
            The above example will check the table to ensure no records other
            than the one where <command>id = $user_id</command> contains the value
            $username.
        </para>

        <para>
            You can also provide a string to the exclude clause so you can use
            an operator other than <emphasis>!=</emphasis>. This can be useful for
            testing against composite keys.
        </para>

        <programlisting language="php"><![CDATA[
$email     = 'user@example.com';
$clause    = $db->quoteInto('email = ?', $email);
$validator = new Zend_Validate_Db_RecordExists(
    array(
        'table'   => 'users',
        'field'   => 'username',
        'exclude' => $clause
    )
);

if ($validator->isValid($username)) {
    // username appears to be valid
} else {
    // username is invalid; print the reason
    $messages = $validator->getMessages();
    foreach ($messages as $message) {
        echo "$message\n";
    }
}
]]></programlisting>

        <para>
            The above example will check the 'users' table
            to ensure that only a record with both the username
            <varname>$username</varname> and with the email
            <varname>$email</varname> is valid.
        </para>
    </sect3>

    <sect3 id="zend.validate.db.database-adapters">
        <title>Database Adapters</title>

        <para>
            You can also specify an adapter. This will allow you to work with
            applications using multiple database adapters, or where you have not
            set a default adapter. As in the example below:
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_Db_RecordExists(
    array(
        'table' => 'users',
        'field' => 'id',
        'adapter' => $dbAdapter
    )
);
]]></programlisting>
    </sect3>

    <sect3 id="zend.validate.db.database-schemas">
        <title>Database Schemas</title>

        <para>
            You can specify a schema within your database for adapters such as
            PostgreSQL and DB/2 by simply supplying an array with
            <property>table</property> and <property>schema</property> keys. As in the example
            below:
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_Db_RecordExists(
    array(
        'table'  => 'users',
        'schema' => 'my',
        'field'  => 'id'
    )
);
]]></programlisting>
    </sect3>
</sect2>