jcs.org
a tiny mvc framework for php using php-activerecord
1# PHP ActiveRecord #
2
3Version 1.0
4
5by Kien La and Jacques Fuentes
6
7<http://www.phpactiverecord.org/>
8
9## Introduction ##
10A brief summarization of what ActiveRecord is:
11
12> Active record is an approach to access data in a database. A database table or view is wrapped into a class,
13> thus an object instance is tied to a single row in the table. After creation of an object, a new row is added to
14> the table upon save. Any object loaded gets its information from the database; when an object is updated, the
15> corresponding row in the table is also updated. The wrapper class implements accessor methods or properties for
16> each column in the table or view.
17
18More details can be found [here](http://en.wikipedia.org/wiki/Active_record_pattern).
19
20This implementation is inspired and thus borrows heavily from Ruby on Rails' ActiveRecord.
21We have tried to maintain their conventions while deviating mainly because of convenience or necessity.
22Of course, there are some differences which will be obvious to the user if they are familiar with rails.
23
24## Minimum Requirements ##
25
26- PHP 5.3+
27- PDO driver for your respective database
28
29## Supported Databases ##
30
31- MySQL
32- SQLite
33- PostgreSQL
34- Oracle
35
36# Features ##
37
38- Finder methods
39- Dynamic finder methods
40- Writer methods
41- Relationships
42- Validations
43- Callbacks
44- Serializations (json/xml)
45- Transactions
46- Support for multiple adapters
47- Miscellaneous options such as: aliased/protected/accessible attributes
48
49### Installation ##
50
51Setup is very easy and straight-forward. There are essentially only two configuration points you must concern yourself with:
52
531. Setting the model auto_load directory.
542. Configuring your database connections.
55
56Example:
57
58 ActiveRecord\Config::initialize(function($cfg)
59 {
60 $cfg->set_model_directory('/path/to/your/model_directory');
61 $cfg->set_connections(array('development' => 'mysql://username:password@localhost/database_name'));
62 });
63
64Alternatively (w/o the 5.3 closure):
65
66 $cfg = ActiveRecord\Config::instance();
67 $cfg->set_model_directory('/path/to/your/model_directory');
68 $cfg->set_connections(array('development' => 'mysql://username:password@localhost/database_name'));
69
70Once you have configured these two settings you are done. ActiveRecord takes care of the rest for you.
71It does not require that you map your table schema to yaml/xml files. It will query the database for this information and
72cache it so that it does not make multiple calls to the database for a single schema.
73
74## Basic CRUD ##
75
76### Retrieve ###
77These are your basic methods to find and retrieve records from your database.
78See the *Finders* section for more details.
79
80 $post = Post::find(1);
81 echo $post->title; # 'My first blog post!!'
82 echo $post->author_id; # 5
83
84 # also the same since it is the first record in the db
85 $post = Post::first();
86
87 # finding using dynamic finders
88 $post = Post::find_by_name('The Decider');
89 $post = Post::find_by_name_and_id('The Bridge Builder',100);
90 $post = Post::find_by_name_or_id('The Bridge Builder',100);
91
92 # finding using a conditions array
93 $posts = Post::find('all',array('conditions' => array('name=? or id > ?','The Bridge Builder',100)));
94
95### Create ###
96Here we create a new post by instantiating a new object and then invoking the save() method.
97
98 $post = new Post();
99 $post->title = 'My first blog post!!';
100 $post->author_id = 5;
101 $post->save();
102 # INSERT INTO `posts` (title,author_id) VALUES('My first blog post!!', 5)
103
104### Update ###
105To update you would just need to find a record first and then change one of its attributes.
106It keeps an array of attributes that are "dirty" (that have been modified) and so our
107sql will only update the fields modified.
108
109 $post = Post::find(1);
110 echo $post->title; # 'My first blog post!!'
111 $post->title = 'Some real title';
112 $post->save();
113 # UPDATE `posts` SET title='Some real title' WHERE id=1
114
115 $post->title = 'New real title';
116 $post->author_id = 1;
117 $post->save();
118 # UPDATE `posts` SET title='New real title', author_id=1 WHERE id=1
119
120### Delete ###
121Deleting a record will not *destroy* the object. This means that it will call sql to delete
122the record in your database but you can still use the object if you need to.
123
124 $post = Post::find(1);
125 $post->delete();
126 # DELETE FROM `posts` WHERE id=1
127 echo $post->title; # 'New real title'
128