cvs: peardoc /en/package/database db-dataobject.xml /en/package/database/db-dataobject intro-relations.xml
/en/package/database/db-dataobject/db-dataobject selectas.xml

From: Date: Thu, 15 May 2003 16:40:59 +0000
Subject: cvs: peardoc /en/package/database db-dataobject.xml /en/package/database/db-dataobject intro-relations.xml
/en/package/database/db-dataobject/db-dataobject selectas.xml
Groups: php.pear.doc 
Request: Send a blank email to pear-doc+get-824@lists.php.net to get a copy of this message
alan_k Thu May 15 12:40:59 2003 EDT Added files: /peardoc/en/package/database/db-dataobject/db-dataobject selectas.xml Modified files: /peardoc/en/package/database db-dataobject.xml /peardoc/en/package/database/db-dataobject intro-relations.xml Log: add selectas, tidy up the links and joins introduction, wow getting some examples...

Index: peardoc/en/package/database/db-dataobject.xml diff -u peardoc/en/package/database/db-dataobject.xml:1.7 peardoc/en/package/database/db-dataobject.xml:1.8 --- peardoc/en/package/database/db-dataobject.xml:1.7 Wed May 14 09:03:09 2003 +++ peardoc/en/package/database/db-dataobject.xml Thu May 15 12:40:59 2003 @@ -1,4 +1,4 @@ -<!-- $Revision: 1.7 $ --> +<!-- $Revision: 1.8 $ --> <sect1 id="package.database.db-dataobject"> <title>DB_DataObject</title> @@ -54,6 +54,7 @@ &package.database.db-dataobject.db-dataobject.getlinkarray; --> + &package.database.db-dataobject.db-dataobject.selectas; &package.database.db-dataobject.db-dataobject.joinadd; <!-- other usefull stuff --> Index: peardoc/en/package/database/db-dataobject/intro-relations.xml diff -u peardoc/en/package/database/db-dataobject/intro-relations.xml:1.1 peardoc/en/package/database/db-dataobject/intro-relations.xml:1.2 --- peardoc/en/package/database/db-dataobject/intro-relations.xml:1.1 Tue Jan 14 03:22:58 2003 +++ peardoc/en/package/database/db-dataobject/intro-relations.xml Thu May 15 12:40:59 2003 @@ -3,7 +3,7 @@ <refnamediv> <refname>Automatic Table Linking and Joins</refname> <refpurpose> - Automatic Table Linking - ::getLink(), ::getLinks(), ::joinAdd() + Automatic Table Linking - ::getLink(), ::getLinks(), ::joinAdd(), ::selectAs() </refpurpose> </refnamediv> @@ -17,20 +17,108 @@ can automatically fetch objects into the parents variables. </para> <para> - Currently automated links are supported by column naming conventions, this feature is depreciated in favour of - using the links.ini files. As this offers a more flexible and clearer way of performing these operations. + Automated links are supported by a databasename.links.ini file. which stores the relations ship between tables, maping + one tables column to anothers. This databasename.links.ini file is used by the getLinks() and joinAdd() Method, to + either retrieve related information of a primary object, or quickly build complex multitable queries. </para> - + <para> - The other way of using getLink() is to use it with the second parameter which is the table name of the related - table, it will then query the primary key on that table to see if it matches the value of the requested row. - In this method however the getLinks() method will not work, as it will not know the related table names. + The other way of using linking is via the getLink() method, which you can manually use without + a database.links.ini file to specify a column, and how it relates to another table and column. </para> + <para> - Recent versions of DB_DataObject also included support for table joins, this uses the same links.ini configuration - to build join queries. + The goal of getlinks and joinAdd is to make connecting two tables as simple and fast as possible, while + still ensuring that the code is reasonably comprehensable. In the example below, It is demostrated how + getlinks() can be used to fetch more data about an object after the initial fetch, and it can also be used to + test the links file prior to building a full blown join Query. + + <example> + <title> A simple introduction to links and joins</title> + <programlisting role="php"><![CDATA[ + +// just loop and fetch more information + +$person = new DataObjects_Person; +$person->eyeColour = 'red'; +$person->find(); +while ($person->find()) { + // this will look up in the cars table for the id matching the person->car value. + + $car = $person->getLink('car','cars','id'); + + echo "{$person->name} has red eyes and owns a {$car->type}\n"; +} + + + + + +// now if you create a database.links.ini file with the car example +// the example would look like this. + +$person = new DataObjects_Person; +$person->eyeColour = 'red'; +$person->find(); +while ($person->find()) { + + // use the links.ini file to automatically load + // the car object into $person->_car + $person->getLinks(); + + echo "{$person->name} has red eyes and owns a {$person->_car->type}\n"; +} + + + + + + +// and finally the most complex, using SQL joins and select as. +// the example would look like this. + +$person = new DataObjects_Person; +$person->eyeColour = 'red'; + +// first, use selectAs as to make the select clauses match the column names. +$person->selectAs(); + +// now lets create the related element +$car = new DataObjects_Car; + +// and for fun.. lets look for red eys and red cars.. +$car->colour = 'red'; + +// add them together. +$person->joinAdd($car); + +// since both tables have the column id in them, we need to reformat the query so +// that the car columns have a different name. + +$person->selectAs($car,'car_%s'); + + + + +$person->find(); +while ($person->find()) { + + echo "{$person->name} has red eyes and owns a {$person->car_type}\n"; +} + + + + + + + ]]> + </programlisting> + </example> + </para> + + </refsect1> @@ -38,14 +126,20 @@ <title>Using link ini files for table links</title> <para> DB_DataObject Version 0.3 introduced the ability to create link ini files so you can map rows to other database - columns using an ini file this ini file should have the name databasename.links.ini, and be placed in the - same folder as the databasename.ini file that is created automatically by createTables.php + columns using an ini file this ini file should have the name 'databasename.links.ini', and be placed in the + same folder as the database schema ini file 'databasename.ini' file that is created automatically by createTables.php </para> <para> - The Ini file contains a section for each table, then the row that is linked equal to the table and row - that it should locate the row from. If you use a 'full stop' in the key (link from column), getLinks() will + The databasename.links.ini file contains a section for each table, then the row that is linked equal to + the table and row that it should locate the row from. It assumes the relationships are non-primary id to primary id, + as the example below shows, the person.owner is linked to grp.id. This indicates that running getLinks() on the + person object, will fetch a single bit of data from 3 tables - colurs,grp,attachments. + </para> + <para> + If you use a 'full stop' in the key (link from column), getLinks() will look up in the table with the row name matching the string to the left of the 'full stop', and replace the - 'full stop' with and underscore and assign the object variable to that name. + 'full stop' with and underscore and assign the object variable to that name. Or you may wish to use the + selectAs() method to decide how you want columns from different objects to be returned (when using joinAdd()) <example> <title> An example databasename.links.ini file</title> <programlisting role="ini"><![CDATA[ Index: peardoc/en/package/database/db-dataobject/db-dataobject/selectas.xml +++ peardoc/en/package/database/db-dataobject/db-dataobject/selectas.xml <!-- $Revision: 1.1 $ --> <refentry id="package.database.db-dataobject.db-dataobject.selectas"> <refnamediv> <refname>-&gt;selectAs()</refname> <refpurpose>Build the select component of a query (usually for joins)</refpurpose> </refnamediv> <refsynopsisdiv> <funcsynopsis> <funcprototype> <funcdef>void <function>$DB_DataObject-&gt;selectAs</function></funcdef> <paramdef> object | array <parameter><optional>$columns_or_object</optional></parameter> string <parameter><optional>$format</optional></parameter> string <parameter><optional>$table_name</optional></parameter> </paramdef> </funcprototype> </funcsynopsis> </refsynopsisdiv> <refsect1 id="package.database.db-dataobject.db-dataobject.selectas.desc"> &title.desc; <para> Auto creates select items based on either the current objects column names, the supplied object, or an array. </para> <para> This is primarily used in conjunciton with joinAdd, to enable the renaming of columns into a fixed format when they are likely to have naming conflicts (like both tables have an 'id' column). </para> <para> Sending no arguments to selectAs, will reset the current select (usually removing the default *), and build a select list based on the current objects column names. </para> </refsect1> <refsect1 id="package.database.db-dataobject.db-dataobject.selectas.parameter"> &title.param; <para> <itemizedlist> <listitem> <para> <parameter>object | array $column_or_object</parameter> - a dataobject or array of column names </para> </listitem> <listitem> <para> <parameter>string $format</parameter> - the format the columns will appear, using sprintf format, the %s is replaced with the column name so car_%s would result in the SQL 'car.name as car_name' being generated. </para> </listitem> <listitem> <para> <parameter>string $tableName</parameter> - this is used either when use send an array as the first argument, or when you are joining a table 'as' another name, </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1 id="package.database.db-dataobject.db-dataobject.selectas.note"> &title.note; &note.notstatic; <simpara></simpara> </refsect1> <refsect1 id="package.database.db-dataobject.db-dataobject.selectas.example"> &title.example; <example> <title>Using <function>selectAs</function></title> <programlisting role="php"> <![CDATA[ // ok lets see what is going on.. DB_DataObject::debugLevel(1); $person = new DataObjects_Person; // to generate "person.id as id , person.name as name ......." $person->selectAs(); // to generate a restricted list.. "person.age as age , person.name as name" $person->selectAs(array('age','name')); // using another object. $car = new DataObjects_Car; // this is the first car ( $car->use = 'first'; // using the joinadd add the car.. $person->joinAdd($car); // now add all the select columsn for the car eg. "car.id as car_id, car.name as car_name ...." $person->selectAs($car, 'car_%s'); // now the user can have a second car.... $secondcar = new DataObjects_Car; $secondcar->use = 'second'; // now since we alreay have one car, the sql statement would get messy // so we are joining this as the second car "FROM person INNER JOIN car ..... , car as secondcar WHERE ..... $person->joinAdd($secondcar,'','secondcar'); // and we can now add all the columns // "secondcar.id as secondcar_id, secondcar.name as secondcar_name ........ // note that you must use the last field as the SECONDCAR.ID format uses the 'AS' name, rather than the // objects real table name 'car' $person->selectAs($secondcar, 'secondcar_%s','secondcar'); // ok fire of a query... $person->find(); while ($person->fetch()) { ...... } ]]> </programlisting> </example> </refsect1> </refentry> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"../../../../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 -->
« previous php.pear.doc (#824) next »