FuelPHP Application Development Blueprints

This is the simplest solution. You should be able to download it by requesting the URL http://fuelphp.com/files/download/28.

Alternatively, you can access all the compressed packages of important FuelPHP releases at http://fuelphp.com/docs/installation/download.html (It can be accessed through the FuelPHP website by navigating to DOCS | TABLE OF CONTENTS | FuelPHP | Installation | Download)

First, if you didn't do it yet, you need to install Composer. You can find out how by reading the official website at https://getcomposer.org/.

The installation instructions for major operating systems are given in the Getting Started guide. Please note that you can install Composer either globally or locally.

From now on, we will generally assume that you have installed Composer globally. If Composer is installed locally into your working directory, our instructions will work if you replace composer by php composer.phar.

In order to specifically install FuelPHP 1.7, you can simply execute the following command line (replace TARGET by the directory in which you want to download FuelPHP):

composer create-project fuel/fuel:dev-1.7/master TARGET

Assuming you have activated the mod_rewrite Apache module, the simplest way is to install FuelPHP in the root folder of your web server (generally the /var/www directory on Linux systems). If you install FuelPHP in the DIR directory of the root folder (/var/www/DIR), you will be able to access your project at the following URL:

http://localhost/DIR/public/

However, be warned that FuelPHP has not been implemented to support this, and if you publish your project this way in the production server, it will introduce security issues you will have to handle. In such cases, you are recommended to use the second way we will explain in the upcoming section, although, for instance if you plan to use a shared host to publish your project, you might not have the choice. A complete and up-to-date documentation about this issue can be found in the FuelPHP installation instruction page at http://fuelphp.com/docs/installation/instructions.html (It can be accessed through the FuelPHP website by navigating to DOCS | TABLE OF CONTENTS | FuelPHP | Installation | Instructions)

Another way is to create a virtual host to access your application. You will need a little bit more Apache and system administration skills, but the benefit is that it is more secure and you will be able to choose your working directory. You will need to change two files:

In both cases, the files' location will be dependent on your operating system and the server environment you are using; therefore, you will have to figure out their location yourself (if you are using a common configuration, you won't have any problem to finding instructions on your preferred search engine).

In the following example, we will set up your system to call your application when requesting the my.app URL on your local environment (*nix system recommended).

Let's first edit the virtual host file(s). Add the following code at the end:

<VirtualHost *:80>
    ServerName my.app
    DocumentRoot YOUR_APP_PATH/public
    SetEnv FUEL_ENV "development"
    <Directory YOUR_APP_PATH/public>
        DirectoryIndex index.php
        AllowOverride All
        Order allow,deny
        Allow from all
    </Directory>
</VirtualHost>

Then, open your system host file and add the following line at the end:

127.0.0.1 my.app

Depending on your environment, you might need to restart Apache after this. You can now access your website at: http://my.app/.

Congratulations! You just have successfully installed the FuelPHP framework. The welcome page shows some recommended directions to continue your project.

As written earlier, the app directory is where you will work most of the time. Thus, you should be familiar with its hierarchy, which is given as follows:

The fuel/packages directory contains five default packages that, when activated, can add interesting features to FuelPHP:

We will also create our own package in Chapter 4, Creating and Using Packages.

In FuelPHP, there are five constants that define the location of the most important directories as follows:

You are recommended to read the official documentation about these constants at http://fuelphp.com/docs/general/constants.html (It can be accessed through the FuelPHP website by navigating to DOCS | TABLE OF CONTENTS | FuelPHP | General | Constants)

Please keep in mind, that we will often use these constants in the book to shorten file paths.

An interesting point is that FuelPHP allows you to change quite easily the folder structure: for instance, you can change in the public/index.php file the value of the constants that we just introduced, or you can change the directory where FuelPHP will load modules by changing the module_paths key in the APPPATH/config/config.php configuration file.

You might also have noticed that class names are related to their own path, as given in the following:

This result was not achieved by accident; FuelPHP follows by default the PSR-0 standard. You are recommended to read the official documentation about this standard at http://www.php-fig.org/psr/psr-0/.

Model-view-controller (MVC) is a software architecture pattern that states that the code should be separated in three categories: models, views, and controllers.

For those who are not familiar with it, let's illustrate this through an example:

Suppose a user tries to access your website. The following are some URLs he/she might request:

http://my.app/

http://my.app/welcome/

http://my.app/welcome/hello

Depending on the requested URL, your website is generally expected to return some HTML code and it also sometimes needs to update the database, for instance when you want to save the users' comments.

The returned HTML code is generated by the views, because this is what is received by the browser and indirectly seen by the user.

The database is generally updated through models. In concrete terms, instead of executing raw SQL code to access and update the database, the best practice is to use classes and instances to do so. Each class represents a model that is related to a specific table: for example, the car model would access the cars table. Each class' instance is a model instance linked to a specific row in a table: for example, your car's information can be saved as a car instance that will be linked to a specific row in the cars table. As we use classes instead of raw SQL code, the framework has already implemented frequently needed features such as reading, creating, saving, or deleting model's instances. A further advantage is that, as we used packaged and well-implemented methods to access our database, it can prevent most unintended security breaches that we can create when requesting the database using raw SQL.

The controllers allow the website to handle the user's request by selecting the correct view to send back (the response) and updating the database (through models) if necessary. Controllers handle a specific section of the website: for instance, the car controller will handle everything that is related to cars. Controllers are subdivided by actions that will handle specific features: for instance, the list action of the car controller will return a list of cars in HTML code. In practice, controllers are classes and actions are methods.

When the user requests a URL, the framework will select an action inside a controller to handle it. Those are generally chosen by convention; for instance, when requesting http://my.app/welcome/hello, the framework will choose the hello action inside the welcome controller. Sometimes, they can also be chosen using a routes configuration file that matches URLs to actions and controllers.

The views sometimes need to access models; for example, we need to access the car model's instances when we want to display a list of cars. However, views should never update models or the database; only the controllers and preferably models should do that.

Please note that additional code components as helpers or presenters can be added to ease the development process, but if you understood this section, you got the most important points.

Let's illustrate how it works by testing our newly created website. We suppose that your application is available at the following URL:

http://my.app/

//...
class Controller_Welcome extends Controller
{
    //...
    public function action_index()
    {
        //...
    }
    
    //...
    public function action_hello()
    {
        //...
    }
    //...
}

public function action_index()
{
  echo 'Test 1 - Please never print anything inside an action';
  //...
}

public function action_index()
{
  return Response::forge(View::forge('welcome/index'));
}

public function action_index($name = 'user', $id = 0)
{
    return Response::forge(
        View::forge(
            'welcome/index',
            array(
                'name' => $name,
                'id' => $id,
            )
        )
    );
}

<h1>Welcome!</h1>

<h1>Welcome <?php echo ($name.' (id: '.$id.')'); ?>!</h1>

View::forge('welcome/index')

View::forge('welcome/index', array(
        'name' => $name,
        'id' => $id,
    )
)

View::forge('YOUR_VIEW', array(
        'param_1' => 1,
        'param_2' => 2,
    )
)

<?php
return array(
  '_root_'  => 'welcome/index',  // The default route
  '_404_'   => 'welcome/404',    // The main 404 route
  
  'hello(/:name)?' => array('welcome/hello', 'name' => 'hello'),
);

'my/welcome/page'  => 'welcome/index',

public function action_hello()
{
   return Response::forge(Presenter::forge('welcome/hello'));
}

<h1>Hello, <?php echo $name; ?>!

class Presenter_Welcome_Hello extends Presenter
{
    //...
    public function view()
    {
        $this->name = $this->request()->param('name', 'World');
    }
}

FuelPHP is a Hierarchical Model-View-Controller (HMVC) framework, meaning that it allows you to request internal controllers from your application. In concrete terms, the following code:

echo Request::forge('welcome/index')->execute();

will print exactly what the following URL would return:

http://my.app/welcome/index

Though we suggest you to use this feature in moderation, it can come handy when you want to implement and display widgets on several web pages.

You are recommended to read the following resources if you want to learn more about this pattern:

http://en.wikipedia.org/wiki/Hierarchical_model-view-controller

http://stackoverflow.com/questions/2263416/what-is-the-hmvc-pattern

During the previous section, two small issues bothered us for the monkey's listing:

We know that the list appears when requesting the following URL:

http://my.app/monkey

You have probably noticed that in this URL we indicated a controller, but no action. It is important to know that, by default and without any routing configuration involved, this URL is equivalent to http://my.app/monkey/index

So, in fact, we are calling the index action of the monkey controller. If we open the generated controller at APPPATH/classes/controller/monkey.php, we will read the following:

<?php
class Controller_Monkey extends Controller_Template{
    //...
}

First, you can notice that Controller_Monkey extends Controller_Template instead of Controller, as we saw before in Controller_Welcome. Controller_Template is an extension of Controller that adds template support. The idea is that most of the time your web pages will have the same layout: the headers, footers, and menus generally stay the same, regardless of the web pages you are in. Templates allow you to achieve this by limiting the code duplication.

By default, Controller_Template is associated with the APPPATH/views/template.php template that was generated by oil. If you open this file, you will see that it generates the HTML code around the page content. You will also probably notice that it prints the $title and $content variables. We will find out how to set their values by exploring the index action. If you go back to the Monkey controller, the action_index method should contain the following:

public function action_index()
{
    $data['monkeys'] = Model_Monkey::find_all();
    $this->template->title = "Monkeys";
    $this->template->content = View::forge('monkey/index', $data);
}

The first line stores all the monkeys' instances into the $data['monkeys'] variable. In a general manner, MODEL::find_all() returns all a model's instances, but it is definitely not the only method that retrieve instances. These methods will be discussed more thoroughly in Chapter 2, Building a To-do List Application.

The second and third lines set the $title and $content variables displayed in the template file. If you change the second line by $this->template->title = "My monkeys"; and then refresh the web page, you will see that its title has changed accordingly.

The third line sets the $content variable to a view instance that, from what we have observed in the previous sections, executes the view file located at APPPATH/views/monkey/index.php with the $monkey variable set to all monkeys' instances. Let's open this view file. You should see the following:

<h2>Listing Monkeys</h2>
<br>
<?php if ($monkeys): ?>
<table class="table table-striped">
  <thead>
    <tr>
      <th>Name</th>
      <th>Still here</th>
      <th>Height</th>
      <th>Description</th>
    
  <th></th>
    </tr>
  </thead>
  <tbody>
<?php foreach ($monkeys as $item): ?>    <tr>

      <td><?php echo $item->name; ?></td>
      <td><?php echo $item->still_here; ?></td>
      <td><?php echo $item->height; ?></td>
      <td><?php echo $item->description; ?></td>
      <td>
        <?php /* Action buttons */ ?>

      </td>
    </tr>
<?php endforeach; ?>  </tbody>
</table>

<?php else: ?>
<p>No Monkeys.</p>

<?php endif; ?><p>
  <?php /* Add new Monkey button */ ?>

</p>

We have found where the table is displayed, so it is time to make our changes.

First, remove the Description column by removing the following:

<th>Description</th>

and

<td><?php echo $item->description; ?></td>

Then, let's refine how the Still here attribute is displayed by replacing the following:

<td><?php echo $item->still_here; ?></td>

by

<td><?php echo $item->still_here ? 'Yes' : 'No'; ?></td>

The Still here column should now display Yes and No instead of 1 and 0, respectively.

On the list, when clicking on an item's View link, a detailed view of the monkey appears. We would like to change two details here:

First, if you are on a detailed view page, you can notice that the URL is similar to http://my.app/monkey/view/1

This means we are calling the view action of the monkey controller with the first and only parameter set to 1. The view action is quite similar to the index action, as you can see in the following snippet:

public function action_view($id = null)
{
    is_null($id) and Response::redirect('monkey');

    $data['monkey'] = Model_Monkey::find_by_pk($id);

    $this->template->title = "Monkey";
    $this->template->content = View::forge('monkey/view', $data);
}

The first line simply checks if the parameter of the action (associated to the $id variable) is actually set, and otherwise redirects the user (using the Response::redirect method) to the listing page.

The second line stores the monkey with ID $id into the $data['monkey'] variable. The find_by_pk (pk for primary key) method of a model finds one of its instances by its primary key. As we explained earlier, models' methods will be discussed more thoroughly in Chapter 2, Building a To-do List Application.

The third and fourth lines, as in the previous section, set the template variables. The template content is set to the view located at APPPATH/views/monkey/view.php.

<h2>Viewing #<?php echo $monkey->id; ?></h2>

<p>
  <strong>Name:</strong>
  <?php echo $monkey->name; ?></p>
<p>
  <strong>Still here:</strong>
  <?php echo $monkey->still_here; ?></p>
<p>
  <strong>Height:</strong>
  <?php echo $monkey->height; ?></p>
<p>
  <strong>Description:</strong>
  <?php echo $monkey->description; ?></p>

<?php /* Edit button */ ?> |
<?php /* Back button */ ?>

It is time to do some changes.

Replace:

<?php echo $monkey->still_here; ?>

By:

<?php echo $monkey->still_here ? 'Yes' : 'No'; ?>

And replace:

<?php echo $monkey->description; ?>

By:

<div><?php echo nl2br($monkey->description); ?></div>

One of the issues we pointed out previously, is that the description field is required, though we want to be able to enter an empty value.

First, open your browser and request the following URL:

http://my.app/monkey

Click on the Add a new Monkey button, and you can see you are redirected to http://my.app/monkey/create

If you take a look at the page source, you will find that the form's action attribute is actually the same URL:

<form class="form-horizontal" action="http://my.app/monkey/create" accept-charset="utf-8" method="post">

It means that whether we are opening the monkey's creation form or submitting it, we will always call the create action of the monkey controller. We should then read how this action is implemented:

public function action_create()
{
    if (Input::method() == 'POST')
    {
        $val = Model_Monkey::validate('create');
        
        if ($val->run())
        {
            // Saves the model (out of this chapter scope)
        }
        else
        {
            Session::set_flash('error', $val->error());
        }
    }

    $this->template->title = "Monkeys";
    $this->template->content = View::forge('monkey/create');

}

As you can notice, the action is able to know whether or not it is accessed through a POST request by using Input::method(). You are recommended to take a look at the official documentation of the Input class at http://fuelphp.com/docs/classes/input.html (It can be accessed through the FuelPHP website by navigating to DOCS | TABLE OF CONTENTS | Core | Input)

Model_Monkey::validate('create') returns an object that seems to define whether or not the object can be saved (depending on what $val->run() returns). This is a method from the Monkey model, so we should look into it. Open APPPATH/classes/model/monkey.php:

<?php
class Model_Monkey extends Model_Crud
{
    protected static $_table_name = 'monkeys';
    
    public static function validate($factory)
    {
        $val = Validation::forge($factory);
        $val->add_field('name', 'Name', 'required|max_length[255]');
        $val->add_field('still_here', 'Still Here', 'required');
        $val->add_field('height', 'Height', 'required');
        $val->add_field('description', 'Description', 'required');

        return $val;
    }

}

The file contains the Model_Monkey class that extends Model_Crud and allows us to handle the monkey instances.

First, you can notice the $_table_name static attribute that defines the table name where the objects are saved (here, all our monkeys are saved into the monkeys table).

And then there is the validate static method we are looking for. It returns a Validation object, that in our case will check that:

For more detail about this class, you are recommended to read the official documentation at http://fuelphp.com/docs/classes/validation/validation.html (It can be accessed through the FuelPHP website by navigating to DOCS | TABLE OF CONTENTS | Core | Validation | Introduction)

In our case, simply comment or remove the following line:

$val->add_field('description', 'Description', 'required');

It is now easy to check if the height is a float. As we know that monkeys are generally not taller than 4 feet, we can even add a numerical constraint. In the validate method of Model_Monkey, replace the following line:

$val->add_field('height', 'Height', 'required');

by

$val->add_field(
    'height',
    'Height',
    'required|numeric_between[0,6]'
);

This change will be a bit more complex. First, still in the validate method of Model_Monkey, remove the following line as we won't need this validation:

$val->add_field('still_here', 'Still Here', 'required');

Now, if you go back to our create action in Controller_Monkey (located at APPPATH/classes/controller/monkey.php), you will see that the template content is set to the view located at APPPATH/views/monkey/create.php. If you look at the file content, it is pretty simple:

<h2>New Monkey</h2>
<br>

<?php echo render('monkey/_form'); ?>

<p><?php echo Html::anchor('monkey', 'Back'); ?></p>

For your information, the render method is an alias of View::render, and in this case equivalent to View::forge. This illustrates that it is possible to render views inside other views. It can be convenient to prevent code repetition; the view located at APPPATH/views/monkey/edit.php also renders the same view (monkey/_form), and this makes sense since the forms displayed are exactly the same, whether you create a new monkey or edit an existing one.

Since we want to edit the form to replace the still_here input by a checkbox, open the view located at APPPATH/views/monkey/_form.php and replace the following lines:

<?php 
echo Form::input(
    'still_here',
    Input::post(
        'still_here',
        isset($monkey) ? $monkey->still_here : ''
    ),
    array(
        'class' => 'col-md-4 form-control',
        'placeholder' => 'Still here'
    )
);
?>

By

<?php
echo Form::checkbox(
    'still_here',
    1,
    Input::post(
        'still_here',
        isset($monkey) ? $monkey->still_here : true
    )
);
?>

Finally, you are probably aware that the still_here POST attribute won't be defined if the checkbox is unchecked when submitting the form. Thus, we need to define a default value when retrieving the still_here POST attribute, not only in the create action but also in the edit action. In both the methods, replace the following:

Input::post('still_here')

by

Input::post('still_here', 0)

Last but not least, we don't want to display FuelPHP's welcome screen when requesting the root URL, but instead the monkeys' listing. For doing that we will have to change the routes' configuration file located at APPPATH/config/routes.php.

Replace:

'_root_'  => 'welcome/index',

By:

'_root_'  => 'monkey/index',

When requesting:

http://my.app/

You should now see your monkey listing.

Now that our project is working as intended, it might be a good idea to clean it: