Building with FuelPHP
Let's build our first tiny application.
Suppose that 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 the following:
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 the following five major features:
You want to create a new monkey
You want to edit existing ones
You want to list all monkeys
You want to view a detailed file for each monkey
You want to delete monkeys from the system
The preceding five major features, very common in computer applications, are part of the Create, Read, Update and Delete (CRUD) basic operations. This is a perfect example to use the oil utility to generate a scaffold. Oil will quickly generate for us the controllers, models, views, and migrations to handle our monkeys. All we will have to do, then, is to refine the generated code and adapt it to our needs.
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, as we demonstrated it in the FuelPHP basicssection, this configuration file is merged to fuel/app/config/ENV/db.php, ENVbeing the current FuelPHP'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', ), ), );
This is the generated default configuration, which you should adapt to your local configuration, particularly the database name (currently set to fuel_dev), the username, and password. You must create the database of your project manually.
Scaffolding
Now that the database configuration is set, we will be able to generate a scaffold. We will use 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 attribute names
TYPE_1, TYPE_2… are attribute types
In our case, it should be as follows:
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 the associated MySQL column type will be FLOAT.
description: Description of the monkey. Its type is text and the associated MySQL column type will be TEXT.
You can do much more using the oil generate feature, such as generating models, controllers, migrations, tasks, packages, and so on. We will see some of these later in the book, but you are recommended to take a look at the official documentation at http://fuelphp.com/docs/packages/oil/generate.html (It can be accessed through the FuelPHP website by navigating to DOCS | TABLE OF CONTENTS | Oil | Generate)
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
Oil has generated for us nine files, which are as follows:
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
We will take a closer look at these files in the next sections.
You might have noticed that we used the scaffold/crud command, and, if you read the official documentation, we could have typed only scaffold. This is because two types of scaffold can be generated: scaffold/crud, which uses simple models, and scaffold/orm alias scaffold, which uses the orm models. Since using FuelPHP's native ORM was out of the scope of this chapter, and we didn't have to use complex model features such as relations, we chose to use scaffold/crud.
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 that 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 migration files that have not yet been executed will be executed from the oldest version to the latest version (001, 002, 003, and so on). Once all migration 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 has 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, and also created_at and updated_at. These columns store the time an object was created and updated, and are added by default each time you generate your models. It is possible to not generate them with the --no-timestamp argument.
migration: This table is automatically created the first time you execute migrations. 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 migration files can be placed at many places such as modules or packages (see Chapter 3, Building a Blog Application).
The refine migrate feature of oil allows you to have much more control on migrations than simply executing all the new ones. For instance, you can also revert to a previous version using the following command line:
php oil refine migrate:down
Or revert to a specified version using the following command line:
php oil refine migrate --version=3
Or even choose which modules or packages you want to update using the --modules or --package arguments. To have a complete overview, you are recommended to take a look at the official documentation at http://fuelphp.com/ docs/general/migrations.html (It can be accessed through the FuelPHP website by navigating to DOCS | TABLE OF CONTENTS | FuelPHP | Migrations)
But how do migration files allow such complex manipulations? Let's open our migration file located at APPPATH/migrations/001_create_monkeys.php to find out. You should see the following:
<?php namespace Fuel\Migrations; class Create_monkeys { public function up() { \DBUtil::create_table('monkeys', array( 'id' => array( 'constraint' => 11, 'type' => 'int', 'auto_increment' => true, 'unsigned' => true ), 'name' => array( 'constraint' => 255, 'type' => 'varchar' ), 'still_here' => array( 'type' => 'bool' ), 'height' => array( 'type' => 'float' ), 'description' => array( 'type' => 'text' ), 'created_at' => array( 'constraint' => 11, 'type' => 'int', 'null' => true ), 'updated_at' => array( 'constraint' => 11, 'type' => 'int', 'null' => true ), ), array('id')); } public function down() { \DBUtil::drop_table('monkeys'); } }
The file contains a class named Create_monkeys that has the following two methods:
up: This method defines how to update your data structure. Note that this migration file creates the monkey table using the DBUtil::create_tablemethod, but you could perfectly execute a handmade SQL request to do that. Though migrations are generally used to update your database, you can also use them to update custom data files or old configuration files.
Using your application
Now that we have generated the code and migrated the database, our application is ready to be used. You might have noticed during the generation that a controller was created at APPPATH/classes/controller/monkey.php and that the route configuration file was not changed, meaning that the controller must be accessible through the default URL.
Let's request, then, the URL http://my.app/monkey.
As you can notice, this web page is intended to display the list of all monkeys, but since none have been added, the list is empty: You can now edit, add, and delete "Monkey" lists.