I present to you the Extensible PHP Caching Library (Hosted at GitHub) - This collection of classes makes it easy to customize key or column names to your needs as well as switch from one data store to another. This extensibility is baked into the core of the library via an abstract class. This abstract Cache class takes an associative array of keys/columns and determines how to use those keys based on the type of cache back end you are using. For example: Suppose you are using a RDBMS such as MySQL. In this case the associative array will be parsed and the query built such that the key is the column name and the value is what you want to query on. However, if you chose to use a NoSQL key/value store such as Memcache then the associative array is sorted and imploded to create a single string as the key.

Since we always specify the key as an associative array, switching between different data stores is as simple as changing the Class name from say MCache to SQLCache in your code. Nothing else is required to change data stores. Keys, expiration dates, and data processing all stay the same and all functions are called with the same arguments. This functionality is attributed to the abstract base Cache class which guides and regulates the inheriting classes.

Lets get to some examples:

In the following example we create a new SQLCache object and pass it our associative array of keys and values. Check if there is cached data, if there isnt then do something to generate the data and then cache it. Notice how you dont have to pass the key in again when setting the cache. The key is stored within the object so you can get and set as many times as you need without having to set the key every time. Lastly we delete the cache.

// Get Cache
$cache = new SQLCache(array('column1' => 123, 'column2' => 'blah', … ));
$output = $cache->getCache();
 
if(!$output) {
  // Do something to generate data
  $output = 'some datas';
  // Set Cache
  if($cacheNow) {
    // Force a write to cache now
    $cache->setCache($output, '+1 day', true);
  } else {
    // Setting no time defaults to time() + 86400, one day from now.
    $cache->setCache($output);
  }
}
 
print $output;
 
// Delete the cache
$cache->deleteCache();
 

If ever you needed to update this caching strategy to include Memcached the only change would be to change SQLCache to Mcache:

$cache = new SQLCache(array('column1' => 123, 'column2' => 'blah', … ));
to
$cache = new MCache(array('key1' => 123, 'key2' => 'blah', … ));
 

The column and key names are arbitrary and may be set to anything you want to name it. For SQL caches make sure you create a cache table that has the corresponding column names and that they are indexed optimally.

While I have only created classes for SQL (MySQL - since there is a LIMIT 1), Memcached and File based caching, the base class can be extended to include any key/value store or any database with columns (MongoDB, CouchDB, Tokyo, Postgress, Oracle, etc). Just update the back end calls and you are good to go.

For anyone who updates or adds functionality please let me know so I can give credit where credit is due. This library is available under the LGPLv3.

class Rating
{
  public static function ratingAverage($positive, $total, $power = '0.05')
  {
    if ($total == 0)
      return 0;
 
    $z = Rating::pnormaldist(1-$power/2,0,1);
    $p = 1.0 * $positive / $total;
    $s = ($p + $z*$z/(2*$total) - $z * sqrt(($p*(1-$p)+$z*$z/(4*$total))/$total))/(1+$z*$z/$total);
    return $s;
  } 
 
  public static function pnormaldist($qn)
  {
    $b = array(
      1.570796288, 0.03706987906, -0.8364353589e-3,
      -0.2250947176e-3, 0.6841218299e-5, 0.5824238515e-5,
      -0.104527497e-5, 0.8360937017e-7, -0.3231081277e-8,
      0.3657763036e-10, 0.6936233982e-12);
 
    if ($qn < 0.0 || 1.0 < $qn)
      return 0.0;
 
    if ($qn == 0.5)
      return 0.0;
 
    $w1 = $qn;
 
    if ($qn > 0.5)
      $w1 = 1.0 - $w1;
 
    $w3 = - log(4.0 * $w1 * (1.0 - $w1));
    $w1 = $b[0];
 
    for ($i = 1;$i <= 10; $i++)
      $w1 += $b[$i] * pow($w3,$i);
 
    if ($qn > 0.5)
      return sqrt($w1 * $w3);
 
    return - sqrt($w1 * $w3);
  }
}
 

The function takes 3 parameters: the positive votes, total votes, and the power. The power can be adjusted, 0.10 to have a 95% chance that your lower bound is correct, 0.05 to have a 97.5% chance, etc.  Sample usage:

sample(1,0);
sample(100,50);
sample(250,100);
sample(1000,500);
 
function sample($p,$n)
{
  echo Rating::ratingAverage($p,$p+$n);
}
 

Output:

When dealing with sites like Reddit, Digg, and the like you have a certain "freshness" element. The above solution might be a working model for the entire span of the site, but for that front page element you will need to implement some form of "gravity". This can be done by taking the raw score and decaying it over time, like so:

 
class Rating
{
  ...
  public static function gravityRating($positive, $total, $time, $power = '0.05')
  {
    if ($total == 0)
      return 0;
    return (Rating::ratingAverage($positive, $total, $power) / pow($time,0.5));
  }
  ...
}
 
sample(100,50,'0.5');
sample(100,50,'1');
sample(100,50,'4');
sample(100,50,'8');
sample(100,50,'24');
 
function sample($p,$n,$time)
{
  echo Rating::gravityRating($p,$p+$n,$time)."\n";
}
 

In the example above, $time represents the age (in hours) and you can see the decay in the output:

0.83141271310867
0.58789756740385
0.29394878370192
0.20785317827717
0.12000408843024

My recommendation would be to "cap" the time to stop decay after a fixed period such as 12 or 24 hours to stop the initial boost of fresh content and let it normalize quickly. The rate of decay of course, can be adjusted as fast or as slow as you want and again the individual weighting you want to apply will vary from site to site. Depending on the volatility of your content, a front page "freshness" that will encompass a week would not merit a 12 hour decay, but rather a week long decay. Hopefully the above code is enough to get started with content rating and making better use of user feedback and can help lead web masters to making a more intelligent calculation of their content beyond the traditional "5-Star Rating".

[ c9maji2tvz ]

API Features

• Supports CURL and fopen HTTP access methods, with autodetection
• PHP arrays for Google Analytics metrics and dimensions
• Account data object mapping - get methods for parameters
• Report data object mapping - get methods for metrics and parameters
• Easy filtering, use a GAPI query language for Google Analytics filters
• Full PHP5 Object Oriented code, ready for use in your PHP application

Google Quotas

• The quota applies to a single web property
• 10,000 requests per 24 hours
• 100 requests in any given 10-second period
• A query is also limited to pagination limits of 10,000 entries per feed, with a default response of 1,000 entries

While the broad set of data they have is extremely useful to pull down to do your own processing on, I find the custom visitor segments with the API a lot more interesting.    If you have a user based site with registration and collect information on your users, you can pull this data back out to determine a lot of information about your user.   A lot of tools are already built into Analytics for reporting but the ability to mash this data up to provide custom reporting for your users (customers) without giving them access to analytics is key to delivering metrics and performance

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.

The algorithm simplifies a polyline by removing vertices that do not contribute (sufficiently) to the overall shape. It is a recursive process which finds the most important vertices for every given reduction. First, the most basic reduction is assumed. A single segment connecting the beginning and end of the original polyline. This is when the recursion starts, the most significant vertex (the most distant) for this segment is found and, when the distance from this vertex to the segment exceeds the reduction tolerance, the segment is split into two sub-segments, each inheriting a subset of the original vertex list. Each segment continues to subdivide until none of the vertices in the local list are further away than the tolerance value.

There is a PHP class that does just this: Douglas-Peucker Polyline Simplification in PHP by Anthony Cartmell. Based on the original quality of the data and tolerance level, I was able to achieve a 90-93% reduction in size. This reduction allows me to represent significantly more data at a reasonable performance level to clients. Keep in mind, that this reduction is removing data out of the coordinate array so the quality of your representation will go down with the tolerance and reduction being applied. I highly suggest that you play around with the tolerance until you find a good balance between data size and image quality.

pnPoly - Used to determine if a coordinate falls inside a polygon.
Centroid - Find the center of a polygon..
Area - Calculate the area of a polygon.
googleGeoCoder - Extracts GIS information from Google Maps from an address.
PolylineEncoder - Takes a set of coordinates and encodes it for Google Maps.

If you ran into the problem I did, which is that a lot of the data is coming in the form of shp/dbf files and needs to be parsed out to something friendlier either KML or CSV, there are a couple of solutions for that. You can parse out the data with shp2text if your source coordinate format is already in lat/lng or if you have different coordinate system and use ArcGIS, you can try the plugin Export to KML 2.5.3 to help with the exporting of data with the ESRI suite of products.

Once your data is in SQL, the following query is an example of distance sorting with SQL. You can grab a copy of the zip_codes database here and play around with it.

SELECT *,
sqrt((69.1 * ("37.6" - latitude)) * (69.1 * ("37.6" - latitude)) +
(53.0 * ("-77.6" - longitude)) * (53.0 * ("-77.6" - longitude)))
AS distance
FROM `zip_codes`
HAVING distance < 10
ORDER BY distance ASC

I realized that I was over-thinking the problem so I did a little test to just see how much overhead Drupal is adding. I can execute ten times the number of queries natively through PHP and mysql_connect than if I were to execute those queries from within Drupal with just bootstrap included. Apache answered requests and processed these several million round trips to the database much faster. I understand that as a framework there is a lot being loaded, but a whole decimal point off when dealing with requests/sec is a huge overhead.

The better part of the last few days was spent gutting the inner workings of Drupal and removing as much of it as possible to lover overhead, reduce response time, and hopefully let us scale a little further on the hardware that we have. As it is, traffic is growing a steady 40-50% month over month for a while now and we are already dealing with several million unique visitors a month. That number is growing rapidly with no ceiling in the near future and it's unfortunate that at this point the only way to make this work is to break the upgrade path of Drupal.

Going through the code base, it's easy to see where so much of the bloat comes from. With comments like: "TODO: remove this when we require at least PHP 4.4.0" there is a lot of backwards compatibility that is required to support such a large community. I am seeing more and more Frameworks replace legacy CMS systems that provide a bare bone set of tools. The agility, performance, and maintenance of a ground up site using frameworks like Symfony or Rails leads to longer development cycles and increased costs but there is a point where you stop putting a round peg in a square hole and realize that the cost of maintenance and development down the road will far exceed the up front investment.

I'm glad Drupal has been able to take us this far and I'm very grateful for the community behind it. It's a pleasant surprise that everything is still working and hopefully we can get a few more miles out of it before we are ready to do the next iteration of the site.

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;