Find the latest here.

PHP 5.3 gets ActiveRecord!

A quick search to find an implementation of active record for php on google is discouraging when one considers the state of ActiveRecord for Ruby on Rails. The reader will notice that the top results are from very old posts and the rest of the results preview minimial implementations. Of course, eventually, PHP will see a robust active record similar to RoR. Fortunately, that time is now, thanks to PHP 5.3 and the beneficial new features: closures, late static binding, and namespaces.

My friend Kien and I have improved upon an earlier version of an ORM that he had written prior to PHP 5.3. The ActiveRecord we have created is inspired by Ruby on Rails and we have tried to maintain their conventions while deviating mainly because of convenience or necessity. Our main goal for this project has been to allow PHP developers tackle larger projects with greater agility. However, we also hope that use of this resource will push the PHP community further by learning the wonderful benefits of the Ruby on Rails stack. Enough with the rambling, let's get to the interesting piece!

Overview

Allow me to reiterate the fact that we have tried to maintain similarity between our implementation and rails' ActiveRecord to avoid headaches and increase programmer bandwidth. Keeping this similarity in mind, we have tried to re-produce many of the features. Here is a list of those features:

• Finder methods
• Dynamic finder methods
• Writer methods
• Relationships
• Validations
• Callbacks
• Serializations
• Support for multiple adapters
• Miscellaneous options

There are other features such as named scopes, additional adapters, transactions (something we want sooner than later), and a few others we hope to add in the future, but we believe this is a great start. We are hoping to have the code hosted on launchpad or the like within a week or two and a website with documentation. Be sure to check back here shortly for updates!

Configuration

Setup is very easy and straight-forward. There are essentially only two configuration points you must concern yourself with:

• Setting the model auto_load directory.
• Configuring your database connections

Examples:

 
ActiveRecord\Config::initialize(function($cfg)
{
    $cfg->set_model_directory('/path/to/your/model_directory');
    $cfg->set_connections(array('development' =>
       'mysql://username:password@localhost/database_name'));
});
 
#Alternatively (w/o the 5.3 closure):
$cfg = ActiveRecord\Config::instance();
$cfg->set_model_directory('/path/to/your/model_directory');
$cfg->set_connections(array('development' =>
    'mysql://username:password@localhost/database_name'));
 

Once you have configured these two settings you are done. ActiveRecord takes care of the rest for you. It does not require that you map your table schema to yaml/xml files. It will query the database for this information and cache it so that it does not make multiple calls to the database for a single schema.

Finder methods

ActiveRecord supports a number of methods by which you can find records either by primary key or you can construct your own complex conditions array with other options such as: order, limit, select, group.

 
#find by primary key
Author::find(3);
 
#same as above but expecting multiple results
Author::find(1,2,3);
 
#find the first record with limit
Author::first(); 
 
#find last record by order and limit
Author::last(); 
 
Author::all(); 
 
#this may be evil - but you can pass your raw sql to this method
Author::find_by_sql();
 
## you can also pass many options to finder methods
 
#sql => ORDER BY name
Author::find(3,array('order' => 'name'));
 
#sql => WHERE author_id IN (1,2,3)
#find all with conditions as array
Author::find('all',
  array('conditions' => array('author_id IN(?)',array(1,2,3))));
 
#sql => WHERE author_id = 3
#find with conditions as string
Author::find('first',array('conditions' => 'author_id=3'));
 
#sql => GROUP BY name
Author::find(3, array('group' => 'name'));
 
#sql => LIMIT 0,3
Author::find('all', array('limit' => 3));
 
#sql => select * from `author` INNER JOIN etc...
Author::find('all', array('joins' =>
  'INNER JOIN book on (book.author_id = author.id)'));
 
#sql => SELECT name FROM table
Author::first(array('select' => 'name'));
 
#these methods do not return records
#return true/false
Author::exists(1);
 
#return integer
Author::count(array('conditions' => array('name = ?', 'John')));
 
# access is self-evident
$book = Book::first();
echo $book->title;
echo $book->author_id;
 
#returns an array
$books = Book::all();
echo $books[0]->title;
 

Dynamic finder methods

ActiveRecord within rails makes clever use of finders by allowing you to dynamically create methods based on the attribute names. This means you can easily make a "find_by_attribute_name" query without having to explicitly define it in the class. We also make use of this feature by using a new PHP 5.3 magic method: __callStatic().

 
Author::find_by_name('George Bush');
#you can make use of and/or
Author::find_by_name_or_author_id('George Bush', 2);
Person::find_by_first_name_and_last_name('Obama', 'Mama');
#also have find_all_by
Author::find_all_by_name('Tito');
Author::find_all_by_name(array('Tito','Bill Clinton'));
 

Writer methods

What good is it to have an object that encapsulates a record from the database if you can't do anything with it?

 
#call to SQL insert since it knows that it is a new record
$book = new Artist(array('name' => 'Tito'));
$book->save();
 
## updates
#only update 'dirty' attributes meaning the sql would only update
#fields that have been changed
$book = Book::find(1);
$book->title = 'new title!';
$book->save();
 
#this will automatically call save
$book = Book::find(1);
$book->update_attributes(array('title' => 'new title!',
  'price' => 5.00));
 
#will also make call to save
$book = Book::find(1);
$book->update_attribute('title', 'some new title');
 
$book = new Book;
$book->title = 'new title!';
$book->author_id = 5;
$book->save();
$book->created_at # we also support created_at/updated_at timestamps where applicable
echo $book->id; #id is also set to the auto increment value from the db
 
#delete
$author = Author::find(4);
$author->delete();
 
#you can pass readonly on the find so that you cannot save a model
$book = Book::first(array('readonly' => true));
$book->title = 'new'; # or you could set it here by doing $book->readonly(true);
#this will throw an ActiveRecord\ReadonlyException
$book->save();
 

Relationships

Associations are the complex piece of ActiveRecord. They accept many of the same options as with rails.

 
#relationships are declared with a static var
class Book extends ActiveRecord\Model {
  static $belongs_to = array(
    array('publisher'),
    array('author', 'readonly' => true, 'select' => 'name', 'conditions' => "name != 'jax'"),
    array('another', 'class_name' => 'SomeModel')
  );
  #has_many accepts select/conditions/limit/readonly/group/primary_key
  #has_many also takes a through option which you can use with source
  #to clarify the class
  static $has_many = array(
    array('revisions'),
    array('editors', 'through' => 'revisions')
  );
 
  static $has_one = array(
    array('something')
  );
}
 
#the 0 index declaration array of each association is the "attribute_name"
#which you use to access on the model like so:
$book = Book::first();
echo $book->publisher->name;
echo $book->author->name; # we only have name as an attribute b/c of the select opt
#below will throw a readonlyException due to the option -- see the writer
#methods section
$book->author->save();
 
#has_many
echo $book->revisions[0]->id;
#has_many through
echo $book->editors[0]->name;
 

Validations

This is rather self-explanatory. Before save/update/insert, your validations will be called for each declaration you have made and will save the model if all validations have passed. Otherwise, you will have access to an errors attribute which you can use to get back validation error messages.

 
class Book extends ActiveRecord\Model
{
  static $validates_format_of = array(
    array('title', 'with' => '/^[a-zW]*$/', 'allow_blank' => true)
  );
  static $validates_exclusion_of = array(
    array('title', 'in' => array('blah', 'alpha', 'bravo'))
  );
  static $validates_inclusion_of = array(
    array('title', 'within' => array('tragedy of dubya', 'sharks wit laserz'))
  );
  static $validates_length_of = array(
    array('title', 'within' => array(1, 5)),
    array('attribute2', 'in' => array(1,2)),
    array('attribute3', 'is' => 4, 'allow_null' => true)
  );
  # same as above since it is just an alias
  static $validates_size_of = array();
  static $validates_numericality_of = array(
    array('title')
  );
  static $validates_presence_of = array(
    array('title')
  );
};
 
$book = new Book;
$book->title = 'this is not part of the inclusion';
if (!$book->save())
  print_r($book->errors->on('title'));
 

Callbacks

Callbacks allow you to take command of your model before/after certain events during its lifecycle. You can define methods in your model that will occur as callbacks before or after other methods are invoked on the model. Unfortunately, even though PHP 5.3 has closures, you cannot use them in a static var declaration so you must define/use methods.

 
#below are the possible declarations that you can make
#if your callback returns false for a before_* then it will cancel the
#action and the rest of the callbacks
class Book extends ActiveRecordModel{
  static $after_construct;
  static $before_save = array('do_something_before_save');
  static $after_save;
  static $before_create;
  static $after_create;
  static $before_update;
  static $after_update;
  static $before_validation;
  static $after_validation;
  static $before_validation_on_create;
  static $after_validation_on_create;
  static $before_validation_on_update;
  static $after_validation_on_update;
  static $before_destroy;
  static $after_destroy;
 
  #this will be called directly before save()
  public function do_something_before_save() {}
}
 

Serializations

 
class Book extends ActiveRecord\Model{
  public function upper_title(){
    return strtoupper($this->title);
  }
}
 
#produces: {title: 'sharks wit lazers', author_id: 2}
$book = Book::find(1);
$book->to_json(); 
 
#produces: {title: 'sharks wit lazers'}
$book->to_json(array('except' => 'author_id'));
 
#produces:  {upper_title: 'SHARKS WIT LAZERS'}
#make methods an array of methods and it will call them all
$book->to_json(array('methods' => 'upper_title', 'only' => 'upper_title')); 
 
#produces {title: 'sharks wit lazers', author_id: 2}
$book->to_json(array('include' => array('author')));
 
#also support xml w/ the same options but need more tests =)
$book->to_xml();
 

Support for multiple adapters

Currently, there exists support only for MySQL (also through mysqli) and sqlite3. Right now there are only two contributors to the code base; however, we hope to attract more coders to the project that can help support additional adapters such as postgres and oracle. The connection/adapter piece of the code has been sufficiently abstracted so that it should not be difficult to create more adapters when the time comes.

Miscellaneous Options

When declaring a model you can also specify the primary_key and table_name. Protected/accessible declarations are available so that you can avoid mass assignment problems. Attributes can be aliased so that you may access them via different names.

 
class Book extends ActiveRecord\Model{
  static $primary_key = 'book_id';
  static $table_name = 'book_table';
  static $attr_accessible = array('author_id');
  static $attr_protected = array('book_id');
  static $alias_attribute = array(
    'new_alias' => 'actual_attribute',
    'new_alias_two' => 'other_actual_attribute'
  );
}
 

The Future

As I stated previously, very shortly the code will be available on launchpad. We are also in the works of putting up a website to host tutorials and documentation for the code. I will make additional posts once those milestones have been reached. Thanks for reading.

Today, I would like to present to you another class that will help extend your framework in similar fashion.

The Flash

If you aren't familiar with the way RoR uses "flash" messaging, you can take a look at the RoR API, or you can read this explanation:

The flash provides a way to pass temporary objects between actions. Anything you place in the flash will be exposed to the very next action and then cleared out.

The flash allows you to place messages in a user's session that can be viewed when navigating (or redirecting) to different pages or even the current page. If you read further into the API, you will see that the RoR flash offers you the following behavior:

• Set a regular message (viewable upon next http request)
• Create a "now" message (viewable now and not upon next http request)
• "Keep" a message or all messages (is a message is viewable now, it will now also be viewable upon the next http request)
• Discard/unset a message or all messages

If you're a good little coder, you would first attempt to steal this code from somewhere else. I have found a few sites that offer 'some' of the functionality of the RoR flash; however, I would like to have the flash in its full capacity. Therefore, I have created my own class.

The behavior of the flash is rather simple and so is my class. If you think about the lifetime of the messages, it should hit you that we have essentially two types of flash messages: now and later (next http request). Even though we have two types of messages, we actually only have one corresponding message. This means that a certain flash message "error" could have a now and a later message. The reason behind this is beceause we want to use discard() and keep() which we should be able to pass a 'key' to when invoked so that discard would remove all traces of our "error" message (or all messages if no key is passed). My class requires php >= version 5. Keep in mind that you will only want one instance of this class, so you could make it a singleton if you'd like. The constructor does all of the work by removing old messages and such, so you only have to worry about setting messages. Okay, let's see some code.

<!--p
# Instantiate flash which will remove old messages;
$flash = new UserSessionFlash;
$flash->error = 'This is an error message for the next page request.';
$flash-&gt;now('notice', 'Message will be available for the current page request.');
 
# Allows you to use the 'notice' for the next page request.
# If you do not pass a key, then it will keep ALL messages.
$flash-&gt;keep('notice'); 
 
# The $flash-&gt;error above has now been erased.
# Just like keep, if you do not pass a key, then ALL messages will be erased.
$flash-&gt;discard('error');
# Delete all messages.
$flash-&gt;discard();
?&gt;

As you can see this is all fairly basic. Simply add the flash instance to your action controller, and you access it via your page controller. What I have done is included a function in my action controller called flash() that returns my instance of the flash class. So my page controller would call

$this->flash()->error = 'This is an error msg.';
$this->flash()->now('notice', 'Show me the money.');

If you'd like, you can check out some other implementations below. Again, none of the other classes I've found offer the full rails flash behavior.

http://poorbuthappy.com/ease/archives/2007/04/22/3589/rails-flash-in-php
http://www.phpclasses.org/browse/package/3668.html
http://shabadeehoob.com/2007/03/17/rails-like-flash-messages-in-cakephp/
http://api.phpontrax.com/__filesource/fsource_PHPonTrax__vendortraxsession.php.html

Adding conventions to DRY our code

This article will provide a few snippets of code that I have recently plugged into the custom PHP framework that I use. However, those of you whom use and are more familiar with popular frameworks may be able to use this as well. I decided a few days ago to alter this custom framework in the following ways:

• an "application controller" which has access to the base and current page controller
• filter capabilities in page controllers

First, I will outline some basics about my framework so that you can understand my implementations.

The custom framework that I use is very similar to rails' conventions. It is an MVC framework and has almost a 1:1 folder/file structure to rails. One glaring difference is that it uses camelCase throughout the framework in opposition to the rails convetion. Anyway, let me start with the app folder (since this is the center of our attention).

You can see above that my app folder is almost exactly like rails except for the camelCase and the fact that my views have .tpls (go smarty!). You'll also notice that I have 3 page controllers plus the application controller. We are going to start with how I have implemented the application controller.

The Application Controller

You should already know that my page controllers will extend the "base" controller (which is simply Controller for me). Thus, my page controllers have access to all of the essentials such as redirections, session access, IoC, flash messaging, etc. So, we want to make another controller which will allow those 3 page controllers (and any future page controller) to access shared functions so that we can maintain DRY code. Keep in mind that this application controller should also have access to the parent controller.

The problem: How do we easily give our application controller shared communication between the parent controllers and child controller, but also disallowing it from being a page controller itself?

First let's take a look at my page controller:

<!--p
class HomeController extends Controller
{
  public function actionIndex()
  {
    $thi-->requireUser();
  }
};
?&gt;

<!--p
class ApplicationController extends AbstractApplicationController
{
   public function requireUser()
   {
     if (!$thi-->session()-&gt;hasRole(array('User')))
     {
        $this-&gt;flash()-&gt;error = 'You must be logged in to do that.';
	$this-&gt;redirect(array('controller' =&gt; 'home', 'action' =&gt; 'index'));
     }
   }
};
?&gt;

$this->applicationController = new ApplicationController($this);

<!--p
abstract class AbstractApplicationController
{
   private $controller;
 
   public function _construct(&#038;$controller)
   {
      if (is_subclass_of($controller, 'Controller'))
         $thi-->controller =&amp; $controller;
      else
         throw new Exception(get_class($controller) .' must be a subclass of Controller');
   }
 
   public function getController()
   {
     return $this-&gt;controller;
   }
 
   public function __call($meth, $args)
   {
     return call_user_func_array(array($this-&gt;controller, $meth), $args);
   }
};
?&gt;

<!--p
public function __call($meth, $args)
{
   return $thi-->applicationController-&gt;$meth();
}
?&gt;

<!--p
class GamesController extends Controller
{
   protected $BEFORE_FILTER = array(
     'requireUser'--> array('except' =&gt; array('myExceptionAction'))
   );	
 
   public function actionIndex()
   {
      //before filter method will be invoked before this method is invoked
   }
 
   public function actionMyExceptionAction()
   {
      //before filter method will not be invoked for this
   }
};
?&gt;

<!--p
//instaniate our ApplicationController before
//the current page's action is invoked
$thi-->applicationController = new ApplicationController($this);
//run before filter
$this-&gt;filter('before');
 
private function filter($temporality)
{
  $filter = strtoupper($temporality.'_FILTER');
  $controllerName = $this-&gt;getControllerName().'Controller';
  $controller = new ReflectionClass($controllerName);
 
  foreach ($controller-&gt;getProperties() as $property)
  {
    if ($property-&gt;name === $filter)
    {
      $filter = $this-&gt;{$property-&gt;name};
      if (!is_array($filter))
      {
 	settype($filter, 'array');
 	$filter[$filter[0]] = $filter[0];
 	unset($filter[0]);
      }
 
      foreach ($filter as $method =&gt; $options)
      {
 	$action = $this-&gt;currentAction();
 	if(!is_array($options) || (!isset($options['only'])
          &amp;&amp; !isset($options['except'])))
	      $this-&gt;$method();
	elseif (isset($options['only'])
          &amp;&amp; in_array($action, $options['only']))
	      $this-&gt;$method();
	elseif (isset($options['except'])
          &amp;&amp; !in_array($action, $options['except']))
	      $this-&gt;$method();
      }
    }
  }
}
?&gt;