5bc9d104a6
Sorry for the trigger happy commits, but with each one I'm actaully trying to fix some post-commit script magic :)
315 lines
10 KiB
XML
315 lines
10 KiB
XML
<?xml version="1.0" encoding='ISO-8859-1'?>
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
|
|
|
|
[
|
|
<!ENTITY version "2.0">
|
|
]>
|
|
|
|
<book id="doctrinebook">
|
|
|
|
<bookinfo>
|
|
<title>Doctrine Documentation</title>
|
|
<author>
|
|
<firstname>Konsta</firstname>
|
|
<surname>Vesterinen</surname>
|
|
</author>
|
|
<author>
|
|
<firstname>Ian</firstname>
|
|
<surname>Christian</surname>
|
|
<email>pookey@pookey.co.uk</email>
|
|
</author>
|
|
<copyright>
|
|
<holder>Doctrine Project</holder>
|
|
<year>2007</year>
|
|
</copyright>
|
|
<legalnotice id="legalnotice">
|
|
<para>
|
|
The contents of this document are licensed under the Creative Commons
|
|
<ulink url="http://creativecommons.org/licenses/by-sa/2.0/">Attribution-ShareAlike License</ulink>.
|
|
</para>
|
|
</legalnotice>
|
|
|
|
<abstract>
|
|
<para>
|
|
Documentation for the PHP Doctrine project.
|
|
</para>
|
|
<para>
|
|
This document was generated <?dbtimestamp format="Y-m-d H:M:S"?>.
|
|
</para>
|
|
</abstract>
|
|
</bookinfo>
|
|
|
|
<chapter id="introduction">
|
|
<title>Introduction</title>
|
|
<sect1 id="about-doctrine">
|
|
<title>About Doctrine</title>
|
|
<para>
|
|
Doctrine is a Object Relational Mapping and database abstraction
|
|
framework for PHP. The DBAL part of Doctrine derives from MDB2. The key
|
|
idea was to provide very intuitive and easy-to-use persistency solution
|
|
(eg. RoR ActiveRecord) with all the advanced features from the more
|
|
heavy-weight solutions (eg. Hibernate).
|
|
</para>
|
|
<para>
|
|
Doctrine Query Language implements EJB 3 OQL specificiation and expands
|
|
it a bit further (it has special LIMIT and OFFSET clauses).
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="requirements">
|
|
<title>Requirements</title>
|
|
<para>
|
|
Doctrine requires PHP >= 5.1, and it doesn't require any external libraries.
|
|
</para>
|
|
<para>
|
|
For database abstraction Doctrine uses PDO which is bundled with php by
|
|
default. Doctrine also requires a little adodb-hack for table creation,
|
|
which comes with doctrine.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="community">
|
|
<title>Community</title>
|
|
<para>
|
|
Doctrine has 3 mailing lists, an IRC forum, and a wiki.
|
|
</para>
|
|
<sect2 id="community-mailinglist">
|
|
<title>Mailing Lists</title>
|
|
<para>
|
|
The 'user' mailing list is for discussing the usage of doctrine.
|
|
To subscribe to this list, send a blank email to
|
|
<email>doctrine-user+subscribe@lists.pengus.net</email>
|
|
</para>
|
|
<para>
|
|
The 'dev' mailing list is used for discussion of the development
|
|
of doctrine. To subscribe to this list, send a blank email to
|
|
<email>doctrine-dev+subscribe@lists.pengus.net</email>
|
|
</para>
|
|
<para>
|
|
The 'svn' mailing list is a read-only list, which users and developers
|
|
can subscribe to to receive commit logs to the SVN repository. This
|
|
list is quite high traffic, as every commit to the repository results
|
|
in an email containing the changelog entry and diffs of the changed
|
|
files.
|
|
To subscribe to this list, send a blank email to
|
|
<email>doctrine-svn+subscribe@lists.pengus.net</email>
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="community-irc">
|
|
<title>IRC</title>
|
|
<para>
|
|
The #doctrine IRC channel can be found on the freenode network.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="contributing">
|
|
<title>Contributing</title>
|
|
<para>
|
|
Doctrine is constantly under development, and is always happy for new
|
|
developers to contribute to the project.
|
|
</para>
|
|
<para>
|
|
To get an account on trac to submit bugs and make suggestions, or to get
|
|
access to commit to the SVN repository, please visit the IRC channel, or
|
|
email the users mailing list.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="installation">
|
|
<title>Installation</title>
|
|
<para>
|
|
As of the time of writing, there is no stable release of doctrine. That is not to say
|
|
that it's unstable, but simply that the best way to install it is to aquire it from
|
|
SVN.
|
|
</para>
|
|
<para>
|
|
To get the latest copy, simple check out 'trunk' from SVN. You will need subversion
|
|
install to check out doctrine. If you are unable to install subversion for whatever
|
|
reason, see below for details on downloading a snapshot.
|
|
</para>
|
|
<screen>
|
|
<prompt>bash $</prompt><command>svn checkout http://doctrine.pengus.net/svn/trunk</command>
|
|
</screen>
|
|
<para>
|
|
Daily snapshots can be found at
|
|
<ulink url="http://doctrine.pengus.net/downloads/">http://doctrine.pengus.net/downloads/</ulink>
|
|
and the latest daily snapshot can always be found at
|
|
<ulink url="http://doctrine.pengus.net/downloads/latest-snapshot.tar.gz">http://doctrine.pengus.net/downloads/latest-snapshot.tar.gz</ulink>
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="include-and-autoload">
|
|
<title>Include and autoload</title>
|
|
<para>
|
|
In order to use Doctrine in your project it must first be included.
|
|
</para>
|
|
<programlisting role="php"><![CDATA[
|
|
<?php
|
|
require_once('path-to-doctrine/lib/Doctrine.php');
|
|
?>]]></programlisting>
|
|
<para>
|
|
Doctrine support <ulink
|
|
url="http://www.php.net/autoload">Autoloading</ulink> for including
|
|
files so that you do not have to include anything more then the base
|
|
file. There are two different strategies that can be used to do this:
|
|
</para>
|
|
|
|
<para>
|
|
If you do use the <emphasis>__autoload</emphasis> function for your own
|
|
logic you can use it.
|
|
</para>
|
|
<programlisting role="php"><![CDATA[
|
|
<?php
|
|
function __autoload($class) {
|
|
Doctrine::autoload($class);
|
|
}
|
|
?>]]></programlisting>
|
|
|
|
<para>
|
|
If your project uses autoload and/or you have other libraries that use
|
|
it you could use <ulink
|
|
url="http://www.php.net/manual/en/function.spl-autoload-register.php">spl_autoload_register</ulink>
|
|
to register more then one autoloading function.
|
|
</para>
|
|
|
|
<programlisting role="php"><![CDATA[
|
|
<?php
|
|
spl_autoload_register(array('Doctrine', 'autoload'));
|
|
?>]]></programlisting>
|
|
</sect1>
|
|
|
|
<sect1 id="compiling">
|
|
<title>Compiling</title>
|
|
<para>
|
|
Compiling is a method for making a single file of most used doctrine
|
|
runtime components including the compiled file instead of multiple files
|
|
(in worst cases dozens of files) can improve performance by an order of
|
|
magnitude. In cases where this might fail, a Doctrine_Exception is throw
|
|
detailing the error.
|
|
</para>
|
|
<programlisting role="php"><![CDATA[
|
|
<?php
|
|
Doctrine::compile();
|
|
|
|
// on some other script:
|
|
require_once('path_to_doctrine/Doctrine.compiled.php');
|
|
?>]]></programlisting>
|
|
</sect1>
|
|
|
|
<sect1 id="new-project">
|
|
<title>Starting a new project</title>
|
|
<para>
|
|
Doctrine_Record is the basic component of every doctrine-based project.
|
|
There should be atleast one Doctrine_Record for each of your database
|
|
tables. Doctrine_Record follows the <ulink
|
|
url="http://www.martinfowler.com/eaaCatalog/activeRecord.html">Active
|
|
Record pattern</ulink>
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<chapter id="connection-management">
|
|
<title>Connection Management</title>
|
|
</chapter>
|
|
|
|
<chapter id="object-relational-mapping">
|
|
<title>Object Relational Mapping</title>
|
|
</chapter>
|
|
|
|
<chapter id="working-with-objects">
|
|
<title>Working With Objects</title>
|
|
</chapter>
|
|
|
|
<chapter id="configuration">
|
|
<title>Configuration</title>
|
|
</chapter>
|
|
|
|
<chapter id="advanced-components">
|
|
<title>Advanced Components</title>
|
|
</chapter>
|
|
|
|
<chapter id="dql">
|
|
<title>DQL (Doctrine Query Lanaguage)</title>
|
|
<sect1 id="dql-intro">
|
|
<title>Introduction</title>
|
|
<para>
|
|
Doctrine Query Language(DQL) is an Object Query Language created for helping users in complex object retrieval.
|
|
</para>
|
|
<para>
|
|
You should always consider using DQL(or raw SQL) when retrieving relational data efficiently (eg. when fetching users and their phonenumbers).
|
|
</para>
|
|
<para>
|
|
When compared to using raw SQL, DQL has several benefits:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para>From the start it has been designed to retrieve records(objects) not result set rows.</para></listitem>
|
|
<listitem><para>DQL understands relations so you don't have to type manually sql joins and join conditions.</para></listitem>
|
|
<listitem><para>DQL is portable on different databases</para></listitem>
|
|
<listitem><para>DQL has some very complex built-in algorithms like (the record limit algorithm) which can help developer to efficiently retrieve objects.</para></listitem>
|
|
<listitem><para>It supports some functions that can save time when dealing with one-to-many, many-to-many relational data with conditional fetching.</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
If the power of DQL isn't enough, you should consider using the rawSql API for object population.
|
|
</para>
|
|
|
|
<programlisting role="php"><![CDATA[
|
|
<?php
|
|
// DO NOT USE THE FOLLOWING CODE
|
|
// (using many sql queries for object population):
|
|
|
|
$users = $conn->getTable('User')->findAll();
|
|
foreach($users as $user) {
|
|
print $user->name."\n";
|
|
foreach($user->Phonenumber as $phonenumber) {
|
|
print $phonenumber."\n";
|
|
}
|
|
}
|
|
|
|
// same thing implemented much more efficiently:
|
|
// (using only one sql query for object population)
|
|
|
|
$users = $conn->query("FROM User.Phonenumber");
|
|
foreach($users as $user) {
|
|
print $user->name."\n";
|
|
foreach($user->Phonenumber as $phonenumber) {
|
|
print $phonenumber."\n";
|
|
}
|
|
}
|
|
?>]]></programlisting>
|
|
</sect1>
|
|
|
|
</chapter>
|
|
|
|
<chapter id="native-sql">
|
|
<title>Native SQL</title>
|
|
</chapter>
|
|
|
|
<chapter id="transactions">
|
|
<title>Transactions</title>
|
|
</chapter>
|
|
|
|
<chapter id="caching">
|
|
<title>Caching</title>
|
|
</chapter>
|
|
|
|
<chapter id="database-abstraction">
|
|
<title>Database Abstraction</title>
|
|
</chapter>
|
|
|
|
<chapter id="technology">
|
|
<title>Technology</title>
|
|
</chapter>
|
|
|
|
<chapter id="real-world-examples">
|
|
<title>Real World Examples</title>
|
|
</chapter>
|
|
|
|
<chapter id="coding-standards">
|
|
<title>Coding Standards</title>
|
|
</chapter>
|
|
|
|
</book>
|