Doctrine is a very powerful framework, however you should study its behavior a little bit to get it working properly. As it turns out – it’s not that hard.

Speed

One of the first things I recommend looking at is query cache. Because there is quite a lot happening in turning DQL statement into the SQL query, caching that process can increase performance by a big margin. Best choice – APC, although robo47.net has an example code for use of Zend_Cache adapters, just don’t forget that file back-end is probably not the best pick.

Hydrators are probably the easiest thing to misuse. Hydration in Doctrine language is turning SQL query results into data graph. It can be an array, object or single value. It’s very nice to get results as PHP objects (in this case – models), however it’s slow. Slower than hydrating like array, and much slower than getting raw result from PDO. That’s why I always recommend answering one simple question: “will you be updating/deleting records?”. If the answer is no – hydrate as array, because you are not going to need an actual model (usually).

For this reason I always try to use array notation to access properties rather than like-object-vars one. Basically instead of $product->name I tend to write $product['name'], which returns the same result, but makes switching to array hydration very easy. You can find more tips and tricks at Doctrine manual here, but the key moment is to remember that the faster data structure in PHP is array (I believe so), so if application is not performing well – start playing with hydrations first.

Doctrine has a very nice support for relations, where they work like proxies and data can be retrieved when it’s needed (lazy-loading). However, this is wrong:

$user = Doctrine_Core::getTable('User')->find(1);
 
foreach ($user->Comments as $comment)
{
   print $comment->NewsItem->title . '<br />';
}

This code is bad, because for each comment you will load news item using a separate query, hence you are wasting db server resources and making code slower. Optimization is pretty straightforward:

$query = Doctrine_Query::create();
 
$query->from('Comments C')
        ->innerJoin('C.NewsItem N')
        ->where('C.user_id = ?');
 
foreach ($query->execute(array(1)) as $comment)
{
   print $comment->NewsItem->title . '<br />';
}

Here all the data is loaded in one query and everything happens much faster (and in this case making it to hydrate as array would also improve the performance).

However, make sure you know what you are joining. For example imagine that in previous example news item is also one-to-many (comment has many news items) relation and user 1 has written 1000 comments where each comment is attached to average news items. Query above will return 50′000 records (50 * 1000) which Doctrine will need to hydrate then. This will be very slow and probably going to kill your web server after some time. One day I had a query which was returning 2GB of data, server admins where probably not very happy about it…

Memory

One of my favorite parts of software development is playing with memory usage and making it efficient. Even though it sounds really simple, debugging it and finding it where the memory is leaking is not an easy task. Recently I was using Doctrine to work with quite big datasets (on average 50′000 of records) and probably have tried all the possible tricks to make Doctrine memory efficient. My code looked really simple:

$data = Doctrine_Query::create()->execute();
 
foreach ($data as $item)
{
    // do some work here
}

You might expect that memory usage would be steady, however it is not. Doctrine uses identity map and objects also have a lot of references which makes freeing up memory a tricky job. As my experience showed, even though records have a method free() which is supposed to de-reference it, sometimes it doesn’t help.

So to make memory management work, make sure to try these:

• $record->free(true) – deep free-up, calls free() on all relations too
• $collection->free() – free all collection references
• Doctrine_Manager::connection()->clean() – cleanup connection (and remove identity map entries)

With some debugging and profiling (and these methods) you hopefully can make memory usage to be low. I’m also using some custom iterators (available here) to divide query into chunks, because loading 50′000 of objects in one go is not going to work, so you might want to look at it too.

Another recommended tip: make sure to free queries too. As collections hold references to all records, query object also has some references to parsed sub-parts of query. For this I use auto-free setting enabled by (available in my first part post also here):

// enable automatic queries resource freeing
$manager->setAttribute(
	Doctrine_Core::ATTR_AUTO_FREE_QUERY_OBJECTS,
	true
);

It’s very easy to forget to free a query and it’s again creating these references which makes garbage collector’s work hard. Nevertheless, after enabling this one I don’t know any other place where the memory can start to leak.

Last step – PHP 5.3. I’ve been working with this version for a few months and it works great, so if it’s possible – I recommend using it (you will also help with testing frameworks, but both Zend Framework and Doctrine already should work fine). One important function here is improved garbage collector, so the actual script takes less memory to execute. I haven’t recorded benchmarks on this one, but what I’ve noticed during development is that 5.3 does in fact has a lower peak memory usage.

Conclusion

I think I haven’t missed anything here, or at least these are the tips which made applications work fast (if I have – let me know). To finish with – good optimizations are done by comprehensive benchmarking and profiling, so the fact that Doctrine is a big framework doesn’t necessary mean it’s slow too. At the end of the day, it’s usually only a matter of reading a manual.

All parts:

1. Zend Framework and Doctrine. Part 1
2. Zend Framework and Doctrine. Part 2
3. Zend Framework and Doctrine. Part 3

These are the steps required to setup Doctrine:

1. Create MySQL (or any other adapter supported by Doctrine) database
2. Download Doctrine 1.2 (as of today – 1.2.0beta3). Believe, it’s stable enough (no problems at all for me) and supports functions all functions we are going to use later
3. Setup application.ini and application resource
4. Generate models from database
5. Profit!

To start with, download this archive (or get updated version from my public repository). It has everything you will need. Some of the files are quite long so I’m not going to post them here, it’s better that you download them and have them ready to be used as the article progresses.

Create MySQL database

For MySQL databases I use a product called “MySQL Workbench“. If you haven’t tried it I definitely recommend to give it a go – it basically allows you create a database as a diagram and then export it to sql file or update actual database (can be risky). Since I expect you to have enough knowledge how to create a database I won’t write anything more – you can find tutorials all over the web.

Download Doctrine

After downloading Doctrine extract it to library folder. You should have ./library/Doctrine.php in your library folder. Although, you can use svn:externals (if you are using SVN at all) to remove Doctrine code from repository, but in this case you probably need to setup paths in application resource file explain below to use Doctrine_Core if you just get Doctrine folder contents (from here).

Most important point here – don’t forget to download 1.2, not version 1.1. Even though it doesn’t have a stable release, 1.1 doesn’t support models generation as we want them to be (auto-loadable). Also this week all bugs have been fixed which I reported and now models generation works perfectly. From my personal experience, I haven’t even used 1.1 at all (started with 1.2 when it was in alpha) and didn’t had any problems, so my recommendation – use 1.2.

Setup application.ini and application resource

From the file listed above open a file called application.ini. Append you current configuration (more on getting Zend Framework project running can be found here) with settings in that file (leave compiled and cache options to false for now). Doctrine uses DNS strings to connect to a database, there are quite a few examples in the documentation. If you have used PDO before you be very familiar.

In archive there is a file called library/resource.php. Depending on what namespace you use for outside-Zend code, paste it to chosen folder. If you choose to have “App” as a namespace, just copy that file to library/App/Application/Resource/Doctrine.php. And don’t forget to have:

autoloaderNamespaces[] = "App_"
pluginpaths.App_Application_Resource = "App/Application/Resource"

in application.ini also, otherwise library code won’t be auto-loaded. I don’t recommend putting any code in Zend folder, because it will create tons of problems in the future. Having App or ProjectName library folders allows to have your own code in separate packages which you can use in later projects (I usually have App, ProjectName, CompanyName).

Provided application.ini file isn’t that much configurable, mainly because it wasn’t supposed to be released at all. If you are looking for something more dynamic, look no further than this proposal in Zend incubator. Nevertheless, my code should work fine – it has all options required to get you started and have been tweaked with settings which I found to be really useful.

Generate models from database

This part is the most awesome. To start, just copy and paste everything from scripts folder in the zip archive to your scripts folder in application (I have scripts folder in the same level as application and library, in the root of project). There actually only two files – doctrine-cli.php and custom task in Doctrine/Task/GenerateModels.php. You can run doctrine-cli.php like this:

php doctrine-cli.php

and you should get a list of all the possible tasks (if you setup everything properly). To run my custom task, append “generate-models” to the end of previous command to get:

php doctrine-cli.php generate-models

This task will load your database schema and create all classes (table, base model, model) required for models. Doctrine also supports generating models from yaml configuration files, though I’ve never used it before, but configuration should be almost the same.

It works

To test the models you can look at the generate code or start coding you application (or even run dql task from doctrine-cli.php). For example you can test simply like this (adjust by models you have):

$product = new Model_Product();
$product->title = 'Product name';
$product->save();
 
print_r(Doctrine_Core::getTable('Model_Product')->findAll()->toArray());

If everything has been configured properly you shouldn’t get any errors and this code (put it in controller) should output array of your saved data. Because of the settings in application resource, save() method also runs validation so if you missed a field and it breaks a not null constrain, this code will throw a validator exception.

What’s next?

This article has enough information to get you started and almost all the code provided it left as simple as possible and open for further modifications. I hope that in coming months code for Doctrine and Zend Framework integration will be completed and you can use Doctrine without any outside code.

Since we have application running now we can dive into actual usage, testing and more advanced stuff. I have code for these also and will be posting more articles very soon, even though the best resource for Doctrine is documentation. If you have any problems with this code just leave a comment here or find my on twitter (here) and I will try to explain more.

All parts:

1. Zend Framework and Doctrine. Part 1
2. Zend Framework and Doctrine. Part 2
3. Zend Framework and Doctrine. Part 3

History

To start with, in my opinion, Zend Framework never had a proper M from MVC. It was quite common to use Zend_Db_Table as base models class, but it was simply not practical. When you start dealing with relations and hierarchical data types it starts to get really tricky, because simply Zend_Db_Table doesn’t provide an extensive enough functionality.

So half a year ago Zend Framework developers started to look for better solutions. Quite obvious one was to start implementing their own Domain layer. You can find quite a few different implementations of that in blogosphere, and I chose this path also. However, after quite some time of developing my own code I realized that it’s simply not a right thing to do – I’m expected to deliver a product and I was “wasting” way too much time tweaking, testing, extending etc. my domain model code.

So about 3-4 months ago I completely switched to Doctrine. After evaluating possible solutions I decided to stay with Doctrine for a long time. I don’t know any other solution coming, I definitely don’t want (mainly because I don’t have time) to invest on creating my own library and Doctrine is simply awesome when you get used to it. After all this time I can say that it was a right call – Doctrine is on a way to being officially supported in Zend Framework (Symfony has it right now) and with Doctrine 2.0 (you can see a short presentation of its new features right here) it will be just a perfect tools combination. I would very much agree with Giorgio that:

Thus, Doctrine 2 is going to become the first production-ready Orm for php and to be favored with seamless integration in both Zend Framework and Symfony.

Benefits

Some time ago I was actually involved in making a decision of choosing Doctrine over other libraries (main Zend Framework components) as part of my work, so here I’m going to outline some points which made that decision easier.

Relations. I keep repeating this term every time I speak about Doctrine (or ORM’s in general), but for me it’s a key factor in writing code fast. Quick example: let’s image that our application consists of Order which has a list of Items where Item is Product and price, quantity information. Code for this situation:

$order = new Order();
 
$item = new OrderItem();
$item->Product = $product; // product object from somewhere
$item->quantity = 10;
$item->price = 9.99;
 
$order->Items->add($item);
 
$order->save();

This is how much code I need to write myself. I’m going to show more examples in the future posts, but because Doctrine is ORM (object relation mapper) all the hierarchical structure of your application data becomes very easy to work with.

What is more, Doctrine can generate all the model classes by itself. Now that’s a treasure! Just specify database connection in the config file, open up a terminal and run:

php doctrine-cli.php generate-models-db

In a few seconds all schema information is retrieved from the actual database and all the classes are created. My biggest project so far with Doctrine was worth more than 10′000 lines of models code. I don’t know how to count the time it saved and despite a few minor bugs in Doctrine library it worked exactly as we wanted.

I can list things I like about it for hours probably, so I’m going to finish this list with the future I consider to be a very big time saver. This feature is dynamics of models: inheritance and behaviors. Inheritance makes your objects have different classes even though they could be a same table (with for example type_id). All the work needed to handle the actual schema is done in background.

Behaviors work in the same way – one line of code and a model becomes physically undeletable (called soft-delete) or has a separate table to save revisions. Behaviors are very similar to decorators in Zend_Form for example – they are small classes which can be added to the main class to extend its functionality. So in the end your mode could have all sorts of different functionality depending on how you “decorate” it.

What’s next?

I only wrote a few examples how great Doctrine actually is today, but you can expect a lot more. Especially in Zend Framework code side: application.ini settings, application resource to setup auto-loading, script to generate Zend Framework compatible models, testing Doctrine models and much more. I’m also involved in a work group making Doctrine and Zend Framework integration possible so you can expect great things to come (first proposal here).

If you have been following me on twitter you might have noticed that I tweet a lot of interesting material on both Zend Framework, Doctrine and general PHP so I would recommend following me there or subscribing to the RSS feed. I haven’t been writing for a while now, but I will try as hard as I can to change it and write much more frequently – during past months I tried a lot of cool stuff which I would love to talk about.

All parts:

1. Zend Framework and Doctrine. Part 1
2. Zend Framework and Doctrine. Part 2
3. Zend Framework and Doctrine. Part 3