Day 3: The ~Data Model~

Those of you itching to open your text editor and lay down some PHP will be happy to know today's tutorial will get us into some development. We will define the Jobeet data model, use an ORM to interact with the database, and build the first module of the application. But as symfony does a lot of the work for us, we will have a fully functional web module without writing too much PHP code.

The Relational ~Model~

The ~Schema~

But as symfony is an Object-Oriented framework, we like to manipulate ~object|OOP~s whenever we can. For example, instead of writing SQL statements to retrieve records from the database, we'd rather prefer to use objects.

If you have decided to create the tables by writing SQL statements, you can generate the corresponding schema.yml configuration file by running the propel:build-schema task:

$ php symfony propel:build-schema

The above task requires that you have a configured database in databases.yml. We show you how to configure the database in a later step. If you try and run this task now it won't work as it doesn't know what database to build the schema for.

The ~YAML~ Format

According to the official YAML website, YAML is \"a human friendly data serialization standard for all programming languages\"

Put another way, YAML is a simple language to describe data (strings, integers, dates, arrays, and hashes).

In YAML, structure is shown through indentation, sequence items are denoted by a dash, and key/value pairs within a map are separated by a colon. YAML also has a shorthand syntax to describe the same structure with fewer lines, where arrays are explicitly shown with [] and hashes with {}.

If you are not yet familiar with YAML, it is time to get started as the symfony framework uses it extensively for its configuration files.

There is one important thing you need to remember when editing a YAML file: indentation must be done with one or more spaces, but never with ~tabulations|Code Formatting~.

The ~Database~

The symfony framework supports all PDO-supported databases (MySQL, PostgreSQL, SQLite, Oracle, MSSQL, ...). ~PDO~ is the ~database abstraction layer|Database Abstraction Layer~ bundled with PHP.

Let's use ~MySQL~ for this tutorial:

$ mysqladmin -uroot -p create jobeet
Enter password: mYsEcret ## The password will echo as ********

Feel free to choose another ~database engine|Database Engine~ if you want. It won't be difficult to adapt the code we will write as we will use the ORM will write the SQL for us.

We need to tell symfony to use this database for the Jobeet project:

The configure:database task takes three arguments: the ~PDO DSN~, the username, and the password to access the database. If you don't need a password to access your database on the development server, just omit the third argument.

The configure:database ~task|Tasks~ stores the ~database configuration|Database Configuration~ into the config/databases.yml configuration file. Instead of using the task, you can edit this file by hand.

Passing the database password on the command line is convenient but ~insecure|Security~. Depending on who has access to your environment, it might be better to edit the config/databases.yml to change the password. Of course, to keep the password safe, the configuration file access mode should also be restricted.

The ~ORM~

Thanks to the database description from the schema.yml file, we can use some Propel or Doctrine built-in tasks to generate the ~SQL~ statements needed to create the database tables:

The propel:build-sql task generates SQL statements in the data/sql/ directory, optimized for the database engine we have configured:

As for any ~command line|Command Line~ tool, symfony tasks can take arguments and options. Each task comes with a built-in help message that can be displayed by running the help task:

$ php symfony help propel:insert-sql

The help message lists all the possible arguments and options, gives the default values for each of them, and provides some useful usage examples.

The propel:build-model task generates PHP files in the lib/model/ directory that can be used to interact with the database.

The column values of a record can be manipulated with a model object by using some ~accessors|Accessors~ (get*() methods) and mutators (set*() methods):

You can also define ~foreign keys|Foreign Key~ directly by linking objects together:

$ php symfony propel:build-all --no-confirmation

As you will see later on, symfony ~autoloads|Autoload~ PHP classes for you, which means that you never need to use a require in your code. It is one of the numerous things that symfony automates for the developer but there is one downside: whenever you add a new class, you need to clear the symfony ~cache|Cache~. As the propel:build-model has created a lot of new classes, let's clear the cache:

A symfony ~task|Tasks~ is made of a namespace and a task name. Each one can be shortened as much as there is no ambiguity with other tasks. So, the following commands are equivalent to cache:clear:

$ php symfony cache:cl
$ php symfony ca:c

As the cache:clear task is so commonly used, it has an even shorter hardwired abbreviation:

$ php symfony cc

• Test data: ~Test Data~ are needed for the application to be tested. As a developer, you will write tests to ensure that Jobeet behaves as described in the user stories, and the best way is to write automated tests. So, each time you run your tests, you need a clean database with some fresh data to test on.

Each time symfony creates the tables in the database, all the data are lost. To populate the database with some initial data, we could create a PHP script, or execute some SQL statements with the mysql program. But as the need is quite common, there is a better way with symfony: create YAML files in the data/fixtures/ directory and use the propel:data-load task to load them into the database.

First, create the following ~fixture|Fixtures~ files:

The job fixture file references two images. You can download them (http://www.symfony-project.org/get/jobeet/sensio-labs.gif, http://www.symfony-project.org/get/jobeet/extreme-sensio.gif) and put them under the web/uploads/jobs/ directory.

A fixtures file is written in YAML, and defines model objects, labelled with a unique name (for instance, we have defined two jobs labelled job_sensio_labs and job_extreme_sensio). This label is of great use to link related objects without having to define ~primary keys|Primary Key~ (which are often auto-incremented and cannot be set). For instance, the job_sensio_labs job category is programming, which is the label given to the 'Programming' category.

In a YAML file, when a string contains line breaks (like the description column in the job fixture file), you can use the pipe (|) to indicate that the string will span several lines.

Although a fixture file can contain objects from one or several models, we have decided to create one file per model for the Jobeet fixtures.

In a fixture file, you don't need to define all columns values. If not, symfony will use the default value defined in the database schema. And as symfony uses Propel or Doctrine to load the data into the database, all the built-in ~behaviors|Behaviors (ORM)~ (like automatically setting the created_at or updated_at columns) and the custom behaviors you might have added to the model classes are activated.

The propel:build-all-load task is a shortcut for the propel:build-all task followed by the propel:data-load task.

Let's see how to display the list of jobs, how to edit an existing job, and how to delete a job. As explained during day 1, a symfony project is made of applications. Each ~application|Application~ is further divided into modules. A ~module|Module~ is a self-contained set of PHP code that represents a feature of the application (the API module for example), or a set of manipulations the user can do on a model object (a job module for example).

$ php symfony propel:generate-module --with-show
  ➥ --non-verbose-templates frontend job JobeetJob

The propel:generate-module generates a job module in the frontend application for the JobeetJob model. As with most symfony tasks, some files and directories have been created for you under the apps/frontend/modules/job/ directory:

The actions/actions.class.php file defines all the available ~action|Action~ for the job module:

You can now test the job module in a browser:

class JobeetJob extends BaseJobeetJob
{
  public function __toString()
  {
    return sprintf('%s at %s (%s)', $this->getPosition(),
     ➥ $this->getCompany(), $this->getLocation());
  }
}

See you Tomorrow

That's all for today. I have warned you in the introduction. Today, we have barely written PHP code but we have a working web module for the job model, ready to be tweaked and customized. Remember, no PHP code also means no bugs!

If you still have some energy left, feel free to read the generated code for the module and the model and try to understand how it works. If not, don't worry and sleep well, as tomorrow, we will talk about one of the most used paradigm in web frameworks, the MVC design pattern.

As for any other day, today's code is available on the Jobeet SVN repository. Checkout the release_day_03 tag:

$ svn co http://svn.jobeet.org/##ORM_LOWER##/tags/release_day_03/ jobeet/