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!

My latest experiment is building a new site without leveraging one of the many MVC Frameworks that are out there today. I decided to approach a new project using the following criteria:

• Simple can be better sometimes.
• Frameworks don’t do EVERYTHING well.
• Components that do one job and do it well are easier.
• Easier can be more productive.

To be fair, my results were a mixed bag, but so far I’m happy with the experiment. The site is not open to the public yet, but you can check out the current version here if you are curious how it is going. Below is a brief out line of the tools I used and the results (good, bad and ugly)!

The Tools:

• Formed – Formed is a PHP HTML form generator class that I created and released into the public domain. It does one thing (render styled HTML forms using metadata and templates) and even though it is alpha right now it does it pretty well. The code still needs to be more defensive, but I’m pleased with the results. You can check it out and give it a try if you have a need. If you come up with interesting templates please share with them me and I’ll include them in the zip file.
• GluePHP – GluePHP is an excellent little PHP micro-framework that does one simple thing, it maps URL’s to Classes. It is a simple and elegant implementation of a front controller design pattern. Glue was created by Joe Topjian.
• Rain.TPL – Rain.TPL is an easy PHP template engine. Rain achieves ease of use by having only 8 Tags and 4 Methods. This was my first time using Rain and so far I’m very pleased. Rain is created and maintained by the Rain Team.
• 960 Grid System – A sensible and easy to use CSS framework. I’m a long time fan of this excellent work.
• RedBeanPHP – RedBean is an ORM that I keep coming back to because it is so darn easy to use. Foreign keys require more effort, but the ease of use is worth the effort.
• GUMP – GUMP is a class for PHP input validation by the folks at Wixel.net. It easy to use and has a good selection of basic validators. It makes a nice complement for Formed as opposed to including a validator in it myself.
• jQuery – The Javascript library. Write less, do more.
• Other bits or random code I created for the site. One stand out is Monster, the http cookie managing class.

The Results:

Let me start by saying that I do not intend to criticize anyone’s code. All of the solutions that I used did their job as advertised and did it well. What I’m providing is my perspective of how doing that job added to or detracted from the ease of creating my web application.

The Good:

GluePHP was a great front controller. It performed exactly as expected and did a really great job. It handled query string parameters via regular expressions and just plain worked. Rain.TPL was equally compelling. It was super easy to use, fast and did a great job helping me lay out templates. I did experience a problem with query string parameters buried in sensible URL’s without the ?, but it was user error. I’ll explain that more below. 960 Grid System continued to be a programmers friend as it is just so easy to use. I can’t say enough good things about that little CSS Framework.

The Not as Good:

RedBeanPHP is a solution that continues to vex me. I keep coming back to it because it is so darn cool, but it does have some limitations that are frustrating. RedBean excels at dehydrating and hydrating objects for easy database storage. What it does not excel at is referential integrity. I does not handle foreign keys. You can do it yourself, but this means managing decisions about cascading deletes on your own. The whole point of an ORM is hide all the mechanics of that from the programmer. RedBean does not quite see it that way. That’s why I contend that the ORM label is somewhat miss-leading. I expect my ORM to not create intersection tables by default for every join I ask it to make. RedBean does that. The lack of referential integrity is partially what leads to RedBean’s coolest feature, programming the DB on the fly in code rather than writing SQL. It’s that same lack of true ORM design time metadata that prevents it from building foreign keys. RedBean gives you tools to help with this, but eventually you realize that you are implementing those features yourself. For me the ORM of choice question is still outstanding, but if you need an object hydrator / dehydrator then you should look no further than RedBean. At that function it is the BOMB!

My understanding of the Rain.TPL was not as good as it should have been. I was having a problem with clean URL’s and the WYSIWYG features with Rain.TPL. I posted a question and the following Monday the Rain team provided a great answer. Unfortunately I wanted to plow ahead so I converted all my links with query strings to hidden form posts to overcome the issue. It worked and jQuery was excellent as usual in accomplishing this, but it was not an ideal solution. Having said that I still think Rain.TPL is the most compelling and easiest PHP template engine I’ve used to date.

The Bad:

The PHP Framework that I’ve used the most is Kohana. Right out of the gate I started missing some of the Kohana helper functions. I had to locate and update an older cookie management class that I re-dubbed Monster. That plus Formed and RedBean PHP helped me get the authentication working. Next as I tried to build CRUD operations I started writing my own “controllers” which were just objects that go called by the GluePHP class. This worked fine, but I quickly realized that I was lacking a model. Since I was trying to be fast I started adding the additional code around calls to RedBean to achieve more model like behavior from methods in my controller classes. This was a poor architecture, but it was better than writing my own models so that’s what I went with. This meant that the solution was not quite as structured as I would have preferred.

The Road Ahead

The project went fast enough and well enough that I think I’ll try it again. I have to say that next time I’ll be looking to find some new combinations that may suite my needs and programming practices better. I actually did recently create the Formed web site using GluePHP and Rain.TPL. They continue to work great for rapid site deployment. For that site I also deployed Alex Gorbatchev’s excellent Javascript tool SyntaxHighlighter. This allowed me to create a far more visually appealing and useful Tutorial for the Formed web site. It’s still pretty plain right now, but given that the whole site took just an hour or two to put together I’m very happy with the outcome.

Please allow me to introduce Formed, a simple PHP based HTML form generator class. The primary objectives I had when creating Formed were:

• Simple to Use
• Customizable using HTML formatting or CSS
• Self Contained (no framework dependencies)
• Template Support

I created a home site for it in the event that people wanted to try it, make suggestions (be nice), provide changes, that kind of thing. It is not on GitHub because it does not warrant that level of control at this point. The site is built on Joomla and the template is one of the defaults that I barely modified so it looks funny. If you go to the link above you can down load the zip file or read the tutorial. If you are interested check it out and post a comment here.

As a side note, PHP CMS tools must be in a tragic state these days. Joomla was easy enough to get working, but it is far from intuitive when you first use it. By contrast Drupal I could not even get working on Apache. To be fair I did not put much time into either one, but isn’t that the point of a CMS? It is a sorry state of affairs.

One thing I love about the open source community is all you need is another motivated, talented programmer with an opinion and change happens. I just found another new PHP Framework that has waded into the fray (at least from my perspective). It’s call DOOPHP and it has an interesting take on magic methods. The author’s contention on the about page is that magic methods rob frameworks of performance. I don’t know if that’s worth building a new solution over, but it could be worth a look. Enjoy.