Posts tagged qgl

Back in 2005, the Quantum Star SE project caught the Object Relational Mapping (ORM) bug and I took a first stab at implementing something that was simple, fast and easy to use. Until this stage I was a regular user of the Data Mapper pattern (among others) but since switching to PHP and developing open source projects found it to be largely unnecessary. The root problem is akin to hammering nails with a sledgehammer - too much complexity being implemented for a simple underwhelming task.

Here in 2007, with the QGL in development I found myself re-assessing my previous experiences and finding it attractive to develop something less complex and hopefully faster than a full scale ORM solution. Taking some previous work I did, I opened a branch in the QGL subversion repository and set to work. The results are slowly coming to fruition - the DAO, Row and part of the Driver families are shaping up going by the unit tests.

So what is Quantum_Db (in practice)? It will be a family of classes which form a Data Access Object (DAO) Framework when complete. This post is largely a ramble about current progress and intentions - so if looking for a complete solution you’re in the wrong place as the current code is strictly in-progress. For reference though, the source code is under the New BSD License. It’s incomplete, but available from its subversion branch at: http://quantumstar.svn.sourceforge.net/viewvc/quantumstar/branches/Quantum_Db/ and the forums can be found for the QGL in general at http://forums.astrumfutura.com/viewforum.php?f=25.

In this specific implementation of Quantum_Db, the DAO class (Quantum_Db_Access) is a Singleton which attempts to offer relatively basic CRUD methods capable of use on any valid database table record. A large part of its responsibility is generating CRUD type SQL. So you could have a User record, which could be saved by passing it to a DAO save() method. It’s not quite as clear cut, since to reduce the mass of code a DAO implementation often needs the “record” is encapsulated in a container called Quantum_Db_Row. This Row class can represent a single table record, but also doubles as a data container for setting up SQL conditions (think of WHERE, IN and INSERT clauses).

One of the goals intentionally targets simplicity, so there is no Propel-style Criteria object to mess about with. There will be in the future, but for simple needs, a simple DAO framework is sufficient as an initial start. A simplistic use case is adding a new User record. Some code showing this task:

[geshi lang=php]require_once ‘Models/User.php’;

// Fields are public properties handled by __get/__set in the
// Quantum_Db_Row class. The User class is actually a simple
// subclass defining valid fields and primary key(s).
//
// We do not specify an Id value for new Users. The DAO class will
// assign this assuming Id is an auto-incrementing value for MySQL
// or a Sequence for PostgreSQL.

$user = new User;
$user->name = ‘Pádraic’;
$user->email = ‘[email protected]’;
$user->password = sha1(‘password’);
$user->country = ‘ie’;

// Call on DAO to save this record to the database. Obviously any
// database errors will result in Exceptions thrown by the DAO so
// the database table rules (primary key, unique key, etc.) all apply.

$user->save();[/geshi]

The first thing you can note is that the DAO class (called Quantum_Db_Access is not directly called. Instead all Row objects carry a reference to the Quantum_Db_Access singleton so Quantum_Db_Row::save() proxies to Quantum_Db_Access::save() - we only need one generic DAO object. If one desperately needed the DAO they could just place a call to Quantum_Db_Access::getInstance().

[geshi lang=php]$dao = Quantum_Db_Access::getInstance();
$dao->save($user);[/geshi]

In fact, you can equally access the underlying database extension driver to run queries directly using the following. Of course Singletons have their own evil uses, so ideally you’d pass around the object reference instead of litering source code with static getInstance() calls which explicitly refer to the class name.

[geshi lang=php]// Example of accessing the driver to drop the User table

$driver = Quantum_Db_Access::getInstance->getDriver()->exec(“DROP TABLE user”);[/geshi]

Retrieving records is more interesting. It’s relatively simple to extract a record based on a primary key:

[geshi lang=php]$user = new User;
$user->getByPk(1);

var_dump($user->asArray()); // echo array of User (Id=1) data[/geshi]

It’s much more complex to fetch rows of a very specific nature. Even worse, without a Criteria object using the MySQL IN clause is a challenge. However for those where the SQL values depend solely on simple field values a neat solution is “named queries”. A Named Query (check the excellent introduction at: http://www.tonybibbs.com/article.php/PropelDAO regarding something similar for Propel) is an SQL string containing value placeholders (e.g. for use in a PDO::prepare()) stored in some central file. This has a few benefits and disadvantages.

The main benefit is the centralisaton - like OOP, centralising logic (in this case non-generated SQL strings) reduces duplication and encourages reuse. Allowing the named queries to be indexed (for example, within an XML hierarchy) by a name and model allows them to be easily located and prepared by the Data Access Object. The disadvantages are of course that it’s still limited. For example, use of a MySQL “SELECT id, name, email FROM user_table WHERE id IN(1,2,3,4)” isn’t likely a storeable named query since the IN() range of id values is too variable. But for many queries it’s a good fit in the absence of some form of Criteria class.

Enough of the DAO class however. After beating it to death, there are still pieces to be completed when it comes to allowing complex SQL clauses. The main point is that for simple use cases it is a good match - and simple use cases are extremely common in many of my open source endeavors.

To backup the Data Access Class Quantum_Db also implements a Driver and Results class family. Again simplicity is key, so it’s being written under the presumption that PHP5′s PDO extension is available. The Quantum_Db_Driver_Interface file actually mirrors the PDO interface for this reason. Of course we can’t forget mysqli (the most popular PHP5 database extension) or pgsql and the rest. Quantum_Db_Driver defines an interface to enable additional extension type support. Personally I only intend adding a light abstraction over ADOdb-Lite - it’s not worth duplicating Mark’s already existing library.

The Results class, the one part no code exists for yet - don’t be worried I develop using TDD and unit testing so it’s perfectly normal . Quantum_Db_Results will aggregate the results of queries into a class implementing PHP5′s SPL Iterator. To be specific, the Iterator methods will be tied to each underlying Driver’s fetch* methods. This should allow continued use of Lazy Loading during iterations, and allow continued use of foreach() etc.

Here ends my ramble for now. For those working on the QGL or similar code maybe it will provide a few of my thoughts on the topic - assuming you can summarise the rambling of course .