# Doctrine Documentation

Konsta
Vesterinen
Ian
Christian
pookey@pookey.co.uk
Doctrine Project
2007

The contents of this document are licensed under the Creative Commons Attribution-ShareAlike License.

Documentation for the PHP Doctrine project.

This document was generated .

## Introduction

### About Doctrine

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

Doctrine Query Language implements EJB 3 OQL specificiation and expands it a bit further (it has special LIMIT and OFFSET clauses).

### Requirements

Doctrine requires PHP >= 5.1, and it doesn't require any external libraries.

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.

### Community

Doctrine has 3 mailing lists, an IRC forum, and a wiki.

#### Mailing Lists

The 'user' mailing list is for discussing the usage of doctrine. To subscribe to this list, send a blank email to doctrine-user+subscribe@lists.pengus.net

The 'dev' mailing list is used for discussion of the development of doctrine. To subscribe to this list, send a blank email to doctrine-dev+subscribe@lists.pengus.net

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 doctrine-svn+subscribe@lists.pengus.net

#### IRC

The #doctrine IRC channel can be found on the freenode network.

### Contributing

Doctrine is constantly under development, and is always happy for new developers to contribute to the project.

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.

### Installation

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.

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.

            bash $svn checkout http://doctrine.pengus.net/svn/trunk

Daily snapshots can be found at http://doctrine.pengus.net/downloads/ and the latest daily snapshot can always be found at http://doctrine.pengus.net/downloads/latest-snapshot.tar.gz

### Include and autoload

In order to use Doctrine in your project it must first be included.

    <?php
      require_once('path-to-doctrine/lib/Doctrine.php');
    ?>

Doctrine support Autoloading 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:

If you do use the __autoload function for your own logic you can use it.

    <?php
      function __autoload($class) {
        Doctrine::autoload($class);
      }
    ?>

If your project uses autoload and/or you have other libraries that use it you could use spl_autoload_register to register more then one autoloading function.

    <?php
      spl_autoload_register(array('Doctrine', 'autoload'));
    ?>

### Compiling

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.

    <?php
      Doctrine::compile();

      // on some other script:
      require_once('path_to_doctrine/Doctrine.compiled.php');
    ?>

### Starting a new project

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 Active Record pattern

## Connection Management

## Object Relational Mapping

## Working With Objects

## Configuration

## Advanced Components

## DQL (Doctrine Query Lanaguage)

### Introduction

Doctrine Query Language(DQL) is an Object Query Language created for helping users in complex object retrieval.

You should always consider using DQL(or raw SQL) when retrieving relational data efficiently (eg. when fetching users and their phonenumbers).

When compared to using raw SQL, DQL has several benefits:

- From the start it has been designed to retrieve records(objects) not result set rows.

- DQL understands relations so you don't have to type manually sql joins and join conditions.

- DQL is portable on different databases

- DQL has some very complex built-in algorithms like (the record limit algorithm) which can help developer to efficiently retrieve objects.

- It supports some functions that can save time when dealing with one-to-many, many-to-many relational data with conditional fetching.

If the power of DQL isn't enough, you should consider using the rawSql API for object population.

    <?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";
        }
      }
    ?>

## Native SQL

## Transactions

## Caching

## Database Abstraction

## Technology

## Real World Examples

## Coding Standards