Most of the outlined problems and solutions are focused on testability, maintainability and other good code practices. If you are not familiar with them, I recommend read about them ASAP as there is big chance that you are doing those things described in this post and don’t even realize how wrong they are. Believe me, you will soon find yourself a way better developer.

Separate logic

This one is the most obvious one, but trust me, I have found cases of it in every single project I have worked before (more than 10 with Zend Framework in a past half year and counting). If it’s controller, don’t do business logic, if it’s model don’t base behavior on POST parameters etc. Same applies to forms, bootstrap, views, various helpers and many more other components – logic should be separate and have its place.

Move all logic from controller to a model or service. Use forms only to handle validation and filtering, not to actually process data and persist it in any fashion. Hide session and authentication handling in one place and provide API for other algorithms. I can go on, but I hope it’s starting to get pretty clear, or at least it will eventually when you start testing your code: when you need to setup frontController, request, cookie and mail server just to test a form you realize that something is really wrong.

Globals

If you haven’t seen this video, please do it immediately – you won’t regret it. Global state makes testing problematic and is completely opposite to what OOP proposes. This applies for use of $_SERVER, $_SESSION etc. values and all of them are accessible via request object (look at Zend_Controller_Request_Http) methods or separate classes, like Zend_Session.

Yet again I’m going to mention testability, because that’s something you always need to keep in mind. Test should not modify global variables, but rather inject mocked request/other objects which just return expected values (like client IP), because Zend Framework does pretty good job abstracting access to all global variables.

Use form values, not request

This one is both security and ease of coding issue, let’s look at this code sample:

$form = new Form();
 
if ($this->_request->isPost()) {
 
    if ($form->isValid($this->_request->getPost())
    {
        $model = new Model($this->_request->getPost());
        $model->save();
    }
    else
    {
        $form->populate($this->_request->getPost());
    }
}

After form is validated (and hence values are filtered), raw values from request are still used from $this->_request->getPost(). Not only do you lose Zend_Form functions like ignored elements (for submit buttons for example) but also none of the filters are applied (which you use, yes?). Also I can pass pretty much anything I want and model needs to do way more validation. Hence $form->getValues() should always be used as it returns form data with respect to all defined rules and filters.

Form populate() method is also very overused. This method is designed to set default values for a form, from for example GB entry (when editing something) apart from that, you simply don’t need to use it as method isValid() sets values for all elements, so there is no need to apply default values too.

Do not rely or use exit()/die()

One of the first things I do is remove all these exit() calls and handle such cases with exceptions or return statements. There is only very very limited amount of situations where you actually need to use one of those functions. Just for example, imagine this controller action code:

if (!$this->userHasPermissions())
{
    $this->_redirect('/');
}
 
$form = new Form_Add();
 
if (//submit form)
{
    // save with $form->getValues();
    $this->_redirect('/index');
    exit();
}
 
// do something else

First problem – thinking that $this->_redirect() will call exit() and hence nothing else will be executed. Even though this is true by default, this should be avoided in all cases. Not only it makes all post* events to not be fired, but also it makes testing impossible or incorrect. Zend_Test disables use of exit() in controller helpers, so in this case while testing you cannot test permissions checking as in all cases it will still execute later code. To fix this just add return in front of redirect (return $this->_redirect(‘/’)) and you are safe.

Furthermore, second exit() is completely useless and makes code even more untestable. Again you can just use return to cancel later code (view will not be rendered as viewRenderer helper checks for redirection header and does nothing if detects such). From my experience, after saving entry, there is only some assignments to view in left code so you won’t suffer a lot if you just leave redirect, of course without exit().

Use a framework, not PHP

This can sound wrong at first, but if you use a framework (Zend Framework in this case) don’t start throwing in hacks from 5 year old PHP apps. Like this (controller action):

$object = new Some_Object();
 
$image = $object->generateImage();
 
header ('Content-type: image/jpeg');
echo $image;

I don’t even know where to start… All this logic is incorporated in response object, so you can do things like:

$this->getResponse()->setHeader("Content-type", 'image/jpeg');
$this->getResponse()->setBody($image);

It might seem as same thing, but it’s not. Yet again you can actually test it, you are not working with global state (header() is global state function) and request dispatch process is left working as it should. Controllers do not output any data (hence no echo should be used) they just get request object and return response object, that’s it. In a similar fashion as exit() breaks dispatch process, outputting from controller does that too, so don’t forget to make sure that you preserve this flow.

Some small ones

Application.ini has a property includePaths, which is used to add additional paths to include path. Even though it works great, I still recommend not to use it because it will add those paths every time you create new application instance (true for 1.9, can change in future). If you try to do some controllers testing, you are probably going to instantiate it before every single test and after some hundreds of tests you will notice that somehow it’s getting slower and slower. That took me a few hours to find, though fix was easy, but still keep that in mind.

If you are using jQuery or any other javascript view helpers, take full power of them. By that I mean use functions like addJavascriptFile(), addJavascript(), addStylesheet(), addOnload() etc. to add some additional resources and code from views. If you add javascript straight to view everything will still work, but by using view helper container you will have all your code nicely placed in one place and not scattered all other the place.

Conclusion

This is just a small list of problems and issue I have seen in my work – there are way more to look at (you can share some tips too). I hope those will give you some idea how to work with Zend Framework in a clean fashion and you will soon find that your code is starting to look nicer and coding time is decreasing as everything is nicely separated and transparent to other code.

“Old-style” interaction with data

I’ve used it for different projects, but one of the best examples of how great this concept is SaaS or any other users-based application. Some years ago I used to have code which worked like this (let’s say this is controller action):

public function userInfo()
{
     $userDao = new Users();
     $user = $userDao->getUser($_SESSION['id']);
}

And then in my database access class Users I just execute sql query with a given user id. However, after some thinking I looked at it again and though – why does controller need to know the userId? I mean, of course it’s a job of controller to process requests and control application flow, but logically – if an action is named userInfo and we got to the point where we need the user info (hence the user is authenticated and validated) why do we need to pass user id? It’s clear that some part of code already knows it.

One more case: if a site is a e-commerce it’s clear that user has only access to his orders, addresses information etc. but in a basic MVC you either fetch by Id and then check if it’s in fact user’s order or create a method like in a first example. Again, not very clear and not easy to maintain. There are more problems too: by passing user id and id of a record you assume that controller knows that this is a key to get the information. But it’s wrong – business layer knows that user has orders; controller only knows that there is such a thing like orders and it can be retrieved by id. That’s it.

Service layer

For such things I use service layer: it has user info injected from bootstrap (or directly to a constructor) and operates with data only accessible to the user. So previous method becomes to:

public function userInfo()
{
     $service = new UsersService();
     $user = $service->getUser();
}

of course you would have a separate method to fetch other users data, but for sake of simplicity let’s just say that this method returns some private info (like address for example). Here my action is completely unaware of what user id actually is – it expects a user object, it gets it. Very simple, very clean and very easy to maintain.

Getting back to the e-commerce example, action for a view order would look like this:

public function viewOrder()
{
     $service = new OrdersService();
     $order = $service->getOrder($_GET['id']);
}

Again – this controller action doesn’t care what user id is in current session, it just gets an order by its id. If this action returns false (or throws exception with error type) then it means order cannot be retrieved, or in other words – service cannot return id by given id. It can be permissions problem, it can be something else – but controller is completely freed from checking all this unnecessary things.

Practical usage

As you might have noticed, service layer is intermediate layer between models and controllers – in the same way as you would use Flickr or Youtube API to work with remote data, you use service layer API to work with application resources. All the business logic resides in service layer, where also using other service layer, models are retrieved, changed, saved, returned etc. Controller has zero lines which contain a word Doctrine (or any other database layer class). None.

Another advantage of using a service layer – it’s a good place to merge information sources. I think it’s more like a style of mine, but I tend to have models very clean – only with logic on that model. This is mainly because I usually use Doctrine models and I don’t want to put anything in them. For example just yesterday Adam from jazzslider.org posted a very good article about using Acl with models by creating custom listeners. With all respect, even though it works really great, I don’t think it’s a clean approach – I see models and permissions control as separate layers.

Furthermore, having this layer makes replacing database layer (or even models layer) a little bit easier – because all the other code communicates with data using given API (from service layer) so as long as results returned are the same, they don’t care how they are actually retrieved (for example they can come from cache, text file or created on-the-fly). But if you would have Zend_Db_Select calls all other the place, migrating to Doctrine’s DQL can be a pain. From my personal experience, I successfully migrated my own ORM code with about 50 models to Doctrine in about 4 days without changing a line in controllers (also because of tests I had).

To be honest, I’ve only tried various service layer implementations with Zend Framework. Even a default autoloader has a resource namespace Service_ with services folder inside application, so I didn’t need to do any hacking to get it working. Nevertheless, this pattern doesn’t require any specific framework futures, but if a framework has good dependency injector (like this one from Symfony) it can make things even cleaner.

Conclusion

I don’t know if I have convinced you to look at this pattern, but I definitely recommend looking at it. Especially when your application gets quite big and you need some sort of functionality to work with all these models (on average, I used service layer with applications having roughly 80 models). Nevertheless, there are tons of different ways to do this, so I definitely recommend reading a book by M. Fowler called “Patterns of Enterprise Application Architecture (P of EAA)”. One of the best sources for enterprise applications I’ve read so far.

^* Image copyright: http://martinfowler.com/eaaCatalog/serviceLayer.html and http://www.tutorialspoint.com/images/soa-additional-service-layer.jpg

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

I need to have modular systems, which would allow downloading module as an archive and installing it would be as hard as unpacking it. Modules should work in their own folders and don’t require any system modifications. Also, modules needs to have different controllers and views for different website parts: backend and frontend.

Zend Framework manual has examples for directory structures and suggests this modular structure:

application/
    *module_name*/
        controllers/
            IndexController.php
            FooController.php
        models/
        views/
            scripts/
                index/
                foo/
            helpers/
            filters/

But how to distinguish between frontend and backend parts? Some solutions suggests having backend as admin module, but modular structure would be lost – adding new modules would require modifying admin module. So I decided to invent my own directories tree and came up with:

application/
    *module_name*/
        controllers/
	    admin/
                 IndexController.php
                 FooController.php
	    public/
                 IndexController.php
                 FooController.php
        models/
        views/
            scripts/
                admin/
		     index/
		     foo/
                public/
		     index/
		     foo/
            helpers/
            filters/

It works perfectly (requires small bootstrap modifications), but I do not like it. What I don’t like is high depth of folders – working with files browser is really painful. Also, multiple folders share same admin and public folders, but it’s not really right – admin and public are parts of website and they should have different controllers, not controllers have different parts. So I reversed whole tree:

application/
    *module_name*/
        admin/
            controllers/
                 IndexController.php
                 FooController.php
            scripts/
                 index/
		 foo/
        public/
            controllers/
                 IndexController.php
                 FooController.php
            scripts/
                 index/
		 foo/
        models/
        views/
            helpers/
            filters/

I haven’t tried implementing it, but it works in theory. Having admin and public as root folders also creates possibility to add, for example, part dependant forms more easily.  However, I still don’t know which structure to choose – they all have different pros and cons, though last one seems to be most “natural”.

Which structure you use?