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.

I have updated Formed, my PHP HTML Form Generator, to provide support for errors. The functionality is there, but I have not updated the tutorial yet to cover error handling. Setting errors is actually as easy as calling the set_errors method of the Formed object and telling it what errors you want to set. Below is a simple example:

1

$myForm->set_errors (array ("Comment" => array ("You must provide a comment!", "The comment field must be at least 10 characters!"))) ;

This example shows setting 2 different error messages for the comments field element. That’s all there is to it. The DefaultTemplate and the black_and_white template were updated to incorporate the tags needed for processing errors. The others will be updated as time permits. You can make the edits yourself if needed sooner by following the example in black_and_white. I’m excited about this new feature and I have already used the functionality in my Your Brain site.

On a related note I always like to give a shout out where it is warranted. Although I have not used it, the PHPForms product looks pretty nice if you need to render static HTML forms. Although this is not the goal of Formed, I still think their form builder implementation is intuitive and well done. If you need to develop static forms you should give them a look. If you need to generate dynamic forms in your code then Formed may be more appropriate for your project.

It’s been a while since I posted about this and as I look for sliders I thought I would update you on some additional cool jQuery Plugins that I’ve come across. Enjoy!

• Nivo Slider – The worlds’ most awesome jQuery slider.
• arbor.js – a graph visualization library using web workers and jQuery
• Awkard Showcase – They call it a Content Slider, but as they state it can do more then just slide the content with tooltips, thumbnails, dynamic height and lots more.
• Nice & Clean Sliding Login Panel – Nice & Clean Sliding Login Panel Built With JQuery.

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!

At work lately I’ve been encountering a lot of Business Process Management or BPM tools in disguise. It got me to wondering if the open source community is active in this area. I found this blog post which suggests maybe. These do appear to be mostly free, but they have commercial companies around them which always complicates the issue.

Today my colleague pointed out a commercial RAD tool that was very promising. It’s called outsystems Agility Platform and it is worth a look if you are in the market for this kind of solution.

What does all this mean? Nothing maybe. Eventually it could spell the end to the software engineering profession as it exists today. I doubt that will be tomorrow, but it could happen. Wouldn’t that make for an interesting world?