In a recent post I touted the coolness factor of the Spot ORM. Based on a response to that post I prepared this short tutorial on how to get started. This is culled from personal experience and guidance that I received from the software’s author. I hope this is helpful to you if you are interested in giving Spot a try.

First, download the code from github here and copy the included folder where it can be referenced by your project. I renamed my folder Spot and put it in the modules folder for my project. Your approach my vary.

Next we set up the Spot objects for use. Here is a MySql example.

1
2
3
4

require_once "modules/Spot/Config.php" ;
$cfg = new Spot\Config () ;
$adapter = $cfg->addConnection ('mysql', 'mysql://username:password@localhost/databasename') ;
$mapper = new Spot\Mapper ($cfg) ;

Right away you can see that Spot uses the namespace Spot. It’s a trivial observation, but it might save you a little frustration when you are just getting started. Next we need to define our entity. Spot is based on the Data Mapper design pattern so the Entity is sort of a dumb object, but we need to define it anyway. Here is a basic entity example.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

/*
	Author Mapper
*/
class Authors extends Spot\Entity
{
    // Specify the data source (table for SQL adapters)
    protected static $_datasource = "authors";
 
    // Define your fields as public class properties
	public static function fields ()
	{
		return array
		(
			'id' => array ('type' => 'int', 'primary' => true, 'serial' => true),
			'firstname' => array ('type' => 'string', 'required' => true),
			'lastname' => array ('type' => 'string', 'required' => true),
			'sex' => array ('type' => 'string')
		) ;
	}
 
	public static function relations ()
	{
		// Authors Relationship
		return array
		(
			'books' => array 
			(
				'type' => 'HasMany', 
				'entity' => 'Books', 
				'where' => array ('author_id' => ':entity.id'),
				'order' => array ('title' => 'ASC')
			)
		) ;
	}
}

As you can see the Entity defines both the fields it cares about as well as foreign key related fields. The naming conventions are pretty standard. Note the $_datasource property which defines the actual data table where the entity is stored. I don’t think this is necessary in the above example, but I wanted to include it as a reference for how you might refer to an authors mapper where the table name was something other than authors. Also note the use of the singular author_id in the HasMany definition array. This is by convention. Now let’s use this Entity to do something useful. Let’s get a single author.

1
2
3
4
5

$author = $mapper->first ('Authors', array ('lastname' => $lastname)) ;
if ($author !== false)
{
	print $author->lastname . ", " . $author->firstname . "(" . $author->sex . ")</br>" ;
}

As you can see it is trivial to access the individual record retrieved from the DB. In this example there could be more than one authors with the same last name, but only the first one would be returned and acted upon. Now let’s create a new author entry.

1
2
3
4
5

$author = new Authors () ;
$author->firstname = "John" ;
$author->lastname = "Smith" ;
$author->sex = "Male" ;
$mapper->save ($author) ;

Again, pretty simple stuff. The Data Mapper pattern takes care of all the dirty translation into the underlying data store. You just work at the object level which is far more intuitive for a programmer. Updating the entity is just as easy. You simply retrieve the entity you want to update as shown above, assign new values to the properties you want to change and call the same save method on the mapper class. That’s it. It looks like this.

1
2
3

$author = $mapper-> first ("Authors", array ("firstname" => "John", "lastname" => "Smith")) ;
$author->sex = "Female" ;
$mapper->save ($author) ;

What is John up to anyway? Well, at least you get the idea. Deleting the record is just as easy. Here is an example.

1
2

$author = $mapper-> first ("Authors", array ("firstname" => "John", "lastname" => "Smith")) ;
$mapper->delete ($author) ;

That’s all there is to deleting. Now let’s look at some other useful commands. Here we select all entities matching a specific criteria and order the result.

1
2
3
4
5
6
7
8

$authors = $mapper->all ("Authors", array ("lastname" => $author_sirname, "sex" => "Male"))->order (array ("lastname" =>"desc")) ;
if (! $authors === false)
{
	foreach ($authors as $author)
	{
		// Do something
	}
}

Here is a more complicated example using where.

1
2
3

$authors = $mapper->all ("Authors", array ("id" => 15))
	->where (array ("lastname :like" => $sirname, "firstname :like" => $name), "OR", "AND")
	->order (array ("lastname" =>"desc")) ;

Shifting examples a bit here, below is an actual working example of a HasManyThrough relationship. In this example the Tags table is related to the Items table through the Items_Tags table.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

/*
	Tags Mapper
*/
class Tags extends Spot\Entity
{
	// Specify the data source (table for SQL adapters)
	protected static $_datasource = "tags";
 
	// Define your fields as public class properties
	public static function fields ()
	{
		return array
		(
			'id' => array ('type' => 'int', 'primary' => true, 'serial' => true),
			'name' => array ('type' => 'string', 'required' => true),
			'user_id' => array ('type' => 'int', 'index' => true, 'required' => true)
		) ;
	}
 
	// Items Relationship
	public static function relations ()
	{
		return array
		(
			'items' => array
			(
				'type' => 'HasManyThrough',
				'entity' => 'Items',
				'where' => array ('id' => ':throughEntity.items_id'),
				'throughEntity' => 'Items_Tags',
				'throughWhere' => array ('tags_id' => ':entity.id'),
				'order' => array ('created_on' => 'desc')
			)
		) ;
	}
}

Based on this example we can select all Items associated with a group of tags. Two things to note about the example below. First, the user_id is another relation of a tag to a user which is defined in the tag’s entity. Second, the nested foreach behavior is (I think, but I can’t recall for certain) an implementation of lazy loading of the associated item records for the tags.

1
2
3
4
5
6
7
8
9
10
11
12
13

$tags = $mapper->all ('Tags', array ('id' => (int) $tag, 'user_id' => (int) config::$id)) ;
if (! $tags === false)
{
	$buffer = "" ;
	foreach ($tags as $tag)
	{
		foreach ($tag->items as $item)
		{
			$buffer .= $item->something_useful ;
		}
	}
	return $buffer ;
}

So that’s it. A quick and easy introduction to the basic use of Spot. If you are interested then let Vance Lucas (the author) know and hopefully he’ll put more time into developing the code and the documentation into an even more accessible ORM than it already is. Thanks for your interest and good luck with Spot.

No, this is not about Doctrine and Propel, although I’m sure those are both really fine PHP ORM tools if you are willing to endure the learning curve. This is about 2 lesser known but notable ORM tools that deserve a nod of recognition. I’ve tried a number of PHP ORM tools over the last year and many of them had merit. In fairness, as you look at one attempt you begin to realize how much each of them owes to those that came before them. There are so many variations on a theme that you can easily get confused and give up in frustration. But my recent efforts have revealed two that I find very useful and note worthy depending on your project. Here is a quick run down on each.

Spot

Spot is the second attempt at a Data Mapper ORM implementation for PHP by Vance Lucas. Vance’s first attempt was titled PHPDataMapper a was and nifty attempt in it’s own right. Vance took what he learned and created Spot, the 2.0 implementation of his original ORM. Spot has straight forward configuration through object inheritance and is very easy to use once you get the hang of it. Spot supports HasOne, HasMany and HasManyThrough relationships. It solves the Lazy Loading problem and is hands down the best implementation of association management through an ORM model that I’ve encountered. The available documentation is spartan right now (I’m being kind), but Vance was kind enough to give me the few pointers I needed to get working quickly. If anyone is interested let me know and I can provide some demo code in a separate post.

Given how much I have enjoyed using Spot, I have only one minor quibble. As I looked at the implementation, I could not find a way to build Models dynamically at run time rather than pre-define them. Granted this is not a problem for many projects, but it was an issue for the last thing I was doing. Having said that if I do any PHP projects in the future with static data models then I’ll be using Spot to do them. If you have a similar need and value power and simplicity then I encourage you to give Spot a go!

RedBeanORM

RedBeanORM is the marvelous dynamic ORM by Gabor de Mooij. For anyone who has read my blog you probably know that I have an on-going love / hate relationship with RedBean. This ORM is crazy easy to use as it builds the data tables and relationships on the fly as you run your program. The ORM picks the most appropriate type for your data items and adds any fields that are missing to the table. It even builds associations through intersection tables. It is such a cool concept that I am constantly drawn to it. That is except for the fact that it builds associations through INTERSECTION TABLES! I was never a fan of this and I posted in the forum that using only intersection tables was overkill for many common relational models.

After much waiting I’m happy to report that as of version 2.0 Gabor has added N:1 relationship support that implements a foreign key! It’s like mana from digital heaven! The implementation is not as user friendly as Spot (I have to do some of the work myself, gasp!), but it does go a long way towards making the resulting data model more practical for larger relational problems. This coupled with the dynamic nature of RedBeanORM make it a very compelling tool. For my dynamic model science project I’m going to use RedBean. I’m not sure where it will end up, but I’m excited to jump in and give it another try!

So there you have it. A tale of two PHP ORM’s that deserve a little recognition for their authors’ hard work and vision to make something better than what was there before. It is the true spirit of open source and I salute both of them for doing such a great job. I’m excited about ORM tools again, and that’s saying something!

I’m not an active Python developer at the moment, but I have been searching far and wide on the web for ORM solutions that might interest me. One Python based ORM which struck me as really interesting is SQLAlchemy. If you are interested in trying an ORM tool and you read the description on SQLAlchemy’s home page you would swear you had died and gone to ORM heaven! If this solution actually accomplishes what it claims then it could be a very interesting choice. I did not find a PHP port so I’ll have to keep looking for another PHP ORM that I’m interested in trying. Sigh.

Object Relational Mapping (ORM) tools allow developers to interact with databases through objects. The basic object in the typical solution is the model. The model is essentially an object representation of a single table in the database. In fact, implementations that subscribe to the activerecord design pattern will often view the model as an object representation of a single row of a specific table. Since the target data store in most cases is an RDBMS (excluding the recent surge in distributed Document based DB’s) the typical ORM needs some way to represent foreign key relationships in an object oriented way. To facilitate this the field has evolved a set of conventions or names for foreign key (FK) relationships in the DB based on the object’s (table’s) role in the given index. Here is a brief but hopefully useful explanation of four relationship types.

• Belongs-To – This is the most basic form of a FK representation in an ORM. A field in a model is designated as type Belongs To when that field has is a FK that references the primary key (PK) in another model (table). I say model since the Belongs To is used to describe the behavior of one model that contains a FK index in relation to another model that is the target of that FK index. The typical default behavior would be for the field to be named by using the target model’s name joined to the target model’s PK field name by an underscore such as author_id. The assumption in this example being that the author table would have a PK field named id.
• Has-One – This is the other side of the Belongs-To convention. This tells the model that another model is using this models PK as the target for its FK. The model can use this relationship to manage cascading deletes, joined selections, etc. The implication is that the model expects there to be one and only one FK in the remote model (table) attached to each record in this model (table).
• Has-Many – This is the same as Has-One except now the model expects there to be one or more FK’s in the remote model (table) attached to each record in this model (table).
• Many-To-Many – Although you might assume this is similar to Has-Many, it is actually more akin to Belongs-To. This convention represents a FK relationship from this model (as with Belongs To) to an intersection table that in turn joins it to another model. The typical implementation contains a Through property that defines the name of the intersection table. By default this table will typically be named by joining the name of each model (table) connected to it with an underscore character.

That is all there is to it. Although this is a simple explanation of these four relationship types, I think you can begin to see how the ORM will rely on each to execute desirable behaviors as you interact with your database through model objects. If you have any comments or corrections to the above please let me know.

jonathangeiger of the Kohana PHP Framework community has been working hard lately on a new ORM that shows promise. The github repository can be found here if you would like to check the code out. I decided to point my PHP Code Explorer at it to figure out the Jelly object model. Below is a screen capture of what I found. You can click the image to see a larger view.

I hope this view is helpful to you. I know it helped me to get a better perspective of Jelly and how it was designed.

Update: The official Jelly web site can be found at http://jelly.jonathan-geiger.com/.