Vendor lock

vendor/j4mie/idiorm/docs/models.rst

@@ -0,0 +1,161 @@
+Models
+======
+
+Getting data from objects
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once you've got a set of records (objects) back from a query, you can
+access properties on those objects (the values stored in the columns in
+its corresponding table) in two ways: by using the ``get`` method, or
+simply by accessing the property on the object directly:
+
+.. code-block:: php
+
+    <?php
+    $person = ORM::for_table('person')->find_one(5);
+
+    // The following two forms are equivalent
+    $name = $person->get('name');
+    $name = $person->name;
+
+You can also get the all the data wrapped by an ORM instance using the
+``as_array`` method. This will return an associative array mapping
+column names (keys) to their values.
+
+The ``as_array`` method takes column names as optional arguments. If one
+or more of these arguments is supplied, only matching column names will
+be returned.
+
+.. code-block:: php
+
+    <?php
+    $person = ORM::for_table('person')->create();
+
+    $person->first_name = 'Fred';
+    $person->surname = 'Bloggs';
+    $person->age = 50;
+
+    // Returns array('first_name' => 'Fred', 'surname' => 'Bloggs', 'age' => 50)
+    $data = $person->as_array();
+
+    // Returns array('first_name' => 'Fred', 'age' => 50)
+    $data = $person->as_array('first_name', 'age');
+
+Updating records
+~~~~~~~~~~~~~~~~
+
+To update the database, change one or more of the properties of the
+object, then call the ``save`` method to commit the changes to the
+database. Again, you can change the values of the object's properties
+either by using the ``set`` method or by setting the value of the
+property directly. By using the ``set`` method it is also possible to
+update multiple properties at once, by passing in an associative array:
+
+.. code-block:: php
+
+    <?php
+    $person = ORM::for_table('person')->find_one(5);
+
+    // The following two forms are equivalent
+    $person->set('name', 'Bob Smith');
+    $person->age = 20;
+
+    // This is equivalent to the above two assignments
+    $person->set(array(
+        'name' => 'Bob Smith',
+        'age'  => 20
+    ));
+
+    // Syncronise the object with the database
+    $person->save();
+
+Properties containing expressions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is possible to set properties on the model that contain database
+expressions using the ``set_expr`` method.
+
+.. code-block:: php
+
+    <?php
+    $person = ORM::for_table('person')->find_one(5);
+    $person->set('name', 'Bob Smith');
+    $person->age = 20;
+    $person->set_expr('updated', 'NOW()');
+    $person->save();
+
+The ``updated`` column's value will be inserted into query in its raw
+form therefore allowing the database to execute any functions referenced
+- such as ``NOW()`` in this case.
+
+Creating new records
+~~~~~~~~~~~~~~~~~~~~
+
+To add a new record, you need to first create an "empty" object
+instance. You then set values on the object as normal, and save it.
+
+.. code-block:: php
+
+    <?php
+    $person = ORM::for_table('person')->create();
+
+    $person->name = 'Joe Bloggs';
+    $person->age = 40;
+
+    $person->save();
+
+After the object has been saved, you can call its ``id()`` method to
+find the autogenerated primary key value that the database assigned to
+it.
+
+Properties containing expressions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is possible to set properties on the model that contain database
+expressions using the ``set_expr`` method.
+
+.. code-block:: php
+
+    <?php
+    $person = ORM::for_table('person')->create();
+    $person->set('name', 'Bob Smith');
+    $person->age = 20;
+    $person->set_expr('added', 'NOW()');
+    $person->save();
+
+The ``added`` column's value will be inserted into query in its raw form
+therefore allowing the database to execute any functions referenced -
+such as ``NOW()`` in this case.
+
+Checking whether a property has been modified
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To check whether a property has been changed since the object was
+created (or last saved), call the ``is_dirty`` method:
+
+.. code-block:: php
+
+    <?php
+    $name_has_changed = $person->is_dirty('name'); // Returns true or false
+
+Deleting records
+~~~~~~~~~~~~~~~~
+
+To delete an object from the database, simply call its ``delete``
+method.
+
+.. code-block:: php
+
+    <?php
+    $person = ORM::for_table('person')->find_one(5);
+    $person->delete();
+
+To delete more than one object from the database, build a query:
+
+.. code-block:: php
+
+    <?php
+    $person = ORM::for_table('person')
+        ->where_equal('zipcode', 55555)
+        ->delete_many();
+