In this article by Sébastien Drouyer, author of the book FuelPHP Application Development Blueprints we will see that FuelPHP is an open source PHP framework using the latest technologies. Its large community regularly creates and improves packages and extensions, and the framework’s core is constantly evolving. As a result, FuelPHP is a very complete solution for developing web applications.

(For more resources related to this topic, see here.)

In this article, we will also see how easy it is for developers to create their first website using the PHP oil utility.

The target application

Suppose you are a zoo manager and you want to keep track of the monkeys you are looking after. For each monkey, you want to save:

• Its name
• If it is still in the zoo
• Its height
• A description input where you can enter custom information

You want a very simple interface with five major features. You want to be able to:

• Create new monkeys
• Edit existing ones
• List all monkeys
• View a detailed file for each monkey
• Delete monkeys

These preceding five major features, very common in computer applications, are part of the Create, Read, Update and Delete (CRUD) basic operations.

Installing the environment

The FuelPHP framework needs the three following components:

• Webserver: The most common solution is Apache
• PHP interpreter: The 5.3 version or above
• Database: We will use the most popular one, MySQL

The installation and configuration procedures of these components will depend on the operating system you use. We will provide here some directions to get you started in case you are not used to install your development environment. Please note though that these are very generic guidelines. Feel free to search the web for more information, as there are countless resources on the topic.

Windows

A complete and very popular solution is to install WAMP. This will install Apache, MySQL and PHP, in other words everything you need to get started. It can be accessed at the following URL:

http://www.wampserver.com/en/

Mac

PHP and Apache are generally installed on the latest version of the OS, so you just have to install MySQL. To do that, you are recommended to read the official documentation:

http://dev.mysql.com/doc/refman/5.1/en/macosx-installation.html

A very convenient solution for those of you who have the least system administration skills is to install MAMP, the equivalent of WAMP but for the Mac operating system. It can be downloaded through the following URL:

http://www.mamp.info/en/downloads/

Ubuntu

As this is the most popular Linux distribution, we will limit our instructions to Ubuntu.

You can install a complete environment by executing the following command lines:

# Apache, MySQL, PHP
sudo apt-get install lamp-server^
 
# PHPMyAdmin allows you to handle the administration of MySQL DB
sudo apt-get install phpmyadmin
 
# Curl is useful for doing web requests
sudo apt-get install curl libcurl3 libcurl3-dev php5-curl 
 
# Enabling the rewrite module as it is needed by FuelPHP
sudo a2enmod rewrite 
 
# Restarting Apache to apply the new configuration
sudo service apache2 restart

Getting the FuelPHP framework

There are four common ways to download FuelPHP:

• Downloading and unzipping the compressed package which can be found on the FuelPHP website.
• Executing the FuelPHP quick command-line installer.
• Downloading and installing FuelPHP using Composer.
• Cloning the FuelPHP GitHub repository. It is a little bit more complicated but allows you to select exactly the version (or even the commit) you want to install.

The easiest way is to download and unzip the compressed package located at:

http://fuelphp.com/files/download/28

You can get more information about this step in Chapter 1 of FuelPHP Application Development Blueprints, which can be accessed freely.

It is also well-documented on the website installation instructions page:

http://fuelphp.com/docs/installation/instructions.html

Installation directory and apache configuration

Now that you know how to install FuelPHP in a given directory, we will explain where to install it and how to configure Apache.

The simplest way

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 fuel in the DIR directory inside the root folder (/var/www/DIR), you will be able to access your project on the following URL:

http://localhost/DIR/public/

However, be warned that fuel 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 explained in the section below, 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 Fuel installation instruction page:

http://fuelphp.com/docs/installation/instructions.html

By setting up a virtual host

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

• Your apache virtual host file(s) in order to link a virtual host to your application
• Your system host file, in order redirect the wanted URL to your virtual host

In both cases, the files location will be very dependent on your operating system and the server environment you are using, so you will have to figure their location yourself (if you are using a common configuration, you won’t have any problem to find instructions on the web).

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

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 files 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 that. You can now access your website on the following URL:

http://my.app/

Checking that everything works

Whether you used a virtual host or not, the following should now appear when accessing your website:



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

Database configuration

As we will store our monkeys into a MySQL database, it is time to configure FuelPHP to use our local database. If you open fuel/app/config/db.php, all you will see is an empty array but this configuration file is merged to fuel/app/config/ENV/db.php, ENV being the current Fuel’s environment, which in that case is development.

You should therefore open fuel/app/config/development/db.php:

<?php
//...
return array(
'default' => array(
   'connection' => array(
     'dsn'       => 'mysql:host=localhost;dbname=fuel_dev',
     'username'   => 'root',
     'password'   => 'root',
   ),
),
);

You should adapt this array to your local configuration, particularly the database name (currently set to fuel_dev), the username, and password. You must create your project’s database manually.

Scaffolding

Now that the database configuration is set, we will be able to generate a scaffold. We will use for that the generate feature of the oil utility.

Open the command-line utility and go to your website root directory. To generate a scaffold for a new model, you will need to enter the following line:

php oil generate scaffold/crud MODEL ATTR_1:TYPE_1 ATTR_2:TYPE_2 ...

Where:

• MODEL is the model name
• ATTR_1, ATTR_2… are the model’s attributes names
• TYPE_1, TYPE_2… are each attribute type

In our case, it should be:

php oil generate scaffold/crud monkey name:string still_here:bool height:float description:text

Here we are telling oil to generate a scaffold for the monkey model with the following attributes:

• name: The name of the monkey. Its type is string and the associated MySQL column type will be VARCHAR(255).
• still_here: Whether or not the monkey is still in the facility. Its type is boolean and the associated MySQL column type will be TINYINT(1).
• height: Height of the monkey. Its type is float and its associated MySQL column type will be FLOAT.
• description: Description of the monkey. Its type is text and its associated MySQL column type will be TEXT.

You can do much more using the oil generate feature, as generating models, controllers, migrations, tasks, package and so on. We will see some of these in the FuelPHP Application Development Blueprints book and you are also recommended to take a look at the official documentation:

http://fuelphp.com/docs/packages/oil/generate.html

When you press Enter, you will see the following lines appear:

Creating migration: APPPATH/migrations/001_create_monkeys.php
Creating model: APPPATH/classes/model/monkey.php
Creating controller: APPPATH/classes/controller/monkey.php
Creating view: APPPATH/views/monkey/index.php
Creating view: APPPATH/views/monkey/view.php
Creating view: APPPATH/views/monkey/create.php
Creating view: APPPATH/views/monkey/edit.php
Creating view: APPPATH/views/monkey/_form.php
Creating view: APPPATH/views/template.php

Where APPPATH is your website directory/fuel/app. Oil has generated for us nine files:

• A migration file, containing all the necessary information to create the model’s associated table
• The model
• A controller
• Five view files and a template file

More explanation about these files and how they interact with each other can be accessed in Chapter 1 of the FuelPHP Application Development Blueprints book, freely available. For those of you who are not yet familiar with MVC and HMVC frameworks, don’t worry; the chapter contains an introduction to the most important concepts.

Migrating

One of the generated files was APPPATH/migrations/001_create_monkeys.php. It is a migration file and contains the required information to create our monkey table. Notice the name is structured as VER_NAME where VER is the version number and NAME is the name of the migration.

If you execute the following command line:

php oil refine migrate

All migrations files that have not been yet executed will be executed from the oldest version to the latest version (001, 002, 003, and so on). Once all files are executed, oil will display the latest version number.

Once executed, if you take a look at your database, you will observe that not one, but two tables have been created:

• monkeys: As expected, a table have been created to handle your monkeys. Notice that the table name is the plural version of the word we typed for generating the scaffold; such a transformation was internally done using the Inflector::pluralize method. The table will contain the specified columns (name, still_here), the id column, but also created_at and updated_at. These columns respectively store the time an object was created and updated, and are added by default each time you generate your models. It is though possible to not generate them with the --no-timestamp argument.
• migration: This other table was automatically created. It keeps track of the migrations that were executed. If you look into its content, you will see that it already contains one row; this is the migration you just executed. You can notice that the row does not only indicate the name of the migration, but also a type and a name. This is because migrations files can be placed at many places such as modules or packages.

The oil utility allows you to do much more. Don’t hesitate to take a look at the official documentation:

http://fuelphp.com/docs/packages/oil/intro.html

Or, again, to read FuelPHP Application Development Blueprints’ Chapter 1 which is available for free.

Using your application

Now that we generated the code and migrated the database, our application is ready to be used.

Request the following URL:

• If you created a virtual host: http://my.app/monkey
• Otherwise (don’t forget to replace DIR): http://localhost/DIR/public/monkey

As you can notice, this webpage is intended to display the list of all monkeys, but since none have been added, the list is empty.



Then let’s add a new monkey by clicking on the Add new Monkey button. The following webpage should appear:



You can enter your monkey’s information here. The form is certainly not perfect - for instance the Still here field use a standard input although a checkbox would be more appropriated - but it is a great start. All we will have to do is refine the code a little bit.

Once you have added several monkeys, you can again take a look at the listing page:



Again, this is a great start, though we might want to refine it.

Each item on the list has three associated actions: View, Edit, and Delete.

Let’s first click on View:



Again a great start, though we will refine this webpage.

You can return back to the listing by clicking on Back or edit the monkey file by clicking on Edit. Either accessed from the listing page or the view page, it will display the same form as when creating a new monkey, except that the form will be prefilled of course.

Finally, if you click on Delete, a confirmation box will appear to prevent any miss clicking.

Want to learn more ?

Don’t hesitate to check out FuelPHP Application Development Blueprints’ Chapter 1 which is freely available in Packt Publishing’s website. In this chapter, you will find a more thorough introduction to FuelPHP and we will show how to improve this first application. You are also recommended to explore FuelPHP website, which contains a lot of useful information and an excellent documentation:

http://www.fuelphp.com

There is much more to discover about this wonderful framework.

Summary

In this article we leaned about the installation of the FuelPHP environment and installation of directories in it.

Resources for Article:

• PHP Magic Features [Article]
• FuelPHP [Article]
• Building a To-do List with Ajax [Article]