5.3. Basic example

In this example we'll create the Model structures necessary to build a new blogging system from the ground up.

Step 1 - table creation

Our blog will use the following basic tables:

• blog - holds all the blogs that are managed on your system
• blog_entry - entries belonging to a blog
• comment - user comments attached to blog entries

By default Buan assumes that each table has a primary key called id which is a simple auto-incrementing integer. However, you can use any primary-key you wish by defining it in the $dbTablePrimaryKey class property.

Let's have a look at the SQL behind creating the tables in our example:

/* 'blog' */
CREATE TABLE blog (
	id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
	name VARCHAR(50)
)

/* 'blog_entry' */
CREATE TABLE blog_entry (
	id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
	blog_id INT UNSIGNED,
	title VARCHAR(100),
	body TEXT,
	datecreated DATETIME
)

/* 'comment' */
CREATE TABLE entry (
	id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
	blog_entry_id INT UNSIGNED,
	comment TEXT,
	datecreated DATETIME
)

Step 2 - create the Model classes

Each of the following files must now be created and saved in the folder defined in [app.dir.models]:

<?php
/* BlogModel.php */

class BlogModel extends Model {
	protected $dbTableName = 'blog';
}
?>

<?php
/* BlogEntryModel.php */

class BlogEntryModel extends Model {
	protected $dbTableName = 'blog_entry';
}
?>

<?php
/* CommentModel.php */

class CommentModel extends Model {
	protected $dbTableName = 'comment';
}
?>

Note that if you plan to follow Buan's recommended naming conventions for database tables, field names and class names, then you can ignore the table-definition line as Buan will work this out based on your Models' class names. For example, our Comment Model's class could be defined simply as:

<?php
/* Comment.php */

class Comment extends Model {
}
?>

Step 3 - define Model relationships

This is an important step in harnessing the full power of Buan's relational-modelling system. By using the ModelRelation class, we can build a detailed overview of how Models are related to each other.

The following definition can be added to the [app.configPath]/app.php script:

<?php
/* [app.dir.config]/app.php */
...
ModelRelation::define('Blog(1):BlogEntry(M)');		/* Define a 1:M relationship between Blog and BlogEntry */
ModelRelation::define('BlogEntry(1):Comment(M)');	/* Define a 1:M relationship between BlogEntry and Comment */
...
?>

Step 4 - using the Models

Here are some examples of common usage:

<?php
// Create a new blog
$blog = Model::create('Blog');
$blog->name = "My Blog!";

// Make a first entry
$entry = Model::create('BlogEntry');
$entry->title = "What did I do today?";
$entry->body = "Wrote a blog entry :)";
$entry->addRelatedModel($blog);

// Save
// This will actually save $blog too as we need $blog's primary key in order
// to use it in $entry's database record.
$entry->getModelManager->save($entry);

// Load all entries in another, previously saved blog
$blog = Model::create('Blog');
$blog->name = "SuperBlog";
if(!$blog->getModelManager()->loadByName($blog)) {
	// ...
}
$blog->loadRelatedModels('BlogEntry');
$entries = $blog->getRelatedModels('BlogEntry');
?>

There are/will be shortcuts to some of these functions as the framework develops, but these are the very basic controls available.