Setting Up Models

Models are one of the three tiers of the MVC pattern. They are used to define an application's interaction with the database.

PHP Wax takes care of saving your models to the database with as little hassle as possible, it can also handle different types of joins between database tables, later when we cover the more advanced functionality you'll see how models can also handle validation too.

Setting up Models and Defining Fields

Here's an example of how a model is setup, this model handles a user table in the database. Ordinarily you'll make a new file in your app/model folder called User.php to make use of PHP Wax's automatic include feature you'll need to make sure that the filename is the same as the class name, so a class of User gets saved in User.php, a class of MySiteUser would go in a file called MySiteUser.php

<?php
class User extends WaxModel {  

public function setup() {
  $this->define("name", "CharField");
  $this->define("email", "CharField");
	$this->define("username", "CharField", array("required"=>true));
	$this->define("password", "PasswordField");
	$this->define("twitter", "CharField");
	$this->define("flickr", "CharField");
}
  	
}
?>;

How to Define Fields

As you can see in the code example above all of the model's definition gets done in a special method, 'setup'. A call to this->define can take three arguments, firstly the name of the field, the second is the type of field and the third is an array of options that customises the database and validation behaviour.

PHP Wax has quite a few built in field types, the second argument refers to a class which handles the behaviour. As you can see in the example above the most often used value is CharField this is the database equivalent of varchar and is used for short textual values, normally that require fewer than 255 characters.

The other built in field options are:

Of course since these map to class names you can add your own field type as well if you need any custom functionality that the built in ones don't provide.

For now we'll focus on basic usage of models but we'll go into the more fine grained configuration in another tutorial.

As you can see the third value that is passed into the define call is an array of options. This value is optional so for now we'll use the 'out of the box' functionality to get started.

Using Your Model to Write to and Query the Database

Luckily you've done all the hard work now and reading from and writing to the database is a doddle. Let's make a new user in our database.

$user = new User;
$user->username = "fred";
$user->name = "Fred Bloggs";
$user->email = "fred@example.com";
$user->save();

Jump into your database and you'll see, as if by magic, that you now have a new row in the database.

Now we need to get our record out of the database and add his Twitter username.

$user = new User;
$fred = $user->filter("username", "fred")->first();
$fred->twitter = "fredbloggs";
$fred->save();

Using Results in Views

Say that instead of just editing Freds data you want to be able to see all users in the database and be able to edit them, for this you will need more than one action in your controller.

In your default controller - /app/controller/PageController.php - create a new action called user_list: 

public function user_list(){
  $model = new User;
  $this->all_users = $model->all();
}

Assigning the results from the model call to a $this variable means they are accessible inside your views. This is the key to editing data.

As we plan on using a url like http://my.site.local/user-list the view we make will be app/view/page/user-list.html.

This list will look a bit like this:

<?if($all_users &&; $all_users->count()):?>
  <?foreach($all_users as $user):?>
  <div class="list_item">
    <h3><?=$user->name?></h3>
    <p><a href="/user-edit/<?=$user->primval?>">edit</a></p>
  </div>
  <?endforeach?>  
<?else:?>
<p>No users found, sorry!</p>
<?endif?>

To start with we make sure that $all_users is valid, by checking it is true and has a countable value. This way you wont loop over an empty set of results and can provide the user with feedback if none are found.

As result sets implement the iterator interface we can use them in a various loops.

Notice the use of $user->primval. This is a function on the model to return its primary key, so even if each of your model classes have different primary key fields this will return the correct value.

To see how to edit and save details please take a look at the forms page.