more docs on orm

developer_manual/app/appframework/database.rst

@@ -3,9 +3,16 @@ Database Access
 
 .. sectionauthor:: Bernhard Posselt <nukeawhale@gmail.com>
 
-Your database layer should go into the **db/** folder. It's recommended to split the data entities from the database queries. You can do that by creating a very simple PHP object which extends the class :php:class:`\\OCA\\AppFramework\\Db\\Entity`. This object will hold the data. 
+Your database layer should go into the **db/** folder. It's recommended to split the data entities from the database queries. You can do that by creating a very simple PHP object which extends the class :php:class:`OCA\\AppFramework\\Db\\Entity`. This object will hold the data. 
 
-Getters and setters will automatically be created for all public attributes. Should it be required to use special setter or getters, simply create the method. Make sure to mark the field as updated though if it was set by passing the fieldname to the **markFieldUpdated()** method.
+Getters and setters will automatically be created for all public attributes. Should it be required to use special setter or getters, simply create the method. Make sure to mark the field as updated by calling the parent method.
+
+.. note:: Setters mark a field as updated. The :php:meth:`OCA\\AppFramework\\Db\\Entity::fromRow` method should only be used to pass in rows from a database result. Fields will not be marked as updated by using :php:meth:`OCA\\AppFramework\\Db\\Entity::fromRow`!
+
+:php:meth:`OCA\\AppFramework\\Db\\Entity::fromRow` maps the database columns to attributes. The conversion works like the this:
+
+* database field **my_name** gets transformed to attribute myName.
+* the attribute myAwesomeProperty gets transformed to the column my_awesome_property
 
 .. versionchanged:: 6.0 Instead of manually creating and mapping all the entities, this is is now done by extending a parent class.
 
@@ -27,14 +34,15 @@ Getters and setters will automatically be created for all public attributes. Sho
 
       // transform username to lower case
       public function function setName($name){
-          $this->markFieldUpdated('name');
-          $this->name = strtolower($name);
+          $name = strtolower($name);
+          parent::setName($name);
       }
 
   }
 
 
-All database queries for that object should be put into a mapper class. This follows the `data mapper pattern <http://www.martinfowler.com/eaaCatalog/dataMapper.html>`_. Simply inherit the :php:class:`\\OCA\\AppFramework\\Db\\Mapper`
+All database queries for that object should be put into a mapper class. This follows the `data mapper pattern <http://www.martinfowler.com/eaaCatalog/dataMapper.html>`_. Simply inherit the :php:class:`OCA\\AppFramework\\Db\\Mapper`.
+
 
 .. versionchanged:: 6.0: Methods from the old mapper have been removed and deprecated to allow a small ORM.
 
@@ -48,7 +56,7 @@ All database queries for that object should be put into a mapper class. This fol
   use \OCA\AppFramework\Db\Mapper;
 
 
-      class ItemMapper extends Mapper {
+  class ItemMapper extends Mapper {
 
 
       public function __construct(API $api) {
@@ -61,6 +69,8 @@ All database queries for that object should be put into a mapper class. This fol
           'WHERE `id` = ? ' .
           'AND `user_id` = ?';
 
+        // use findOneQuery to throw exceptions when no entry or more than one
+        // entries were found
         $row = $this->findOneQuery($sql, array($id, $userId));
         $feed = new Item();
         $feed->fromRow($row);
@@ -69,6 +79,17 @@ All database queries for that object should be put into a mapper class. This fol
       }
 
 
+      public function findByName($name){
+        $sql = 'SELECT * FROM `' . $this->getTableName() . '` ' .
+        'WHERE `name` = ? ';
+
+        $row = $this->execute($sql, array($name));
+        $feed = new Item();
+        $feed->fromRow($row);
+
+        return $feed;
+      }
+
   }
 
 .. note:: Always use **?** to mark placeholders for arguments in SQL queries and pass the arguments as a second parameter to the execute function to prevent `SQL Injection <http://php.net/manual/en/security.database.sql-injection.php>`_
@@ -92,3 +113,36 @@ All database queries for that object should be put into a mapper class. This fol
 
   $result = $this->execute($sql, $params);
 
+
+The mapper class comes with simple methods for deleting, updating and finding items. To delete a database entry, simply pass an entity with a set id to the :php:meth:`OCA\\AppFramework\\Db\\Mapper::delete` method.
+
+Example:
+
+.. code-block:: php
+
+  <?php
+
+  // delete the item with id 4
+  $item = new Item();
+  $item->setId(4);
+
+  $mapper = new ItemMapper($api); // inject API class for db access
+  $mapper->delete($item);
+
+
+The same works for updating. Only the fields which have been set with setters will be updated.
+
+Example:
+
+.. code-block:: php
+
+  <?php
+
+  // change the name of item with id 4
+  $item = new Item();
+  $item->setId(4);
+  $item->setName('tony');
+
+
+  $mapper = new ItemMapper($api); // inject API class for db access
+  $mapper->update($item);