[Sommaire] [Imprimer]

   1  <refentry id="{@id}" revision="$Id: ActiveRecord.cls 192 2006-03-27 22:02:53Z haas $">
   2   <refnamediv>
   3    <refname>ActiveRecord</refname>
   4    <refpurpose>Base class for the active record design pattern</refpurpose>
   5   </refnamediv>
   6   <refsynopsisdiv>
   7    <author>
   8     Walt Haas
   9     <authorblurb>
  10      {@link mailto:haas@xmission.com haas@xmission.com}
  11     </authorblurb>
  12    </author>
  13   </refsynopsisdiv>
  14   {@toc}
  15   <refsect1 id="{@id active_record_intro}">
  16    <title>Introduction</title>
  17     <para>Heart of Active Record design pattern.  Encapsulates all
  18     access to data in corresponding table.  Enforces domain rules.
  19     Never instantiated directly.  Subclass for each table.</para>
  20     <para>Each subclass of this class is associated with a database table
  21     in the Model section of the Model-View-Controller architecture.
  22     By convention, the name of each subclass is the CamelCase singular
  23     form of the table name, which is in the lower_case_underscore
  24     plural notation.  For example, 
  25     a table named "order_details" would be associated with a subclass
  26     of ActiveRecord named "OrderDetail", and a table named "people"
  27     would be associated with subclass "Person".  Naming convention
  28     encapsulated in {@tutorial PHPonTrax/Inflector.cls} class.</para>
  29     <para>Convention: primary key of each table is column named "id".</para>
  30     <para>For a discussion of the ActiveRecord design pattern, see
  31     "Patterns of Enterprise 
  32     Application Architecture" by Martin Fowler, pp. 160-164.</para>
  33     <para>When object constructed, the format of a row in the
  34     associated table is retrieved from 
  35     the database and stored in object variable $content_columns.
  36     The data values of the columns are stored as object variable with
  37     the same name as the column.  Therefore, it is not possible to have
  38     a column with the same name as an object variable
  39     </para>
  40   </refsect1>
  41   <refsect1 id="{@id basic_methods}">
  42    <title>Basic Methods</title>
  43    <refsect2 id="{@id create_methods}">
  44     <title>Create</title>
  45      <para>Before you can use the subclass of ActiveRecord associated
  46      with a table, you must install the table definition in the
  47      database.  For example:</para>
  48      <example>
  49  drop table if exists person_names;
  50  create table person_names
  51    (id         int auto_increment primary key,
  52     prefix     varchar(20) null,
  53     first_name varchar(40) null,
  54     mi         char(1)     null,
  55     last_name  varchar(40) null,
  56     suffix     varchar(20) null);
  57      </example>
  58      <para>With the table definition installed in the database, you can
  59      create an object that references that table.  The
  60      {@link ActiveRecord::__construct() constructor} for
  61      PersonName connects to the database and reads the definition for
  62      table person_names to find the names of its columns, which then
  63      become the names of the related attributes of the object.</para>
  64      <example>
  65  class PersonName extends ActiveRecord {
  66  };
  67  $p = new PersonName;    
  68  $p->first_name = "Lo";
  69  $p->last_name  = "Phat";
  70  $p->suffix     = "MD";
  71  $result = $p->save();
  72      </example>
  73      <para>$result will be true if the row was saved successfully, false
  74      otherwise.  Slightly more compact ways to say the same thing:</para>
  75      <example>
  76  $p = new PersonName;    
  77  $result = $p->save(array("first_name" => "Lo","last_name" => "Phat",
  78                       "suffix" => "MD"));
  79      </example>
  80      <para>or assign attribute values in the constructor:</para>
  81      <example>
  82  $p = new PersonName(array("first_name" => "Lo","last_name" => "Phat",
  83                       "suffix" => "MD"));    
  84  $result = $p->save();
  85      </example>
  86      <para>You can define the class so that it requires certain
  87      validation tests in order
  88      to be saved.  Here is a definition that will generate an error on
  89      save() if either "first_name" or "last_name" is left blank.
  90      When you call save(), the object is inspected for method
  91      names like 'validate_*' where '*' is the name of a column.
  92      All such methods are executed, and the results are tested.
  93      The return must be an array with true or false in the first
  94      element, and an error message in the second if the first is
  95      false.  If any of the 'validate_*' methods returns false, the
  96      save fails:</para>
  97      <example>
  98  class PersonName extends ActiveRecord {
  99      //  Function to validate first name not blank
 100      function validate_first_name() {
 101          if ($this->first_name == '') {
 102              return array(false, "first name is blank");
 103          } else {
 104              return array(true);
 105          }
 106      }
 107      //  Function to validate last name not blank
 108      function validate_last_name() {
 109          if ($this->last_name == '') {
 110              return array(false, "last name is blank");
 111          } else {
 112              return array(true);
 113          }
 114      }
 115  };
 116  $result = $p->save(array("suffix" => "MD"));
 117  if ($result == false) {
 118     //  Errors are listed in array $p->errors
 119     echo "save failed:\n";
 120     foreach ($p->errors as $key => $value) {
 121         echo "  field $key: $value\n";
 122     }
 123  }
 124      </example>
 125      <para>This will output:</para>
 126      <example>
 127  save failed:
 128    field first_name: first name is blank
 129    field last_name: last name is blank
 130      </example>
 131      <para>If you misspell an attribute, the misspelled name will
 132      become an attribute of the object, but it will not be saved
 133      because it is not the name of a column.  This will not result in
 134      an error message (unless that attribute fails validation):  For
 135      example:</para>
 136      <example>
 137  $p = new PersonName(array("first_name" => "Lo","last_name" => "Phat",
 138                       "sufix" => "MD"));    
 139  $result = $p->save();
 140      </example>
 141      <para>This will not fail, but the attribute $p->sufix will not be
 142      saved. Instead, column 'suffix' will be set to '' (empty string).
 143      </para>
 144    </refsect2>
 145    <refsect2 id="{@id read_methods}">
 146     <title>Read</title>
 147     <para>The find*() methods search the table associated with this
 148     class for rows that match some argument and return a new object of
 149     this class for each matching row.  In the simplest case, you know
 150     the value of the id column of the row you want:</para>
 151     <example>
 152  $p = new PersonName();
 153  $rs = $p->find("42");
 154  //  $rs is a new object representing the row with id 42,
 155  //  or false if it wasn't found.  $p object remains empty.
 156     </example>
 157     <para>You can ask for multiple id values with one find:</para>
 158     <example>
 159  $rs = $p->find(array("17","23","65"));
 160  //  $rs is an array containing zero or more new objects representing the
 161  //  matching rows.  The keys of the array are the id values that matched.
 162     </example>
 163     <para>You can search the table more generally with the find_all()
 164     method, which allows you to provide an SQL clause to describe the
 165     match rule.  For example:</para>
 166     <example>
 167  $rs = $p->find_all("last_name='Dover'");
 168  //  $rs is an array containing zero or more new objects representing the
 169  //  matching rows.  The keys of the array are the id values that matched.
 170     </example>
 171     <para>The argument you provide must be a valid SQL WHERE clause
 172     and it must contain an '='.</para>
 173     <para>If you omit the argument or provide an argument of null, you
 174     get all rows in the table.</para> 
 175     <para>You can also use a second argument to control the order of
 176     the results.  This argument must be a valid SQL ORDER BY clause.
 177     For example:</para>
 178     <example>
 179  $rs = $p->find_all("last_name='Dover'","last_name,first_name");
 180     </example>
 181     <para>The find_first() method returns only the first matching row.
 182     Is there a doctor in the house?</para>
 183     <example>
 184  $rs = $p->find_first("prefix='Dr.'");
 185  //  $rs is a new object representing the first row with prefix 'Dr.',
 186  //  or false if none was found
 187     </example>
 188     <para>An error, such as incorrect SQL, causes an
 189     {@tutorial PHPonTrax/ActiveRecordError.cls}
 190     exception to be thrown.  Note that
 191     it is not an error for no matching rows to be found.</para> 
 192    </refsect2>
 193    <refsect2 id="{@id update_methods}">
 194     <title>Update</title>
 195      <para>@todo Update tutorial</para>
 196    </refsect2>
 197    <refsect2 id="{@id delete_methods}">
 198     <title>Delete</title>
 199      <para>@todo Delete tutorial</para>
 200    </refsect2>
 201    <refsect2 id="{@id agg_methods}">
 202     <title>SQL Aggregate Functions</title>
 203      <para>SQL defines aggregate functions AVG(), COUNT(), MAX(), MIN()
 204       and SUM().  Not all DBMS's implement all of them.  Implemented by
 205       methods avg_all(), count_all(), max_all(), min_all() and sum_all().
 206       Parameters: [0]: If present, expression to apply
 207              the aggregate function to.  Otherwise, '*' will be used.
 208              <b>NOTE:</b>SQL uses '*' only for the COUNT() function,
 209              where it means "including rows with NULL in this column".
 210            [1]: argument to WHERE clause
 211            [2]: joins??? @todo. Joins parameter  Method call is calculated from list
 212            in $aggregrations</para>
 213  
 214     <refsect3 id="{@id agg_method_avg}">
 215      <title>avg_all()</title>
 216      <para>@todo Document avg_all()</para>
 217     </refsect3>
 218     <refsect3 id="{@id agg_method_count}">
 219      <title>count_all()</title>
 220      <para>@todo Document count_all()</para>
 221      <para> </para>
 222     </refsect3>
 223     <refsect3 id="{@id agg_method_max}">
 224      <title>max_all()</title>
 225      <para>@todo Document max_all()</para>
 226      <para> </para>
 227     </refsect3>
 228     <refsect3 id="{@id agg_method_min}">
 229      <title>min_all()</title>
 230      <para>@todo Document min_all()</para>
 231      <para> </para>
 232     </refsect3>
 233     <refsect3 id="{@id agg_method_sum}">
 234      <title>sum_all()</title>
 235      <para>@todo Document sum_all()</para>
 236      <para> </para>
 237     </refsect3>
 238    </refsect2>
 239   </refsect1>
 240   <refsect1 id="{@id associations}">
 241    <title>Associations</title>
 242      <para>@todo Document associations</para>
 243      <para>belongs_to</para>
 244      <para>has_one</para>
 245      <para>has_many</para>
 246      <para>has_and_belongs_to_many</para>
 247   </refsect1>
 248  <!--
 249  Local variables:
 250  mode: xml
 251  c-basic-offset: 1
 252  indent-tabs-mode: nil
 253  End:
 254  -->
 255  </refentry>