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.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 <code>!=</code>
            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 <code>id = $user_id</code> contains the value
            $username.
        </para>

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

        <programlisting language="php"><![CDATA[
$post_id   = $post->getId();
$clause    = $db->quoteInto('post_id = ?', $category_id);
$validator = new Zend_Validate_Db_RecordExists(
    array(
        'table'   => 'posts_categories',
        'field'   => 'post_id',
        '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 <code>posts_categories</code> table
            to ensure that a record with the <code>post_id</code> has a value
            matching <varname>$category_id</varname>
        </para>
    </sect3>

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

        <para>
            You can also specify an adapter, as the fourth parameter when
            instantiating your validator, 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
            <code>table</code> and <code>schema</code> 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>