Simple ORM is an object-relational mapper for PHP & MySQL (using mysqli). It provides a simple way to create, retrieve, update & delete records.
This is not intended for large scale projects as it has extra database interaction than necessary. I would suggest Doctrine for such things.
Simple ORM is a few years old but it has been upgraded over time, therefore PHP 5.3 is a requirement.
To utilise this tool you need to do a few things:
- Include the class file.
- Create a
mysqli
object. - Tell
SimpleOrm
to use themysqli
connection.
For example:
// Include the Simple ORM class
include 'SimpleOrm.class.php';
// Connect to the database using mysqli
$conn = new mysqli('host', 'user', 'password');
if ($conn->connect_error)
die(sprintf('Unable to connect to the database. %s', $conn->connect_error));
// Tell Simple ORM to use the connection you just created.
SimpleOrm::useConnection($conn, 'database');
Define an object that relates to a table.
class Blog extends SimpleOrm { }
Create an entry:
$entry = new Blog;
$entry->title = 'Hello';
$entry->body = 'World!';
$entry->save();
Retrieve a record by it's primary key:
$entry = Blog::retrieveByPK(1);
Retrieve a record using a column name:
$entry = Blog::retrieveByTitle('Hello', SimpleOrm::FETCH_ONE);
Update a record:
$entry->body = 'Mars!';
$entry->save();
Delete the record:
$entry->delete();
This section will detail how you define your objects and how they relate to your MySQL tables.
class Foo extends SimpleOrm {}
The following assumptions will be made for all objects:
- The database used is the database loaded in the
mysqli
object. - The table name is the class name in lower case.
- The primary key is
id
.
You can customise the assumptions listed above using the following static properties:
- database
- table
- pk
For example:
class Foo extends SimpleOrm
{
protected static
$database = 'test',
$table = 'foobar',
$pk = 'fooid';
}
This section will detail how you modify your records/objects.
You can start a new instance & save the object or you can feed it an array.
$foo = new Foo;
$foo->title = 'hi!';
$foo->save();
or
$foo = new Foo(array('title'=>'hi!'));
Simply modify any property on the object & use the save() method.
$foo->title = 'hi!';
$foo->save();
If you want to have some more control over manipulating data you can use set(), get() & isModified().
$foo->set('title', 'hi!');
$foo->save();
Use the delete() method.
$foo->delete();
This section will detail how you fetch data from mysql and boot your objects.
$foo = Foo::retrieveByPK(1);
or
$foo = new Foo(1);
$foo = Foo::retrieveByField('bar', SimpleOrm::FETCH_ONE);
By default, the retrieveBy* method will return an array of objects (SimpleOrm::FETCH_MANY).
$foo = Foo::all();
SimpleOrm::FETCH_ONE
will return a single object or null if the record is not found.
SimpleOrm::FETCH_MANY
will always return an array of hydrated objects.
You can pass in an associative array to populate an object. This saves retrieving a record each time from the database.
$foo = Foo::hydrate($array);
Any SQL statement can be used as long as all the returning data is for the object.
Example
$foo = Foo::sql("SELECT * FROM :table WHERE foo = 'bar'");
This will return an array of hydrated Foo objects.
If you only want a single entry to be returned you can request this.
$foo = Foo::sql("SELECT * FROM :table WHERE foo = 'bar'", SimpleOrm::FETCH_ONE);
The table name & primary key have shortcuts to save you writing the same names over & over in your SQL statements:
:database
will be replaced with the database name.:table
will be replaced with the table name.:pk
will be replaced with the primary key field name.
Any extra data that does not belong to object being loaded will have those fields populated in the object:
$foo = Foo::sql("SELECT *, 'hi' AS otherData FROM :table WHERE foo = 'bar'", SimpleOrm::FETCH_ONE);
echo $foo->otherData; // returns 'hi'
This can be useful if you plan to use aggregate functions within your object & you want to pre-load the data.
Input & output filters can be created to alter data going into the database & when it comes out.
To add a filter, you only need to create a method with either filterIn or filterOut as a prefix (e.g. filterIn, filterInHi, filterIn_hi).
These methods will automatically fire when data is loaded into the object (hydration) or saved into the database (save, update, insert).
Data being saved to the database can be modified.
For example:
class Foo extends SimpleOrm
{
protected function filterIn_dates ($data)
{
$data['updated_at'] = time();
return $data;
}
}
In the example above, every time the object is saved, the updated_at field is populated with a current time & date.
Note: You must return the input array otherwise no fields will be updated.
Any data loaded into the object will be passed through any output filters.
class Foo extends SimpleOrm
{
protected function filterOut ()
{
$this->foo = unserialize($this->foo);
}
}
In the example above, each time the object is hydrated, the foo property is unserialized.