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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect2 id="zend.validate.Db">
   4     <title>Db_RecordExists and Db_NoRecordExists</title>
   5
   6     <para>
   7         <classname>Zend_Validate_Db_RecordExists</classname> and
   8         <classname>Zend_Validate_Db_NoRecordExists</classname> provide a means to test
   9         whether a record exists in a given table of a database, with a given
  10         value.
  11     </para>
  12
  13     <sect3 id="zend.validate.set.db.options">
  14         <title>Supported options for Zend_Validate_Db_*</title>
  15
  16         <para>
  17             The following options are supported for
  18             <classname>Zend_Validate_Db_NoRecordExists</classname> and
  19             <classname>Zend_Validate_Db_RecordExists</classname>:
  20         </para>
  21
  22         <itemizedlist>
  23             <listitem>
  24                 <para>
  25                     <emphasis><property>adapter</property></emphasis>: The database adapter which
  26                     will be used for the search.
  27                 </para>
  28             </listitem>
  29
  30             <listitem>
  31                 <para>
  32                     <emphasis><property>exclude</property></emphasis>: Sets records which will be
  33                     excluded from the search.
  34                 </para>
  35             </listitem>
  36
  37             <listitem>
  38                 <para>
  39                     <emphasis><property>field</property></emphasis>: The database field within this
  40                     table which will be searched for the record.
  41                 </para>
  42             </listitem>
  43
  44             <listitem>
  45                 <para>
  46                     <emphasis><property>schema</property></emphasis>: Sets the schema which will be
  47                     used for the search.
  48                 </para>
  49             </listitem>
  50
  51             <listitem>
  52                 <para>
  53                     <emphasis><property>table</property></emphasis>: The table which will be
  54                     searched for the record.
  55                 </para>
  56             </listitem>
  57         </itemizedlist>
  58     </sect3>
  59
  60     <sect3 id="zend.validate.db.basic-usage">
  61         <title>Basic usage</title>
  62
  63         <para>
  64             An example of basic usage of the validators:
  65         </para>
  66
  67         <programlisting language="php"><![CDATA[
  68 //Check that the email address exists in the database
  69 $validator = new Zend_Validate_Db_RecordExists(
  70     array(
  71         'table' => 'users',
  72         'field' => 'emailaddress'
  73     )
  74 );
  75
  76 if ($validator->isValid($emailaddress)) {
  77     // email address appears to be valid
  78 } else {
  79     // email address is invalid; print the reasons
  80     foreach ($validator->getMessages() as $message) {
  81         echo "$message\n";
  82     }
  83 }
  84 ]]></programlisting>
  85
  86         <para>
  87             The above will test that a given email address is in the database
  88             table. If no record is found containing the value of
  89             <varname>$emailaddress</varname> in the specified column, then an error
  90             message is displayed.
  91         </para>
  92
  93         <programlisting language="php"><![CDATA[
  94 //Check that the username is not present in the database
  95 $validator = new Zend_Validate_Db_NoRecordExists(
  96     array(
  97         'table' => 'users',
  98         'field' => 'username'
  99     )
 100 );
 101 if ($validator->isValid($username)) {
 102     // username appears to be valid
 103 } else {
 104     // username is invalid; print the reason
 105     $messages = $validator->getMessages();
 106     foreach ($messages as $message) {
 107         echo "$message\n";
 108     }
 109 }
 110 ]]></programlisting>
 111
 112         <para>
 113             The above will test that a given username is not in the database
 114             table. If a record is found containing the value of
 115             <varname>$username</varname> in the specified column, then an error
 116             message is displayed.
 117         </para>
 118     </sect3>
 119
 120     <sect3 id="zend.validate.db.excluding-records">
 121         <title>Excluding records</title>
 122
 123         <para>
 124             <classname>Zend_Validate_Db_RecordExists</classname> and
 125             <classname>Zend_Validate_Db_NoRecordExists</classname> also provide a means
 126             to test the database, excluding a part of the table, either by
 127             providing a where clause as a string, or an array with the keys
 128             "field" and "value".
 129         </para>
 130
 131         <para>
 132             When providing an array for the exclude clause, the <code>!=</code>
 133             operator is used, so you can check the rest of a table for a value
 134             before altering a record (for example on a user profile form)
 135         </para>
 136
 137         <programlisting language="php"><![CDATA[
 138 //Check no other users have the username
 139 $user_id   = $user->getId();
 140 $validator = new Zend_Validate_Db_NoRecordExists(
 141     array(
 142         'table' => 'users',
 143         'field' => 'username',
 144         'exclude' => array(
 145             'field' => 'id',
 146             'value' => $user_id
 147         )
 148     )
 149 );
 150
 151 if ($validator->isValid($username)) {
 152     // username appears to be valid
 153 } else {
 154     // username is invalid; print the reason
 155     $messages = $validator->getMessages();
 156     foreach ($messages as $message) {
 157         echo "$message\n";
 158     }
 159 }
 160 ]]></programlisting>
 161
 162         <para>
 163             The above example will check the table to ensure no records other
 164             than the one where <code>id = $user_id</code> contains the value
 165             $username.
 166         </para>
 167
 168         <para>
 169             You can also provide a string to the exclude clause so you can use
 170             an operator other than <code>!=</code>. This can be useful for
 171             testing against composite keys.
 172         </para>
 173
 174         <programlisting language="php"><![CDATA[
 175 $post_id   = $post->getId();
 176 $clause    = $db->quoteInto('post_id = ?', $category_id);
 177 $validator = new Zend_Validate_Db_RecordExists(
 178     array(
 179         'table'   => 'posts_categories',
 180         'field'   => 'post_id',
 181         'exclude' => $clause
 182     )
 183 );
 184
 185 if ($validator->isValid($username)) {
 186     // username appears to be valid
 187 } else {
 188     // username is invalid; print the reason
 189     $messages = $validator->getMessages();
 190     foreach ($messages as $message) {
 191         echo "$message\n";
 192     }
 193 }
 194 ]]></programlisting>
 195
 196         <para>
 197             The above example will check the <code>posts_categories</code> table
 198             to ensure that a record with the <code>post_id</code> has a value
 199             matching <varname>$category_id</varname>
 200         </para>
 201     </sect3>
 202
 203     <sect3 id="zend.validate.db.database-adapters">
 204         <title>Database Adapters</title>
 205
 206         <para>
 207             You can also specify an adapter. This will allow you to work with
 208             applications using multiple database adapters, or where you have not
 209             set a default adapter. As in the example below:
 210         </para>
 211
 212         <programlisting language="php"><![CDATA[
 213 $validator = new Zend_Validate_Db_RecordExists(
 214     array(
 215         'table' => 'users',
 216         'field' => 'id',
 217         'adapter' => $dbAdapter
 218     )
 219 );
 220 ]]></programlisting>
 221     </sect3>
 222
 223     <sect3 id="zend.validate.db.database-schemas">
 224         <title>Database Schemas</title>
 225
 226         <para>
 227             You can specify a schema within your database for adapters such as
 228             PostgreSQL and DB/2 by simply supplying an array with
 229             <code>table</code> and <code>schema</code> keys. As in the example
 230             below:
 231         </para>
 232
 233         <programlisting language="php"><![CDATA[
 234 $validator = new Zend_Validate_Db_RecordExists(
 235     array(
 236         'table'  => 'users',
 237         'schema' => 'my',
 238         'field'  => 'id'
 239     )
 240 );
 241 ]]></programlisting>
 242     </sect3>
 243 </sect2>