FuzzyRecord documentation

Defining your models

To start using FuzzyRecord, you need to create some model classes. A model is a special type of class that represents one of the data objects in your application. For example, a content-managed website might have a 'Page' model, and a 'User' model.

An example model:

 
class Page extends FuzzyRecord {
 
  static protected $table = "page";
 
  static protected $properties = array(
    "id" => array("primary_key", "auto_increment"),
    "url" => array("url", "required"),
    "title" => array("min_length" => 2,"max_length" => 64,"required", 
                     "searchable", "like_searchable"),
    "body" => array("required", "searchable"),
    "section_id" => array("integer"),
    "author_id" => array("integer"),
    "position" => array("sorter" => array("section")),
    "is_live" => array("boolean"),
    "last_modified" => array("date_with_time", "order_by_default")
  );
 
  static protected $relationships = array(
    "belongs_to" => array(
      "section" => array("class" => "Section"),
      "author" => array("class" => "User")
    ),
    "has_many" => array(
      "tags" => array("class" => "Tag", "dependent" => "delete")
    )
  );
 
}

All models MUST define at least:

• The name of the database table that this model maps in the $table static variable
• A list of properties (the fields in the database table) in the $properties static variable

Optionally, models may define:

• A list of relationships with other models in the static $relationships variable
• Any other methods and properties you like, just like a normal class.

About Properties

The $properties variable is an associative array, where each key is the name of the property (and also the name of the field in the database table).

The value of a property will be another array, containing a range of keywords and associative arrays that define the behaviour of that property. Any keywords that are not recognised will be ignored. The array can contain a mix of any of the values in the two tables below.

Supported data-types

When specified for a particular property, these keywords define the type of data that will be stored.

Property constraints

When specified for a particular property, these keywords control how that property should behave.

$users = User::find("like" => "Ben%");

About relationships

The $relationships variable is an associative array that is only used when you want to create a relationship between two objects.

Currently, two types of relationships are supported: has_many and belongs to.

has_many relationships

These are used for describing one to many relationships between database tables. For example, a User has many UserLogins, a BlogEntry has many Comments.

belongs_to relationships

These are the inverse of the has_many relationship. For example, a BlogEntry has one User as the author.

Defining relationships

Generally, has_many and belongs_to are used in conjunction with each other. Let's see a simple example. First, a User model:

 
class User extends FuzzyRecord {
 
  static protected $table = "user";
 
  static protected $properties = array(
    "id" => array("primary_key","auto_increment"),
    "email" => array("email_address","required","unique","searchable"),
    "password" => array("password","required"),
    "name" => array("min_length" => 2,"max_length" => 16,),
  );
 
  static protected $relationships = array (
    "has_many" => array(
      "logins" => array("class" => "UserLogin", "dependent" => "delete")
    )
  );
 
}
 

Now, a UserLogin model:

 
class UserLogin extends FuzzyRecord {
 
  static protected $table = "user_login";
 
  static protected $properties = array(
    "id" => array("primary_key","auto_increment"),
    "user_id" => array("integer","required"),
    "ip_address" => array("max_length" => 32,"required"),
    "date" => array("date_with_time")
  );
 
  static protected $relationships = array(
    "belongs_to" => array(
      "user" => array("class" => "User")
    )
  );
 
}
 

Firstly, look at the $relationships variable in the User model. It defines a single has_many relationship, called 'logins'. It specifies the class of the model that this object is related to (UserLogin). "dependent" => "delete" means that all the UserLogins related to a User should be deleted when the User is deleted.

Now let's look at the UserLogin model. It specifies a single belongs_to relationship, called user, pointing to the User class. Notice that it also contains a 'user_id' field. This is where a reference to the user that logged in is actually stored in the database. The naming of this variable is important. It's name is the name of the belongs_to relationship (user), then an underscore, then the name of the primary key in the User model. It is important that you follow this naming convention in your models so that FuzzyRecord can automatically populate the value of this field, as we'll see below.

Let's see this relationship in action.

 
$user = new User();
$user->email = "ben@allseeing-i.com";
$user->password = "secret";
$user->name = "Ben";
$user->save();
 
$login = new UserLogin();
$login->ip_address = "127.0.0.1";
$login->date = "2009-01-01";
$login->user = $user; // <-- This is the key bit!
$login->save();
 

In this example, we set the 'user' property of the UserLogin instance. But UserLogin doesn't have a 'user' property!

UserLogin does have a 'user' relationship. FuzzyRecord recognises this, and hunts for a foreign key it can use to store the primary key of the user. Since we've named it correctly, it will use the 'user_id' field.

Continuing on from the previous example, we can now do:

 
echo $login->user_id // Will return the id of the user object we just created
echo $login->user // Will return the user object we just created
echo $login->user->email // Will return ben@allseeing-i.com
 

Generating your database from your models

Every model can generate the SQL needed to create its table in the database. Simply call:

User::create_table_sql();

A script to generate tables for all your models is included in the source code distribution for your convenience.

Sorter properties

A sorter is a special data type that allows you to easily model objects that have a position in relation to other objects. For example, if we had a TopStory model that was used to describe stories that might appear on the front page of a news website, the TopStory model might define a position attribute that allowed the editors to move TopStories up and down the page depending on which was most newsworthy at a particular time.

A sorter property stores an integer that represents the position of an object in relation to other objects of the same type. When you save a new instance of an object with a sorter property, the sorter property will be set to 1, and all other instances of the class will have their sorter property incremented by 1. You can then use the move_up() and move_down methods to move the objects position:

<?php
 
class TopStory extends FuzzyRecord {
 
  static protected $table = "top_story";
 
  static protected $properties = array(
    "id" => array("primary_key","auto_increment"),
    "url" => array("varchar"),
    "position" => array("sorter")
  );
}
 
$story1 = new TopStory();
$story1->headline = "Four thousand holes in Blackburn, Lancashire";
$story1->url = "/url-of-this-story";
$story1->save();
 
$story2 = new TopStory();
$story2->headline = "Elvis seen wandering campsite at night";
$story2->url = "/url-of-this-story";
$story2->save();
 
$story3 = new TopStory();
$story3->headline = "Starr: Super-smart alien hampsters want revenge";
$story3->url = "/url-of-this-story";
$story3->save();
 
echo $story1->position; //3
echo $story2->position; //2
echo $story3->position; //1
 
$story2->move_up();
 
echo $story1->position; //3
echo $story2->position; //1
echo $story3->position; //2
 
$story3->move_down();
 
echo $story1->position; //2
echo $story2->position; //1
echo $story3->position; //3
 
$story1->delete();
 
echo $story2->position; //1
echo $story3->position; //2
 
 

Specify a constraint for the sorter

If you define a constraint for a sorter property, instances will sort themselves only in relation to other items that match the constraint. For example:

<?php
class TopStory extends FuzzyRecord {
 
  static protected $table = "top_story";
 
  static protected $properties = array(
    "id" => array("primary_key","auto_increment"),
    "url" => array("varchar"),
    "category_id" => array("integer"),
    "position" => array("sorter" => array("category"))
  );
 
  static protected $relationships = array(
    "belongs_to" => array(
      "category" => array("class" => "TopStoryCategory")
    )
  );
}

In the above example, TopStory instances will sort themselves in relation to other TopStories in the same category.

File properties

File properties are used when you want to store data in a file on a local disk, rather than in the database. This is useful for storing binary data (for example, a photo uploaded by a user), or when you have a large amount of data that might slow down your database.

In the example below, we've added a file property (called file) to the Document model. File properties must define a 'save_path', this tells FuzzyRecord where to store the saved file.

<?php
 
define("DOCUMENT_SAVE_PATH","/home/ben/Sites/fuzzyrecord/htdocs/documents");
 
class Document extends FuzzyRecord {
 
	static protected $table = "document";
 
	static protected $properties = array(
		"id" => array("primary_key","auto_increment"),
		"file" => array("file","save_path" => DOCUMENT_SAVE_PATH),
		"last_modified" => array("date_with_time","order_by_default")
	);
}
 
$document = new Document();
$document->file = new File("/tmp/myfile.txt");
 
// File will be saved to:
// /home/ben/Sites/fuzzyrecord/htdocs/documents/myfile.txt
$document->save();
 
// In this example, assume the user uploaded a file called 'anotherfile.jpg'
$document = new Document();
$document->file = File::file_with_uploaded_file($_FILES["user_uploaded_file"]);
 
// File will be saved to:
// /home/ben/Sites/fuzzyrecord/htdocs/documents/anotherfile.jpg
$document->save();
 

We've used a constant for the path that Document files should be saved to. It would be best to define this in your global config file, so that you can change the path later easily.

Specifiying a custom file name for the saved file

To use a custom file name for the saved file, simply define a method named <property name>_file_name in your model. For example:

<?php
 
define("DOCUMENT_SAVE_PATH","/home/ben/Sites/fuzzyrecord/htdocs/documents");
 
class Document extends FuzzyRecord {
 
	static protected $table = "document";
 
	static protected $properties = array(
		"id" => array("primary_key","auto_increment"),
		"file" => array("file","save_path" => DOCUMENT_SAVE_PATH),
		"last_modified" => array("date_with_time","order_by_default")
	);
 
	public function file_file_name() {
		return $this->id.".jpg";
	}
}
 
$document = new Document();
$document->file = File::file_with_uploaded_file($_FILES["user_uploaded_file"]);
 
// File will be saved to:
// /home/ben/Sites/fuzzyrecord/htdocs/documents/6.jpg
// (where 6 is the id of the Document instance)
$document->save();