Author: guilhermeblanco
Date: 2008-08-27 07:20:38 +0100 (Wed, 27 Aug 2008)
New Revision: 4846
Added:
branches/1.0/docs/manual/en/dql-doctrine-query-language/named-queries.txt
Modified:
branches/1.0/docs/manual/en/dql-doctrine-query-language.txt
Log:
Include documentation of Named Query support.
Added: branches/1.0/docs/manual/en/dql-doctrine-query-language/named-queries.txt
===================================================================
--- branches/1.0/docs/manual/en/dql-doctrine-query-language/named-queries.txt
(rev 0)
+++ branches/1.0/docs/manual/en/dql-doctrine-query-language/named-queries.txt
2008-08-27 06:20:38 UTC (rev 4846)
@@ -0,0 +1,103 @@
+When you are dealing with a model that may change, but you need to keep your
queries easily updated, you need to find
+an easy way to define queries. Imagine for example that you change one field
and you need to follow all queries in your
+application to make sure it'll not break anything.
+
+Named Queries is a nice and effective way to solve this situation, allowing
you to create Doctrine_Queries and reuse them
+without the need to keep rewritting them.
+
+The Named Query support is built at the top of Doctrine_Query_Registry
support. Doctrine_Query_Registry is a class for
+registering and naming queries. It helps with the organization of your
applications queries and along with that it offers
+some very nice convenience stuff.
+
+The queries are added using the add() method of the registry object. It takes
two parameters, the query name and the actual
+DQL query.
+
+<code type="php">
+$r = Doctrine_Manager::getInstance()->getQueryRegistry();
+
+$r->add('User/all', 'FROM User u');
+
+$userTable = Doctrine::getTable('User');
+
+// find all users
+$users = $userTable->find('all');
+</code>
+
+To simplify this support, Doctrine_Table support some accessors to
Doctrine_Query_Registry.
+
++++ Creating a Named Query
+
+When you build your models with option generateTableClasses defined as true,
each record class will also generate a
+*Table class, extending from Doctrine_Table.
+
+Then, you can implement the method construct() to include your Named Queries:
+
+<code type="php">
+class MyFooTable extends Doctrine_Table
+{
+ public function construct()
+ {
+ // Named Query defined using DQL string
+ $this->addNamedQuery('get.by.id', 'SELECT f.* FROM MyFoo f WHERE f.id
= ?');
+
+ // Named Query defined using Doctrine_Query object
+ $this->addNamedQuery(
+ 'get.by.similar.names', Doctrine_Query::create()
+ ->select('f.id, f.value0')
+ ->from('MyFoo f')
+ ->where('LOWER(f.name) LIKE LOWER(?)')
+ );
+ }
+}
+</code>
+
++++ Accessing Named Query
+
+To reach the MyFooTable class, which is a subclass of Doctrine_Table, you can
do the following:
+
+<code type="php">
+$MyFooTableInstance = Doctrine::getTable('MyFoo');
+</code>
+
+To access the Named Query (will return you a Doctrine_Query instance, always):
+
+<code type="php">
+$query = $MyFooTableInstance->createNamedQuery('get.by.id');
+</code>
+
++++ Executing a Named Query
+
+There are two ways to execute a Named Query. The first one is by retrieving
the Doctrine_Query and then executing
+it normally, as a normal instance:
+
+<code type="php">
+$fooItems = Doctrine::getTable('MyFoo')
+ ->createNamedQuery('get.by.similar.names')
+ ->execute(array('%jon%wage%'));
+</code>
+
+You can also simplify the execution, by doing:
+
+<code type="php">
+$fooItems = Doctrine::getTable('MyFoo')
+ ->find('get.by.similar.names', array('%jon%wage%'));
+</code>
+
+The method find() also accepts a third parameter, which is the hydration mode.
+
++++ Cross-Acessing Named Query
+
+If that's not enough, Doctrine take advantage the Doctrine_Query_Registry and
uses namespaced queries to enable
+cross-access of Named Queries between objects.
+Suppose you have the *Table class instance of record "MyBar". You want to call
the "get.by.id" Named Query of record
+"MyFoo". To acess the Named Query, you have to do:
+
+<code type="php">
+$MyBarTable = Doctrine::getTable('MyBar');
+
+// ...
+
+$MyFooItems = $MyBarTable->find('MyFoo/get.by.id', array(1, 2, 3),
Doctrine::HYDRATE_RECORD);
+
+// MyFooItems is a Doctrine_Collection, with MyFoo records (Doctrine_Record).
+</code>
\ No newline at end of file
Modified: branches/1.0/docs/manual/en/dql-doctrine-query-language.txt
===================================================================
--- branches/1.0/docs/manual/en/dql-doctrine-query-language.txt 2008-08-27
05:44:41 UTC (rev 4845)
+++ branches/1.0/docs/manual/en/dql-doctrine-query-language.txt 2008-08-27
06:20:38 UTC (rev 4846)
@@ -13,42 +13,8 @@
++ ORDER BY clause
++ LIMIT and OFFSET clauses
++ Examples
-++ The Query Registry
-
-Doctrine_Query_Registry is a class for registering and naming queries. It
helps with the organization of your applications
-queries and along with that it offers some very nice convenience stuff.
-
-The queries are added using the add() method of the registry object. It takes
two parameters, the query name and the actual
-DQL query.
-
-<code type="php">
-$r = Doctrine_Manager::getInstance()->getQueryRegistry();
-
-$r->add('all-users', 'FROM User u');
-</code>
-
-+++ Namespaces
-
-The Query registry supports namespaces. The namespace is separated from the
actual name with / -mark. If the name of the
-namespace is a record name the given record has all the named queries
available in its local scope.
-
-<code type="php">
-$r = Doctrine_Manager::getInstance()->getQueryRegistry();
-
-$r->add('User/all', 'FROM User u');
-$r->add('User/byName', 'FROM User u WHERE u.name = ?');
-
-$userTable = Doctrine::getTable('User');
-
-// find the user named Jack Daniels
-$user = $userTable->findOneByName('Jack Daniels');
-
-// find all users
-$users = $userTable->find('all');
-</code>
-
+++ Named Queries
++ BNF
-
++ Magic Finders
Doctrine offers some magic finders for your Doctrine models that allow you to
find a record by any column that is present
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"doctrine-svn" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.co.uk/group/doctrine-svn?hl=en-GB
-~----------~----~----~----~------~----~------~--~---
