cvs: peardoc /peardoc2/en/package/database db-dataobject.xml /peardoc2/en/package/database/db-dataobject example.xml intro-autobuilding.xml
intro-configuration.xml intro-purpose.xml intro.xml

From: Date: Sat, 04 Jan 2003 18:26:07 +0000
Subject: cvs: peardoc /peardoc2/en/package/database db-dataobject.xml /peardoc2/en/package/database/db-dataobject example.xml intro-autobuilding.xml
intro-configuration.xml intro-purpose.xml intro.xml
Groups: php.pear.doc 
Request: Send a blank email to pear-doc+get-204@lists.php.net to get a copy of this message
alexmerz Sat Jan 4 13:26:07 2003 EDT Added files: /peardoc/peardoc2/en/package/database db-dataobject.xml /peardoc/peardoc2/en/package/database/db-dataobject example.xml intro-autobuilding.xml intro-configuration.xml intro-purpose.xml intro.xml Log: add DB_Dataobjects, still requires a lot of work

Index: peardoc/peardoc2/en/package/database/db-dataobject.xml +++ peardoc/peardoc2/en/package/database/db-dataobject.xml <!-- $Revision: 1.1 $ --> <sect1 id="package.database.db-dataobject"> <title>DB_DataObject</title> <para> SQL Builder and Data Modeling Layer </para> <para> This chapter describes how to use the DB_DataObject SQL Builder and Data Modeling layer </para> &package.database.db-dataobject.intro-purpose; &package.database.db-dataobject.intro-configuration; &package.database.db-dataobject.intro-autobuilding; &package.database.db-dataobject.db-dataobject.get; &package.database.db-dataobject.db-dataobject.staticget; &package.database.db-dataobject.db-dataobject.find; &package.database.db-dataobject.db-dataobject.fetch; &package.database.db-dataobject.db-dataobject.whereadd; &package.database.db-dataobject.db-dataobject.orderby; &package.database.db-dataobject.db-dataobject.groupby; &package.database.db-dataobject.db-dataobject.limit; &package.database.db-dataobject.db-dataobject.selectadd; &package.database.db-dataobject.db-dataobject.insert; &package.database.db-dataobject.db-dataobject.update; &package.database.db-dataobject.db-dataobject.delete; &package.database.db-dataobject.db-dataobject.fetchrow; &package.database.db-dataobject.db-dataobject.count; &package.database.db-dataobject.db-dataobject.query; &package.database.db-dataobject.db-dataobject.getlinks; &package.database.db-dataobject.db-dataobject.getlink; &package.database.db-dataobject.db-dataobject.getlinkarray; &package.database.db-dataobject.db-dataobject.joinadd; &package.database.db-dataobject.db-dataobject.setfrom; &package.database.db-dataobject.db-dataobject.validate; &package.database.db-dataobject.db-dataobject.debug; &package.database.db-dataobject.db-dataobject.debuglevel; &package.database.db-dataobject.db-dataobject.raiseerror; &package.database.db-dataobject.db-dataobject.staticinitialize; </sect1> <!-- 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 --> Index: peardoc/peardoc2/en/package/database/db-dataobject/example.xml +++ peardoc/peardoc2/en/package/database/db-dataobject/example.xml <!-- $Revision: 1.1 $ --> <refentry id="package.database.db-dataobject.example"> <refnamediv> <refname>Example(s)</refname> <refpurpose>What for (an) Example(s)?</refpurpose> </refnamediv> <refsect1 id="package.database.db-dataobject.example.example1"> <title></title> <para> Example description </para> <!-- the cdata section will formated "as is take care for tabulators --> <programlisting role="php"> <![CDATA[ ]]> </programlisting> </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 --> Index: peardoc/peardoc2/en/package/database/db-dataobject/intro-autobuilding.xml +++ peardoc/peardoc2/en/package/database/db-dataobject/intro-autobuilding.xml <refentry id="package.database.db-dataobject.intro-autobuilding"> <refnamediv> <refname>Auto Building</refname> <refpurpose> creating the base Classes and Database schema </refpurpose> </refnamediv> <refsect1> <title>What the Auto Builder (<command>createTables.php</command>) does</title> <para> One of the essential features of an SQL building tool is to to have some understanding of the database structure, So that Integers can be checked, and strings can be escaped. There a few ways that Querying the database for the table structure could be accomplished <itemizedlist> <listitem> <simpara>on every SQL query</simpara> </listitem> <listitem> <simpara>At the initialization of every web page.</simpara> </listitem> <listitem> <simpara>Once, while setting up the application, and store it in a file</simpara> </listitem> </itemizedlist> <classname>DB_DataObject</classname> uses the last of these, it utilizes the <ulink url="http://www.php.net/parse_ini_file"><function>parse_ini_file</function></ulink> function to read the file, so it should be reasonably fast. However this does involve a stage of setting up <classname>DB_DataObject</classname> prior to use. </para> <para> The other key concept of <classname>DB_DataObject</classname> is that you work with extended classes of <classname>DB_DataObject</classname>, which do all the 'table' related work. Setting up these classes for a large database can be time consuming, so the <command>createTables.php</command> file will automatically build the skeletons for all these class files. </para> <para> To start the auto builder simply go to the <parameter>pear/DB/DataObject/</parameter> directory, and type <command>c:\php4\php.exe createTables.php myconfig.ini</command> this will read your configuration file and generate all the base classes, along with the data definition file. </para> </refsect1> <refsect1> <title>Default Class Definition</title> <para> The default generated class looks like this. <example> <title>an generated extended class</title> <programlisting role="php"><![CDATA[ /* * Table Definition for group */ class DataObjects_Grp extends DB_DataObject { ###START_AUTOCODE /* the code below is auto generated do not remove the above tag */ var $__table='group'; // table name var $id; // int primary_key var $name; // string var $grp_owner; // int var $official; // string var $street; // string var $postcode; // string var $city; // string var $homepage; // string var $email; // string var $extra; // blob /* ZE2 compatibility trick */ function __clone() { return $this;} /* Static get */ function staticGet($k,$v=NULL) { return DB_DataObject::staticGet('DataObjects_Grp',$k,$v); } /* the code above is auto generated do not remove the tag below */ ###END_AUTOCODE } ]]> </programlisting> </example> </para> <para> The class defines the table name, and comments some of table columns for your reference, It also adds the <link linkend="package.database.db-dataobject.db-dataobject.staticget"> <function>staticGet</function></link> method, which can be used to quickly get single rows as Objects. You should add your table related code after the <constant>###END_AUTOCODE</constant>. </para> <para> The <function>__clone</function> function will only be generated on pre Zend Engine 2 applications, and it is recommended to use it so that your code will be Forward and Backward Compatible with the new engine. </para> </refsect1> <refsect1> <title>Database Definition File</title> <para> The default generated database definition file looks like this. <example> <title>Database configuration file</title> <programlisting role="ini"><![CDATA[ [group] id = 1 name = 2 grp_owner = 1 official = 2 street = 2 postcode = 2 city = 2 homepage = 2 email = 2 extra = 2 [group__keys] id = 1 ]]> </programlisting> </example> </para> <para> The blocks indicate either tables and the type of field (1=integer,2=string), or a list of keys for each table. You should not need to edit file. </para> </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 --> Index: peardoc/peardoc2/en/package/database/db-dataobject/intro-configuration.xml +++ peardoc/peardoc2/en/package/database/db-dataobject/intro-configuration.xml <refentry id="package.database.db-dataobject.intro-configuration"> <refnamediv> <refname>Configuration Options</refname> <refpurpose> Setting the defaults for database access </refpurpose> </refnamediv> <refsect1> <title>Configuration</title> <para> <classname>DB_DataObject</classname> needs to be configured before using it and auto generating classes and definitions. The easiest way to configure <classname>DB_DataObject</classname> is to use ini files (although you may also like to consider the <classname>PEAR::Config</classname> class, or your own configuration system) </para> <example> <title> This is a typical configuration file for <classname>DB_DataObject</classname></title> <programlisting role="ini"> [DB_DataObject] database = mysql://user:password@localhost/vending schema_location = /home/me/Projects/myapplication/DataObjects class_location = /home/me/Projects/myapplication/DataObjects require_prefix = DataObjects/ class_prefix = DataObjects_ </programlisting> </example> <para> To use this ini file with <classname>DB_DataObject</classname>, (and possibly any other classes that use options like this) </para> <example> <title> Setting the default options</title> <programlisting role="php"><![CDATA[ $config = parse_ini_file('example.ini',TRUE); foreach($config as $class=>$values) { $options = &PEAR::getStaticProperty($class,'options'); $options = $values; } ]]> </programlisting> </example> </refsect1> <!-- Config Options --> <refsect1> <title>Configuration Options - Required</title> <variablelist> <varlistentry> <term> <parameter>database</parameter> <type>DSN</type> </term> <listitem> <para> This is the default &intro.db-dsn; to connect to your database </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>schema_location</parameter> <type>directory</type> </term> <listitem> <para> The directory where the <classname>DB_DataObject</classname> database schema file is store. </para> <para> <classname>DB_DataObject</classname> stores the description of the database (Tables and Columns) in an .ini file, in this directory. This information is used to determine if the column is a string and needs quotes, or should be a number (and is checked) at SQL building time. It is quite common to store the schema in the same directory as your DataObject Classes. </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>require_prefix</parameter> <type>directory</type> </term> <listitem> <para> The Path absolute, or relative to your default include path(s), where your extended classes can be found. </para> <para> This is used by the <link linkend="package.database.db-dataobject.db-dataobject.staticget"><function>staticGet</function></link> method and the <link linkend="package.database.db-dataobject.db-dataobject.getlinks"><function>getLinks</function></link> method to auto load classes, </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>class_prefix</parameter> <type>string</type> </term> <listitem> <para> All the generated Classes are named <parameter>{class_prefix}ucfirst($table_name)</parameter>. Use this to alter the prefixed name, this is used by the <link linkend="package.database.db-dataobject.db-dataobject.staticget"><function>staticGet</function></link> and <link linkend="package.database.db-dataobject.db-dataobject.getlinks"><function>getLinks</function></link> methods </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>debug</parameter> <type>integer</type> </term> <listitem> <para> The default debugging level (default 0=off), 1= basic sql logging,2=result logging, 3=everything </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>production</parameter> <type>boolean</type> </term> <listitem> <para> if the production option is set, then debugging is totally disabled, this is done to increase performance. </para> </listitem> </varlistentry> </variablelist> </refsect1> <!-- Config Options - Multi Database --> <refsect1> <title>Configuration Options - Multiple Databases (optional)</title> <variablelist> <varlistentry> <term> <parameter>database_*</parameter> <type>string</type> </term> <listitem> <para> When you have multiple databases you can use the database_* to specify the &intro.db-dsn; for each database </para> <para> <example> <title> using multiple databases - database passwords</title> <programlisting role="ini"><![CDATA[ database_authentication = mysql://user:password@localhost/authentication database_sales = mysql://user:password@localhost/sales ]]></programlisting> </example> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>table_*</parameter> <type>string</type> </term> <listitem> <para> When you have multiple databases you can use the table_* configuration variables to map individual tables to different databases, for example </para> <para> <example> <title> using multiple databases - table settings</title> <programlisting role="ini"> table_users = authentication table_saleslog = sales table_stock = sales </programlisting> </example> </para> </listitem> </varlistentry> </variablelist> </refsect1> <!-- Config Options - BUILDER --> <refsect1> <title>Configuration Options - Builder</title> <variablelist> <varlistentry> <term> <parameter>class_location</parameter> <type>directory</type> </term> <listitem> <para> The Directory where your DataObject extended Classes are. </para> <para> Used by the Class Auto Builder when updating/writing to your class definitions. </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>extends</parameter> <type>string</type> </term> <listitem> <para> The Name of your Base Class (usually <classname>DB_DataObject</classname>) is located. </para> <para> If you wish to add a common layer of useful methods for all classes, you can set the extends_location and extends settings to a different class. the default is <parameter>'DB_DataObject'</parameter> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>extends_location</parameter> <type>directory</type> </term> <listitem> <para> The Directory where your Base Class (usually <classname>DB_DataObject</classname>) is located. </para> <para> If you wish to add a common layer of useful methods for all classes, you can set the extends_location and extends settings to a different class. the default is <parameter>'DB/DataObject.php'</parameter> </para> </listitem> </varlistentry> </variablelist> </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 --> Index: peardoc/peardoc2/en/package/database/db-dataobject/intro-purpose.xml +++ peardoc/peardoc2/en/package/database/db-dataobject/intro-purpose.xml <!-- $Revision: 1.1 $ --> <refentry id="package.database.db-dataobject.intro-purpose"> <refnamediv> <refname>Introduction</refname> <refpurpose> What DB_DataObject can do </refpurpose> </refnamediv> <refsect1> <title>Introduction</title> <para> <classname>DB_DataObject</classname> is a SQL Builder and Data Modeling Layer built on top of PEAR::&class.db;, It main purpose is to </para> <para> <itemizedlist> <listitem> <simpara>Build SQL and execute statements based on the objects variables.</simpara> </listitem> <listitem> <simpara>Group source code around the Data that they relate to.</simpara> </listitem> <listitem> <simpara>Provide a simple consistent API to access and manipulate that data.</simpara> </listitem> </itemizedlist> </para> <para> The <classname>DB_DataObject</classname> is rarely accessed directly, it is intended to be the base class which you can extend to put the code specifically relating to a particular database table. Below is an example of how you can use the end result (and extended class), </para> <example> <title>Typical usage example for <classname>PEAR::DB_DataObject</classname></title> <programlisting role="php"> <![CDATA[ // initialize the DataObject Manager require_once('PEAR.php'); $options = &PEAR::getStaticProperty('DB_DataObject','options'); $config = parse_ini_file('example.ini',TRUE); $options = $config['DB_DataObject']; // use one of the extended classes. require_once('DataObjects/Person.php'); $person = new DataObjects_Person; $person->get(12); echo $person->name; ]]> </programlisting> </example> <para> The above example illustrates the two components of the <command>DataManager</command>, by setting the options, all the core objects will be able to auto load the data definitions from a generated ini file, and know how to access the database. (multiple databases are supported - see section on configuration) </para> <para> The later half illustrates how to query and get the result for a single row. The <link linkend="package.db.db-dataobject.db-dataobject.get"><function>$person-&gt;get</function></link> would connect to the database, perform the query, fetch the result and assign the objects variables to the data returned from the query. </para> <para> In the above example, this query would be performed. </para> <programlisting role="php"> SELECT * FROM person WHERE id=12; </programlisting> <para> To make a change to the Database you would just change the value of the objects variables and call the update method. </para> <programlisting role="php"> <![CDATA[ $person = new DataObjects_Person; $person->get(12); $person->name = 'Fred'; $person->update(); ]]> </programlisting> <para> The Package includes a number of tools to make building the extended classes and configuration file; once you have made your extended classes, the idea is that any data manipulation/calculation that relates to this table, or how this table interacts with other data is placed inside the extended class. </para> <programlisting role="php"> <![CDATA[ require_once 'DB/DataObject.php'; class DataObjects_Person extends DB_DataObject { function &listMembership() { $members = new DataObjects_Members(); $members->person_id = $this->id; $members->find(); return $members; } } ]]> </programlisting> <para> In this example the <classname>Person</classname> object asks the <classname>Members</classname> Object to list all records that have the column person_id equal to the current instance's id. </para> </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 --> Index: peardoc/peardoc2/en/package/database/db-dataobject/intro.xml +++ peardoc/peardoc2/en/package/database/db-dataobject/intro.xml <!-- $Revision: 1.1 $ --> <refentry id="package.database.db-dataobject.intro"> <refnamediv> <refname>Introduction</refname> <refpurpose>What contains the intro?</refpurpose> </refnamediv> <!-- please replace the "refsect1" id part with a text related to the refsect1 title --> <refsect1 id="package.database.db-dataobject.intro.refsect1"> <title></title> <para> </para> </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 (#204) next »