PHP-WAX Controllers

How the controller works

The controller is one of the three core strands of the MVC Pattern. It is in charge of collecting data from the model or database tables and sending the relevant information to the view.

An application will contain at least one controller. The typical way of designing an application is to have one controller for each model or each table of your database. This is not always the case though so by default all models are available to all controllers.

All controllers will by default extend ApplicationController. This is an empty controller by default, but adding methods to this file allows you to provide functionality to the entire application.

The basic controller setup

In its most simple case a controller will start like the following:

 Class PageCoontroller extends ApplicationController
 {
 
 }

This would then be saved as PageController.php and placed in the /app/controller directory.

Adding actions to a controller

Supposing that you have not setup any custom routes or default routes entering, http://yourapp.com/page/ would load this controller file. The first thing the application does is to look for actions. Actions are the second part of the url, in this case we haven't given an action so by default the framework would look for an action called index. The basic controller above does not have any actions defined so this would trigger an error.

We can add a default action as below:

 Class PageController extends ApplicationController
 {
   function index(){}
 }

That is all that is needed to prevent the missing action error. Whilst this is not a useful action it would work for a page that required no access to the database and just served a static view.

Accessing the model

How to setup a model file is described on the wx.php Models page. Assuming this is setup then you need to instantiate a model into the controller file. Since the model is named after the table in the database, in this example our model would be called Page. Accessing it in the controller would look like the following....

 Class page_controller extends ControllerBase
 {
   function index()
   {
   $page=new Page();
   }
 }

Now we have an object called $page and we can perform many database functions inside the controller. Some of these are described in more detail on the wx.php Models page.

Passing Information to the View

The view is the third strand of the MVC Pattern. The whole purpose of the controller is to pass data to the view which can then be shown to the user. By default all class variables set in the controller are available to the view. Take the following example:

 Class page_controller extends ControllerBase
 {
   function index()
   {
   $this->message='hello';
   $this->message2='this has been sent to you from the controller';
   }
 }

Because they have been set as object variables (via $this->variable construct) the view will now be able to use these variables. Of course everything from simple strings, as above right through to arrays of database rows can be made available to the view. The only rule is that they have to be set as object variables, nothing else needs to be done, the application will automatically pass them on.

Built in object variables

The first built in variable is called route_array. Routes refer to the url that the user has entered. As discussed before the first part is the controller reference, the second part is the action reference. The remainder of the url is then passed into the route_array variable. This allows you to serve different content according to the url the user has requested. Note that this facility must be enabled first, by default the framework will throw an error if the url is not matched, however doing the following in the controller will allow you to access the route to the number of levels specified

 public $accept_routes=1;

For example if the user has entered http://yourapp.com/page/index/help the first part will load page_controller, the second part will run the action index and the final part will end up in the route_array array. Inside your index action you could read the first value of $this->route_array and set the class variables accordingly. More details and examples are available on the wx.php routes page.

The second built in object variable is a simple string variable that is accessed via $this->use_layout. The value of this array decides which layout file will be loaded. By default this is set to default and will therefore load the layout file named default.html. If you were to override this value by using -

$this->use_layout='page'

then the application would attempt to load the layout file page.html. More information about layouts and where to place layout files is available at the Wx.php Layouts page.

There is now also the opportunity to override the default view, simply by setting the $this->use_view variable. If this variable is not set, which will not be necessary in most cases, then the normal view will load as previously.

Controller Global Method

Finally there is a custom method called controller_global(). This is executed as part of the construction of the controller and can set any controller-wide features. An excellent use for this is to protect an entire controller using the Authorise functions which applies protection to every method inside that controller. Another example is shown below....

protected function controller_global(){
  $this->global_variable= "A value";
}

This example is used to add a variable to the layout. Instead of doing this inside each action however, the above will handle setting it automatically. A more useful application of this method would be to handle authorisation across an entire controller.