“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

What’s Wrong With The Existing MSSQL Extension For PHP?

… or, why do we need an improved SQL Server extension for PHP? :)

The existing MSSQL extension works well, but has a few practical limitations that have to be worked around.

• Limited to varchar(255) support
• No support for unicode columns like nvarchar
• No PDO drivers
• Poor error reporting

Now some of these issues are fixed, however Microsoft native Sql driver is still not used. As I’ve mentioned before, there are to ways to use native driver in PHP now:

1. As PHP extension
2. Through ODBC

However, none of these is available in Zend Framwork. So my task now (because of Winphp competition) is to come up with something what can be used to connect to Microsft Sql database with the new driver. To start with, lets look how standard DB config looks like:

;application/config/application.ini, ZF 1.8
resources.db.adapter = PDO_MYSQL
resources.db.params.host = localhost
resources.db.params.username = usr
resources.db.params.password = psw
resources.db.params.dbname = zf-tutorial

My goal is to change it as minimal as possible to allow easy db’s migration. To test ODBC connector I downloaded this class and renamed it to Add_Db_Adapter_Pdo_Odbc (because it’s not a good idea to change something in actual Zend Framework library). To use it in your code you need to change config file to something like this:

resources.db.adapter = PDO_ODBC
resources.db.params.adapterNamespace = App_Db_Adapter
resources.db.params.username = usr
resources.db.params.password = psw
resources.db.params.dbname = "Driver={SQL Native Client};
Server=localhost\SQLEXPRESS;Database=zf-tutorial;"

Note dbname string – now it has not only database name, but also driver information and host. I guess such format is chosen because dns’ for ODBC are very different for different providers, so to make things easier you just supply whole string, not it’s parts (driver, server/file, etc.). Don’t forget to use correct server host – for some strange reasons 127.0.0.1 refused to work for me.

Problem with ODBC is that it’s too general: ODBC supports a lot databases, hence they each can have something different (correct me if I’m wrong). That’s why I’m thinking about refactoring this class to App_Db_Adapter_Pdo_Odbc_Abstract abstract class and separate classes for different drivers. Although this class works fine for MSSQL, so can be used as is.

To test PHP extension there are no classes at all (at least I haven’t found, only in Adodb). So I decided to implement one myself – with a help of SqlSrv API Reference and Zend_Db_Adapter_Abstract abstract class I quite quickly came up with a working solution App_Db_Adapter_Mssql. Connection configuration looks the same:

resources.db.adapter = MSSQL
resources.db.params.adapterNamespace = App_Db_Adapter
resources.db.params.host = localhost\SQLEXPRESS
resources.db.params.username = usr
resources.db.params.password = psw
resources.db.params.dbname = zf-tutorial

I’ve tested both classes with the same application from previous post and benchmark results surprised me. They were equal! With a small variations page generation times were about 140 ms (all default settings, IIS7, MSSQL Express). Why? SQL server driver for PHP is open source, so if you look at it’s source you would find (C++):

SQLRETURN build_connection_string_and_set_conn_attr(
       sqlsrv_conn const* conn, const char* server, zval const* options,
       __inout std::string& connection_string TSRMLS_DC )
{
   ...
 
   connection_string = "Driver={SQL Native Client};Server=";
   connection_string += server;
   connection_string += ";";
 
   ...
 
   for( zend_hash_internal_pointer_reset( oht );
         zend_hash_has_more_elements( oht ) == SUCCESS;
         zend_hash_move_forward( oht )) {
 
      ...
 
       if( NO_ATTRIBUTE == ret.attr ) {
           if( ret.add ) {
               connection_string += key;
               connection_string += "={";
               connection_string += ret.str_value;
               connection_string += "};";
           }
       }
       ...
   }
 
   ...
 
   return SQL_SUCCESS;
}

If you are familiar with C++ you can look at full source at codeplex.com. What this function does is it creates ODBC connection string, so basically it’s the same thing as using PDO_ODBC (no?). Both are implemented as extensions (not as PHP code) so there are no performance differences, test proves that.

After today’s analysis I can’t say which driver is better to use: ODBC or native driver. However, since Pdo driver is already being used in Zend Framework it’s easier and faster to use ODBC. Also, ODBC doesn’t require Sql PHP extension to be installed, so as long as you have Sql server and native client it will work without php.ini modifications.

In conclusion, if you want to use SQL Native driver with Zend Framework solutions are almost here. I can promise, that something stable and proven to be working by actual application will be released before middle of June. I would love to hear comments from Microsoft people or ODBC users – I’m confused a little bit, because I didn’t have a lot of experience with Microsoft’s Sql and ODBC (you can share find me in twitter also @juokaz).