Download the PHP package lukebaker/activerecord-php without Composer

ActiveRecord In PHP

Motiviation

I wrote this after having been spoiled by Ruby on Rails’ implementation of the ActiveRecord pattern, while still needing to work primarily in PHP. When I started this, there did exist some ORM options in PHP. However, I wasn’t satisfied with any one in particular. My goals were to create an implementation that was very similar to the Rails syntax, easy to install, and fast.

Requirements

• PHP5
• Naming of tables and columns that follows the Rails convention.

Installation

1. Create your database and tables, if you haven’t already. (remember use Rails’ conventions for table and column names)

2. Download recent ActiveRecord release or

   git clone https://github.com/lukebaker/activerecord-php.git

3. Untar into a models/ directory within your project or move checked out directory activerecord-php/ into your models/ directory.
4. There should now be a models/activerecord-php/ directory, edit models/activerecord-php/config.php to your liking.
5. Run models/activerecord-php/generate.php
6. This should have have generated model stubs inside your models/ directory. Edit these model files to tell ActiveRecord about the relationships between tables. Do not edit *Base.php files as they get overwritten every time you run generate.php

7. Use ActiveRecord, by including the models that you want to use:

   require_once 'models/Post.php';

Example

Create

Retrieve

Update

Destroy

Relationships

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.

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: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.

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.

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.

You can also push new objects onto the relationships.

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.

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:

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

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:

• an id number
• an array of id numbers
• the string “first”
• the string “all”

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:

• limit
• order
• group
• offset
• select
• conditions
• include (for associations)

Update

Destroy

Hooks

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

• before_save
• before_create
• after_create
• before_update
• after_update
• after_save
• before_destroy
• after_destroy

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.

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

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.

Table Structure For Example