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

What I had, was a form, where user enters username using auto-completion. Problem was, setting user_id hidden field after user selection (from search results) was sometimes faulty. If users enters “Joh”, selects “John”, user_id is set to 2. But if user changes value to “John J”, selection even is not executed and user_id remains 2. This is a problem, because this is not the users meant and on submit I need to check if given username is correct, and in this case set user_id to null.

It’s quite easy to forget what A in AJAX stands for. A means asynchronous, which means that when HTTP calls are made JavaScript doesn’t wait for it to return response. This property made AJAX so useful, but in some cases it’s not what developers want. For example in jQuery, all AJAX functions has possibility to supply it with anonymous function – callback.

$("#Form").submit(function () {
 
	$.get(
		url,
		{},
		function (data)
		{
			// callback with data
		}
	);
 
	return true;
});

Again, this is what most of the times developers need, but I was working on different problem. Problem is, callback function here will never be executed. JavaScript will make a call, go to “return true;” statement, and browser is sent to other page. In my case, I needed form to be submitted only when response data has arrived and some manipulations have been done.

It may seem quite an easy problem, but it turned not to be. The problem is, you need to modify this even function, such that it can be called again when callback function have done it’s work (or modify it, to unbind submit event function and when submit again). First time, function creates HTTP request and returns false (to stop browser from actually submitting it).

After data has completed loading, callback function calls submit event again. However, now function knows that it’s second call (hence, callback has been called) and returns true – browser submits the form. What I came up with, is this code:

$("#Form").submit(function () {
 
	if ($.formLoading != false)
	{
		$.get(
			url,
			{},
			function (data)
			{
				// callback with data
				$.formLoading = false;
				$("#Form").submit();
			}
		);
 
		return false;
	}
	else
	{
		return true;
	}
});

It works perfectly. You can test it here: first form works correctly, second one never finishes loading (have a look at code).

I believe, that AJAX on submit is not the best way to do such things, but required functionality was for administration panel, so there was no risk of users cheating. It was possible to do the same work in server-side when handling submitted data, but for better user experience, I wanted to make data check without refreshes.