doctrine2/manual/docbook/book/doctrine.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 chap1 SYSTEM "intro.xml">
<!ENTITY chap2 SYSTEM "conn-mgt.xml">
]>

<book id="doctrinebook">

  <bookinfo>
    <title>Doctrine Documentation</title>
    <author>
      <firstname>Konsta</firstname>
      <surname>Vesterinen</surname>
      <authorblurb>The creator and lead developer.</authorblurb>
    </author>
    <author>
      <firstname>Ian</firstname>
      <othername>P.</othername>
      <surname>Christian</surname>
      <email>pookey@pookey.co.uk</email>
      <authorblurb>Junior developer and documentation maintainer.</authorblurb>
    </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>

  &chap1;
  &chap2;

  <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>