Documentation

While this attempts to document most of the features of ActiveRecord, it may not be entirely complete. I’ve tried to create tests for all pieces of functionality that exist in ActiveRecord. To view and / or run these tests check out the devel/ branch in the Subversion repository. In other words, there may be some functionality that is not documented here but is used in the tests.

For example purposes, let’s pretend we’re building a blog. You’ll have model classes which are each the model of a database table. Each model class is in a separate file. The stubs of these files are automatically generated for you by generate.php. Every time you update your database schema, you’ll have to run generate.php again. It will not overwrite the files you’ve altered, but will overwrite the *Base.php files. Once you have the model stubs generated you can use them and work with the tables individually. However, in order to use the relationship specific abilities of ActiveRecord, you’ll need to specify the relationships in your models as outlined below in the Associations section.

Associations

In ActiveRecord we specify relationships between the tables in the model classes. There are 3 types of relationships, 1:1, 1:many, and many:many.

1:1

In our example, blog posts have a 1:1 relationship with slugs. Here’s how you’d specify that inside the Post and Slug classes.

  1. /* inside Post.php */
  2.   protected $has_one  = array(’slug’);
  3.  
  4. /* inside Slug.php */
  5.   protected $belongs_to  = array(‘post’);

In a 1:1 relationship we must specify each side of the relationship slightly differently so that ActiveRecord knows the “direction” of the relationship. We use belongs_to for the model whose table contains the foreign key (post_id in this case). The other side of the relationship uses has_one. Since an object could have multiple 1:1 relationships, we use an array to allow for additional tables. Notice the singular use of slug and post. The code tries to read like English as much as possible, so later when we do 1:many relationships you’ll plural strings.

After you’ve specified this relationship you can do some extra things with your models. On every slug and post object you can now do →post and →slug to get its post and slug respectively as an ActiveRecord object. Also you set assign a slug or post using this mechanism. Furthermore, a save will cascade to the relationship.

  1. $slug = Slug::find(‘first’); # SQL query to grab first slug
  2. $slug->post; # an SQL query occurs behind the scenes to find the slug’s post
  3.  
  4. $p = Post::find(‘first’, array(‘include’ => ’slug’)); # SQL join
  5. $p->slug; # no SQL query here because we already got this post’s slug in the SQL join in the previous line
  6.  
  7. $p = Post::find(‘first’);
  8. $s = new Slug(array(’slug’ => ’super-slug’));
  9. $p->slug = $s; # assign a slug to this post
  10.  
  11. $p->slug->slug = ‘foobar’;
  12. $p->save(); # cascading save (post and slug are saved)

1:many

In our example a post has many comments, but a comment only has one post. Here’s how you’d specify it in the Post and Comment classes.

  1. /* inside Post.php */
  2.   protected $has_many = array(‘comments’);
  3.  
  4. /* inside Comment.php */
  5.   protected $belongs_to = array(‘post’);

Notice, we used plural “comments” for the has_many and a singular “post” for belongs_to. Also notice how the comments table contains the foreign key (post_id) and therefore is a belongs_to relationship. Once we’ve done this Comment can do the same things as an 1:something relationship can (see 1:1).

Post now has some slight variations to the features added in a 1:1 relationship. Now when accessing the attribute comments you’d get an array of comment ActiveRecord objects that belong to this Post.

  1. $p = Post::find(‘first’);
  2. echo $p->comments[0]->body;

You can also get the list of comment ids that belong to this post by calling →comment_ids. You can set the ids in a similar fashion.

  1. $p = Post::find(‘first’);
  2. $foo = $p->comment_ids;
  3. # foo is now an array of comment ids that belong to this post
  4. array_pop($foo); # pop off last comment id
  5. array_push($foo, 23); # and another comment id to $foo
  6.  
  7. $p->comment_ids = $foo;
  8. /* this will remove the comment we popped off of foo
  9.     and add the comment we pushed onto foo to this post
  10. */

You can also push new objects onto the relationships.

  1. $c = new Comment(array(‘author’ => ‘anon’, ‘body’ => ‘first comment!!11′));
  2. $p->comments_push($c); # this call saves the new comment and associates with this post

In this example, we might want to have comments destroyed when their post is destroyed or when they are disassociated with their post. You can have this happen by specifying the relationship slightly differently. You can do this on any sort of relationship. Instead have the following in the Post model.

  1. /* inside Post.php */
  2.   protected $has_many = array(array(‘comments’ => array(‘dependent’ => ‘destroy’)));

many:many

A many:many relationship will have an intermediate table (and therefore model) which ties two other tables together. In our example, there is a many:many relationship between posts and categories. Our intermediate table is categorizations. Here is how that is specified:

  1. /* inside Categorization.php */
  2.   protected $belongs_to = array(‘post’, ‘category’);
  3.  
  4. /* inside Post.php */
  5.   protected $has_many = array(  ‘categorizations’,
  6.                           array(‘categories’ => array(‘through’ => ‘categorizations’)));
  7.  
  8. /* inside Category.php */
  9.   protected $has_many = array(  ‘categorizations’,
  10.                           array(‘posts’ => array(‘through’ => ‘categorizations’)));

Since the categorizations table contains the foreign keys post_id and category_id, it has a belongs_to relationship with those. The Post model has a regular has_many relationship with categorizations and a special has_many relationship with categories. We specify which table that relationship goes through (categorizations), IOW which table is the intermediate table of that relationship. The category to post relationship is specified similarly.

Posts and categories can now use the special has_many methods documented in the 1:many relationship.

Working With Models

This section applies to all models regardless of any associations they may have.

Create

  1. $p = new Post(array(‘title’ => ‘First Post!11!’, ‘body’ => ‘This is the body of my post’));
  2. $p->save(); # saves this post to the table
  3.  
  4. $p2 = new Post();
  5. $p2->title = "Second Post";
  6. $p2->body = "This is the body of the second post";
  7. $p2->save(); # save yet another post to the db

Retrieve

Retrieving data involves finding the rows you want to look at and subsequently grabbing the column data as needed. The first parameter for the find method should be one of the following:

When the first parameter is an id number or the string “first”, the result will be an ActiveRecord object. Otherwise, it will be an array of ActiveRecord objects.

The find method takes quite a few different options for its second parameter by using “named parameters” by accepting an array of key, value pairs. You can pass it the following keys with sane values:

  1. $p = Post::find(1); # finds the post with an id = 1
  2. $p->title; # title of this post
  3. $p->body;  # body of this post
  4.  
  5. # returns the 10 most recent posts in an array, assuming you have a column called "timestamp"
  6. $posts = Post::find(‘all’, array(‘order’ => ‘timestamp DESC’, ‘limit’ => 10));

Update

  1. $p = Post::find(1);
  2. $p->title = "Some new title";
  3. $p->save(); # saves the change to the post
  4.  
  5. # alternatively, the following is useful when a form submits an array
  6. $_POST[‘post’] = array(‘title’ => ‘New Title’, ‘body’ => ‘New body here!’);
  7. $p = Post::find(1);
  8. $p->update_attributes($_POST[‘post’]); # saves the object with these attributes updated

Destroy

  1. $p = Post::find(1);
  2. $p->destroy();

Hooks

The following hooks are available, just define the method of the same name in the model that you want to use them:

Escaping Query Values

ActiveRecord will do proper escaping of query values passed to where possible. However, it can’t do proper quoting when you do something like the following.

  1. $p = Post::find(‘first’, array(‘conditions’ => "title = {$_GET['title']}"));

Instead you can use the quote static method to quote that value like so.

  1. $title = ActiveRecord::quote($_GET[‘title’]);
  2. $p = Post::find(‘first’, array(‘conditions’ => "title = $title"));

Manual Queries

Occasionally, though hopefully rarely, you may need to do specify some queries by hand. You can use the query static method. This returns an associative array with all the rows in it.

  1. ActiveRecord::query("SELECT COUNT(*) FROM bar as b1, bar as b2 where b2.id != b1.id");

Table Structure For Example

  1. –
  2. – Table structure for table `categories`
  3. –
  4.  
  5. CREATE TABLE `categories` (
  6.   `id` int(11) NOT NULL AUTO_INCREMENT,
  7.   `name` varchar(255) DEFAULT NULL,
  8.   PRIMARY KEY  (`id`)
  9. ) TYPE=MyISAM;
  10.  
  11. –
  12. – Table structure for table `categorizations`
  13. –
  14.  
  15. CREATE TABLE `categorizations` (
  16.   `id` int(11) NOT NULL AUTO_INCREMENT,
  17.   `post_id` int(11) DEFAULT NULL,
  18.   `category_id` int(11) DEFAULT NULL,
  19.   PRIMARY KEY  (`id`)
  20. ) TYPE=MyISAM;
  21.  
  22. –
  23. – Table structure for table `comments`
  24. –
  25.  
  26. CREATE TABLE `comments` (
  27.   `id` int(11) NOT NULL AUTO_INCREMENT,
  28.   `author` varchar(255) DEFAULT NULL,
  29.   `body` text,
  30.   `post_id` int(11) DEFAULT NULL,
  31.   PRIMARY KEY  (`id`)
  32. ) TYPE=MyISAM;
  33.  
  34. –
  35. – Table structure for table `posts`
  36. –
  37.  
  38. CREATE TABLE `posts` (
  39.   `id` int(11) NOT NULL AUTO_INCREMENT,
  40.   `title` varchar(255) DEFAULT NULL,
  41.   `body` text,
  42.   PRIMARY KEY  (`id`)
  43. ) TYPE=MyISAM;
  44.  
  45. –
  46. – Table structure for table `slugs`
  47. –
  48.  
  49. CREATE TABLE `slugs` (
  50.   `id` int(11) NOT NULL AUTO_INCREMENT,
  51.   `slug` varchar(255) DEFAULT NULL,
  52.   `post_id` int(11) NOT NULL,
  53.   PRIMARY KEY  (`id`)
  54. ) TYPE=MyISAM;

Related Pages

3 Comments »

  1. LifeFeel said,

    July 27, 2008 @ 6:03 am

    I think it’s very nice library for PHP.

    Are you stopping to develop this project?

    I really wanted to not to stop this project.

  2. sean said,

    October 9, 2008 @ 3:28 pm

    Does this library support foreign keys other than “table_id” convention? I’d like to use it but am using a legacy database where foreign keys don’t follow the same conventions as rails. Didn’t see it in the docs so thought i’d ask

    thanks!

  3. Tanoor said,

    October 28, 2008 @ 9:06 am

    Hi this library seems very interesting. Is it a simple example or a mature project?

    Tanoor.

RSS feed for comments on this post · TrackBack URI

Leave a Comment