It is precisely this overhead that needs to be eliminated. Time is money and if you are working with a new application on a weekly or monthly basis the scaffolding overhead comprises a great deal of that time. Not to mention that most web applications today are running to and fro from a database. This time spent fetching and storing data makes up for a significant chunk in the overall development. 2009 is a big step forward for PHP and there are tools out there that tackle this problem.

Enter ZendFramework 1.8, just recently released it represents Zend's commitment to make PHP a competitive environment for Rapid Application Development (totally RAD). There are several new tools included within this release, primarily Zend_Tool, Zend_Application, and Zend_Navigation. Zend_Tool_Project allows for the automated creation of new projects complete with a ready to go application shell. You can liken this shell to a new Hello World! project with the core structure and scaffolding setup. Rather than going into the details of everything included within the release, you can find a thorough overview within the 1.8 release notes.

This brings me to what I'm really excited about. Recently we pushed out PHP ActiveRecord for everyone! This tutorial goes over the steps necessary to build your environment. You'll be able to create new projects within the ZendFramework with PHP ActiveRecord. I believe developers should spend their time dealing with application logic and not be burdened with configuration, bootstrapping or custom SQL. For this tutorial I am using the following environment:

- Ubuntu 9.04
- PHP 5.3-RC1
- MySQL 5.4
- Apache 2.2.11
- ZendFramework 1.8 min
- php-activerecord 0.9

For the sake of keeping this tutorial short and concise, there are already several resources out there that deal with compiling PHP 5.3. I'll assume you've already setup your server with MySQL, PHP and Apache ready to go. In fact, you can use nginx if you prefer going down that route or even ZendServer CE, although I personally prefer Apache. It certainly doesn't matter what you're serving out PHP with and it will probably be dependent on what you're existing environment is using.

Installing ZendFramework 1.8 and ActiveRecord

We're going to want both libraries in our PHP include directory. First you should download the latest ZF release, 1.8.1 at the time of this post. When you have it ready to go on your server it is important to make sure your environment is working. If you installed PHP 5.3 correctly you should be able to get the following output from CLI:

# php -v
PHP 5.3.0RC1 (cli) (built: May  3 2009 15:31:21)
Copyright (c) 1997-2009 The PHP Group
Zend Engine v2.3.0, Copyright (c) 1998-2009 Zend Technologies
# php -i | grep include_path
include_path => .:/usr/local/php/lib => .:/usr/local/php/lib

Don't worry if your include path is elsewhere, just make a note of where it is since we'll be dumping the Zend stuff there. Now to extract and install Zend:

# tar xzfv ZendFramework-1.8.1-minimal.tar.gz
# mv ZendFramework-1.8.1-minimal/library/Zend /usr/local/php/lib/
# mv ZendFramework-1.8.1-minimal/bin/zf.* /usr/local/php/bin/
# ln -s /usr/local/php/bin/zf.sh /usr/bin/zf
# zf show version
Zend Framework Version: 1.8.1

I opted to put the zf.sh into my PHP bin directory and symlink it from my bin dir. The next step is to download the source from github and unpack it into your include path to a directory called php-activerecord. Our dependencies are there and we can move on to our first project.

Create Project

Now that everything is installed, we want to test out zf create project. The following example is a bare bones project ready for us to extend:

# zf create project /var/www/newproject
Creating project at /var/www/newproject
# ls /var/www/newproject/
application  library  public  tests

That is it, you are ready for the web. Configure your web server to start serving out pages from the location you set for your new project. The docroot path should be /var/www/newproject/public. Load up your web browser and you should see your page.

Loading up ActiveRecord

Inside your application/Bootstrap.php you might notice the code rather bare. The Zend Bootstrapper will load anything within the bootstrap function starting with _init*. To tack on ActiveRecord, we simply add the following:

class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
{
    protected function _initActiveRecord()
    {
        require_once("php-activerecord/ActiveRecord.php");
        ActiveRecord\Config::initialize(function($cfg)
        {
            $cfg->set_model_directory(APPLICATION_PATH . '/models' );
            $cfg->set_connections(array(
                'development' => 'mysql://user:password@localhost/newproject'));
        });
    }
}

You will need to adjust your SQL connect strings, and at this point if you want to restructure your model directory differently you may do so. There are only two configuration points, both of which you could pass from an XML or INI config. Even though ActiveRecord is loaded, we still need to test out that everything is working. In order to do this we will need to create some test data:

CREATE DATABASE newproject;
USE newproject;
CREATE TABLE books(
    id int NOT NULL PRIMARY KEY AUTO_INCREMENT,
    name varchar(50),
    author varchar(50)
);
INSERT INTO books(id,name,author) VALUES(1,'How to be Angry','Jax');

The next step is to create a model for the books table to be used from within your application. In your model directory that you set within the configuration above, create a Book.php with the following:

class Book extends ActiveRecord\Model { }

And finally to test out that everything is working, within your IndexController.php for indexAction add the following:

public function indexAction()
{
    $this->view->book = Book::find(1);
}

And so we can actually see the output, edit your /views/scripts/index/index.phtml with the following:

Today I read <?=book->name?> by <?=book->author?> and it was terrible.

As you can see, you can pull the variable set by the action assigned to the view or you can query right from the view itself if you please. If you get the following output, everything is good to go:

Today I read How to be Angry by Jax and it was terrible.

Next Steps

Going forward, there is plenty of room to extend this setup. Unfortunately, the Zend_Tool_Project abstraction documents are still being completed but there are examples out there on how to add new commands to it. One new command I am working on is the automated creation of AR models by passing a database connect string to simplify the process even further.

Quick Start

We'll start first with a bare bones example to show how little you need to get up and running. There's very little to configure. We've adhered to the convention over configuration philosophy so there are no code generators you need to run and no xml/yaml mapping files to maintain.

<?
// make sure the ActiveRecord project is in your current directory
// or your include_path
require_once 'ActiveRecord/ActiveRecord.php';
 
// assumes a table name of "books" with a primay key named "id"
class Book extends ActiveRecord\Model { }
 
// initialize ActiveRecord
ActiveRecord\Config::initialize(function($cfg)
{
    $cfg->set_model_directory('.');
    $cfg->set_connections(array(
        'development' => 'mysql://username:password@localhost/database_name'));
});
 
print_r(Book::first()->attributes());
?>

That's it! The code for this is located in the examples/simple directory. You can run it with "php examples/simple/simple.php". Make sure to modify the connection string to suit your system and run the simple.sql script appropriately.

Serious Business Time

Now for a not so completely trivial example. This example will simulate a very dumb ordering and payment model. See the examples/orders directory for the source. You can run this sample by executing "php examples/orders/orders.php". Again, make sure you modify the connection string to suit your system and be sure the schema in orders.sql has been created in your test database.

First, let's look at the models:

class Person extends ActiveRecord\Model
{
    // a person can have many orders and payments
    static $has_many = array(
        array('orders'),
        array('payments'));
 
    // must have a name and a state which has a custom error message
    static $validates_presence_of = array(
        array('name'), array('state', 'message' => 'Where do you live then?'));
}

class Order extends ActiveRecord\Model
{
    // order belongs to a person
    static $belongs_to = array(
        array('person'),
        array('order'));
 
    // order can have many payments by many people
    // the conditions is just there as an example as it makes no logical sense
    static $has_many = array(
        array('payments'),
        array('people',
            'through'    => 'payments',
            'select'     => 'people.*, payments.amount',
            'conditions' => 'payments.amount < 200'));
 
    // order must have a price and tax > 0
    static $validates_numericality_of = array(
        array('price', 'greater_than' => 0),
        array('tax',   'greater_than' => 0));
 
    // setup a callback to automatically apply a tax
    static $before_validation_on_create = array('apply_tax');
 
    public function apply_tax()
    {
        if ($this->person->state == 'VA')
            $tax = 0.045;
        elseif ($this->person->state == 'CA')
            $tax = 0.10;
        else
            $tax = 0.02;
 
        $this->tax = $this->price * $tax;
    }
}

class Payment extends ActiveRecord\Model
{
    // payment belongs to a person
    static $belongs_to = array(
        array('person'));
}

And here's the code that does everything:

<?
require_once dirname(__FILE__) . '/../../ActiveRecord.php';
 
// initialize ActiveRecord
ActiveRecord\Config::initialize(function($cfg)
{
    $cfg->set_model_directory(dirname(__FILE__) . '/models');
    $cfg->set_connections(array(
        'development' => 'mysql://test:test@127.0.0.1/orders_test'));
 
    // you can change the default connection with the below
    //$cfg->set_default_connection('production');
});
 
// create some people
$jax = new Person(array('name' => 'Jax', 'state' => 'CA'));
$jax->save();
 
// compact way to create and save a model
$tito = Person::create(array('name' => 'Tito', 'state' => 'VA'));
 
// place orders. tax is automatically applied in a callback
// create_orders will automatically place the created model into $tito->orders
// even if it failed validation
$pokemon = $tito->create_orders(array('item_name' => 'Live Pokemon', 'price' => 6999.99));
$coal    = $tito->create_orders(array('item_name' => 'Lump of Coal', 'price' => 100.00));
$freebie = $tito->create_orders(array('item_name' => 'Freebie', 'price' => -100.99));
 
if (count($freebie->errors) > 0)
{
    echo "[FAILED] saving order $freebie->item_name: " .
        join(',',$freebie->errors->full_messages()) . "\n\n";
}
 
// payments
$pokemon->create_payments(array('amount' => 1.99, 'person_id' => $tito->id));
$pokemon->create_payments(array('amount' => 4999.50, 'person_id' => $tito->id));
$pokemon->create_payments(array('amount' => 2.50, 'person_id' => $jax->id));
 
// reload since we don't want the freebie to show up (because it failed validation)
$tito->reload();
 
echo "$tito->name has " . count($tito->orders) . " orders for: " .
    join(', ',ActiveRecord\collect($tito->orders,'item_name')) . "\n\n";
 
// get all orders placed by Tito
foreach (Order::find_all_by_person_id($tito->id) as $order)
{
    echo "Order #$order->id for $order->item_name " .
        "($$order->price + $$order->tax tax) " .
        "ordered by " . $order->person->name . "\n";
 
    if (count($order->payments) > 0)
    {
        // display each payment for this order
        foreach ($order->payments as $payment)
        {
            echo "  payment #$payment->id of $$payment->amount by " .
            $payment->person->name . "\n";
        }
    }
    else
        echo "  no payments\n";
 
    echo "\n";
}
 
// display summary of all payments made by Tito and Jax
$conditions = array(
    'conditions' => array('id IN(?)',array($tito->id,$jax->id)),
    'order'      => 'name desc');
 
foreach (Person::all($conditions) as $person)
{
    $n = count($person->payments);
    $total = array_sum(ActiveRecord\collect($person->payments,'amount'));
    echo "$person->name made $n payments for a total of $$total\n\n";
}
 
// using order has_many people through payments with options
//
// array('people',
//    'through' => 'payments',
//    'select' => 'people.*, payments.amount',
//    'conditions' => 'payments.amount < 200'));
//
// this means our people in the loop below also has the payment information since
// it is part of an inner join we will only see 2 of the people instead of 3
// because 1 of the payments is greater than 200
$order = Order::find($pokemon->id);
echo "Order #$order->id for $order->item_name ($$order->price + $$order->tax tax)\n";
 
foreach ($order->people as $person)
    echo "  payment of $$person->amount by " . $person->name . "\n";
?>

The orders example should produce the following output:

[FAILED] saving order Freebie: Price must be greater than 0, Tax must be greater than 0

Tito has 2 orders for: Live Pokemon, Lump of Coal

Order #3 for Live Pokemon ($6999.99 + $315 tax) ordered by Tito
  payment #4 of $1.99 by Tito
  payment #5 of $4999.5 by Tito
  payment #6 of $2.5 by Jax

Order #4 for Lump of Coal ($100 + $4.5 tax) ordered by Tito
  no payments

Tito made 2 payments for a total of $5001.49

Jax made 1 payments for a total of $2.5

Order #3 for Live Pokemon ($6999.99 + $315 tax)
  payment of $2.50 by Jax
  payment of $1.99 by Tito

EXTENDED CONFIGURATION

Here's one more example that is basically the same as the first, but the point here is to display some of the ways to extend configuration (while remaining close to convention).

class Book extends ActiveRecord\Model
{
    // explicit table name since our table is not "books"
    static $table_name = 'simple_book';
 
    // explicit pk since our pk is not "id"
    static $primary_key = 'book_id';
 
    // explicit connection name since we always want production with this model
    static $connection = 'production';
 
    // explicit database name will generate sql like so => db.table_name
    static $db = 'test';
}
 
// ActiveRecord allows the use of multiple connections
$connections = array(
    'development' => 'mysql://test:test@127.0.0.1/development',
    'production' => 'mysql://test:test@127.0.0.1/production'
);
 
// initialize ActiveRecord
ActiveRecord\Config::initialize(function($cfg) use ($connections)
{
    $cfg->set_model_directory('.');
    $cfg->set_connections($connections);
});
 
print_r(Book::first()->attributes());
 

Simplicity

From the configuration, all the way to a serious-business example, ActiveRecord takes care of the heavy-lifting and the gritty details for you. This allows you, the developer, to focus more on business logic and complex code instead of composing custom SQL queries or designing ways to handle your data. Because we have embraced a convention over configuration philosophy, using our library is not painful. The conventions are easy to remember which will also contribute to stream-lining your productivity as a developer.

Where can you find ActiveRecord?

Again, the code is hosted on http://github.com/kla/php-activerecord/. We also have a website which will be available in the near future. We hope to have all the necessary content such as: tutorials, screencasts, and documentation.

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.