Symfony2 Jobeet Day 7: Playing with the Category page

* This article is part of the original Jobeet Tutorial, created by Fabien Potencier, for Symfony 1.4.
Today we will make the Category page like it is described in the second day’s requirements:

“The user sees a list of all the jobs from the category sorted by date and paginated with 20 jobs per page“

The Category Route

First, we need to add a route to define a pretty URL for the category page. Add it at the beginning of the routing file:
[crayon-5de9e247dc78c514571713/]
To get the slug of a category we need to add the getSlug() method to our category class:
[crayon-5de9e247dc7a7059707787/]

The Category Link

Now, edit the index.html.twig template of the job controller to add the link to the category page:
[crayon-5de9e247dc7b2828478935/]
In the template above we used category.morejobs, so let’s define it:
[crayon-5de9e247dc7bd052286516/]
The more_jobs property will hold the number of active jobs for the category minus the number of jobs listed on the homepage. Now, in JobController, we need to set the more_jobs value for each category:
[crayon-5de9e247dc7c8130583562/]
The countActiveJobs function has to be added to the JobRepository:
[crayon-5de9e247dc7db164695299/]
Now you should see the result in your browser:

Day-7 - category link

Category Controller Creation

It’s now time to create the Category controller. Create a new CategoryController.php file in your Controller directory:
[crayon-5de9e247dc7e8431545819/]
We could use the doctrine:generate:crud command like we did for the job controller, but we won’t need 90% of the generated code, so we can just create a new controller from scratch.

Update the Database

We need to add a slug column for the category table and lifecycle callbacks for setting this column value:
[crayon-5de9e247dc7f4244800440/]
Remove from the Category entity (src/Ibw/JobeetBundle/Entity/Category.php) the getSlug method we created earlier and run the doctrine command to update the Category entity class:
[crayon-5de9e247dc7ff962066871/]
Now you should have the following added to Category.php:
[crayon-5de9e247dc810492378877/]
Change the setSlugValue() function:
[crayon-5de9e247dc81b859327563/]
Now we have to drop the database and create it again with the new Category column and load the fixtures:
[crayon-5de9e247dc826949204023/]

Category Page

We have now everything in place to create the showAction() method. Add the following code to the CategoryController.php file:
[crayon-5de9e247dc832458859259/]
The last step is to create the show.html.twig template:
[crayon-5de9e247dc83c117770744/]

Including Other Twig Templates

Notice that we have copied and pasted the tag that create a list of jobs from the job index.html.twig template. That’s bad. When you need to reuse some portion of a template, you need to create a new twig template with that code and include it where you need. Create the list.html.twig file:
[crayon-5de9e247dc849880818484/]
You can include a template by using the include function. Replace the HTML <table> code from both templates with the mentioned function:
[crayon-5de9e247dc854307969582/]
[crayon-5de9e247dc85f218550704/]

List Pagination

At the moment of writing this, Symfony2 doesn’t provide any good pagination tools out of the box so to solve this problem we will use the old classic method. First, let’s add a page parameter to the IbwJobeetBundle_category route. The page parameter will have a default value of 1, so it will not be required:

[crayon-5de9e247dc86a314889609/]

Clear the cache after modifying the routing file:

[crayon-5de9e247dc874700547110/]

The number of jobs on each page will be defined as a custom parameter in the app/config/config.yml file:

[crayon-5de9e247dc87f243673755/]

Change the JobRepository getActiveJobs method to include an $offset parameter to be used by doctrine when retrieving jobs:

[crayon-5de9e247dc889322262906/]

Change the CategoryController showAction to the following:

[crayon-5de9e247dc894545209840/]

Finally, let’s update the template

[crayon-5de9e247dc8a1495457566/]

The result:

Day 7 - pagination
Creative Commons License
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.


Symfony2 Jobeet Day 6: More with the Model

* This article is part of the original Jobeet Tutorial, created by Fabien Potencier, for Symfony 1.4.

The Doctrine Query Object

From the second day’s requirements: “On the homepage, the user sees the latest active jobs”. But as of now, all jobs are displayed, whether they are active or not:
[crayon-5de9e247deda1742987043/]
An active job is one that was posted less than 30 days ago. The $entities = $em->getRepository('IbwJobeetBundle')->findAll() method will make a request to the database to get all the jobs. We are not specifying any condition, which means that all the records are retrieved from the database.

Let’s change it to only select active jobs:
[crayon-5de9e247dedb1096795997/]

Debugging Doctrine generated SQL

Sometimes, it is of great help to see the SQL generated by Doctrine; for instance, to debug a query that does not work as expected. In the dev environment, thanks to the Symfony Web Debug Toolbar, all the information you need is available within the comfort of your browser (http://jobeet.local/app_dev.php):

Day 6 - web debug toolbar

Object Serialization

Even if the code above works, it is far from perfect as it does not take into account some requirements from Day 2: “A user can come back to re-activate or extend the validity of the job for an extra 30 days..”.

But as the above code only relies on the created_at value, and because this column stores the creation date, we cannot satisfy the above requirement.

If you remember the database schema we have described during Day 3, we also have defined an expires_at column. Currently, if this value is not set in fixture file, it remains always empty. But when a job is created, it can be automatically set to 30 days after the current date.

When you need to do something automatically before a Doctrine object is serialized to the database, you can add a new action to the lifecycle callbacks in the file that maps objects to the database, like we did earlier for the created_at column:
[crayon-5de9e247dedb9022406869/]
Now, we have to rebuild the entities classes so Doctrine will add the new function:
[crayon-5de9e247dedc0037185928/]
Open the src/Ibw/JobeetBundle/Entity/Job.php file and edit the new added function:
[crayon-5de9e247dedc5487353859/]
Now, let’s change the action to use the expires_at column instead of the created_at one to select the active jobs:
[crayon-5de9e247dedca925870245/]

More with Fixtures

Refreshing the Jobeet homepage in your browser won’t change anything, as the jobs in the database have been posted just a few days ago. Let’s change the fixtures to add a job that is already expired:
[crayon-5de9e247dedd0486337501/]
Reload the fixtures and refresh your browser to ensure that the old job does not show up:
[crayon-5de9e247dedd7241449261/]

Refactoring

Although the code we have written works fine, it’s not quite right yet. Can you spot the problem?

The Doctrine query code does not belong to the action (the Controller layer), it belongs to the Model layer. In the MVC model, the Model defines all the business logic, and the Controller only calls the Model to retrieve data from it. As the code returns a collection of jobs, let’s move the code to the model. For that we will need to create a custom repository class for Job entity and to add the query to that class.

Open /src/Ibw/JobeetBundle/Resources/config/doctrine/Job.orm.yml and add the following to it:
[crayon-5de9e247deddd631089807/]
Doctrine can generate the repository class for you by running the generate:entities command used earlier:
[crayon-5de9e247dede2664598718/]
Next, add a new method – getActiveJobs() – to the newly generated repository class. This method will query for all of the active Job entities sorted by the expires_at column (and filtered by category, if it receives the $category_id parameter).
[crayon-5de9e247dede8973110624/]
Now the action code can use this new method to retrieve the active jobs.
[crayon-5de9e247dee0d910872433/]
This refactoring has several benefits over the previous code:

  • The logic to get the active jobs is now in the Model, where it belongs
  • The code in the controller is thinner and much more readable
  • The getActiveJobs() method is re-usable (for instance in another action)
  • The model code is now unit testable

Categories on the Homepage

According to the second day’s requirements we need to have jobs sorted by categories. Until now, we have not taken the job category into account. From the requirements, the homepage must display jobs by category. First, we need to get all categories with at least one active job.

Create a repository class for the Category entity like we did for Job:
[crayon-5de9e247dee19114367993/]
Generate the repository class:
[crayon-5de9e247dee1f566145429/]
Open the CategoryRepository class and add a getWithJobs() method:
[crayon-5de9e247dee25881355427/]
Change the index action accordingly:
[crayon-5de9e247dee2a374717425/]
For this to work, we have to add a new property to our Category class, the active_jobs:
[crayon-5de9e247dee30256546432/]
In the template, we need to iterate through all categories and display the active jobs:
[crayon-5de9e247dee35728530329/]

Limit the results

There is still one requirement to implement for the homepage job list: we have to limit the job list to 10 items. That’s simple enough to add the $max parameter to the JobRepository::getActiveJobs() method:
[crayon-5de9e247dee3c025744909/]
Change the call to getActiveJobs() to include the $max parameter:
[crayon-5de9e247dee42698535694/]

Custom Configuration

In the JobController, indexAction method, we have hardcoded the number of max jobs returned for a category. It would have been better to make the 10 limit configurable. In Symfony, you can define custom parameters for your application in the app/config/config.yml file, under the parameters key (if the parameters key doesn’t exist, create it):
[crayon-5de9e247dee48994580678/]
This can now be accessed from a controller:
[crayon-5de9e247dee4e744387391/]

Dinamic Fixtures

For now, you won’t see any difference because we have a very small amount of jobs in our database. We need to add a bunch of jobs to the fixture. So, you can copy and paste an existing job ten or twenty times by hand… but there’s a better way. Duplication is bad, even in fixture files:
[crayon-5de9e247dee54651506869/]
You can now reload the fixtures with the doctrine:fixtures:load task and see if only 10 jobs are displayed on the homepage for the Programming category:

Day 6 - limited no of jobs

Secure the Job Page

When a job expires, even if you know the URL, it must not be possible to access it anymore. Try the URL for the expired job (replace the id with the actual id in your database – SELECT id, token FROM job WHERE expires_at < NOW()):

/app_dev.php/job/sensio-labs/paris-france/ID/web-developer-expired

Instead of displaying the job, we need to forward the user to a 404 page. For this we will create a new function in the JobRepository:
[crayon-5de9e247dee5b709335260/]

The getSingleResult() method throws a DoctrineORMNoResultException exception if no results are returned and a DoctrineORMNonUniqueResultException if more than one result is returned. If you use this method, you may need to wrap it in a try-catch blockand ensure that only one result is returned.

Now change the showAction() from the JobController to use the new repository method:
[crayon-5de9e247dee61522726051/]
Now, if you try to get an expired job, you will be forwarded to a 404 page:

Day 6 - no job found

That’s all for today! We will see you again tomorrow, when we’ll be playing with the category page.

Creative Commons License
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.


Symfony2 Jobeet Day 5: The Routing

* This article is part of the original Jobeet Tutorial, created by Fabien Potencier, for Symfony 1.4.

URLs

If you click on a job on the Jobeet homepage, the URL looks like this: /job/1/show. If you have already developed PHP websites, you are probably more accustomed to URLs like /job.php?id=1. How does Symfony make it work? How does Symfony determine the action to call based on this URL? Why is the id of the job retrieved with the $id parameter in the action? Here, we will answer all these questions.

You have already seen the following code in the src/Ibw/JobeetBundle/Resources/views/Job/index.html.twig template:
[crayon-5de9e247e0669324871561/]
This uses the path template helper function to generate the url for the job which has the id 1. The ibw_job_show is the name of the route used, defined in the configuration as you will see below.

Routing Configuration

In Symfony2, routing configuration is usually done in the app/config/routing.yml. This imports specific bundle routing configuration. In our case, the src/Ibw/JobeetBundle/Resources/config/routing.yml file is imported:
[crayon-5de9e247e0676764536724/]
Now, if you look in the JobeetBundle routing.yml you will see that it imports another routing file, the one for the Job controller and defines a route called ibw_jobeet_homepage for the /hello/{name} URL pattern:
[crayon-5de9e247e067c643278669/]
[crayon-5de9e247e0682415533830/]
Let’s have a closer look to the ibw_job_show route. The pattern defined by the ibw_job_show route acts like /*/show where the wildcard is given the name id. For the URL /1/show, the id variable gets a value of 1, which is available for you to use in your controller. The _controller parameter is a special key that tells Symfony which controller/action should be executed when a URL matches this route, in our case it should execute the showAction from the JobController in the IbwJobeetBundle.

The route parameters (e.g. {id}) are especially important because each is made available as an argument to the controller method.

Routing Configuration in Dev Environment

The dev environment loads the app/config/routing_dev.yml file that contains the routes used by the Web Debug Toolbar (you already deleted the routes for the AcmeDemoBundle from /app/config/routing_dev.php – see Day 1, How to remove the AcmeDemoBundle). This file loads, at the end, the main routing.yml configuration file.

Route Customizations

For now, when you request the / URL in a browser, you will get a 404 Not Found error. That’s because this URL does not match any routes defined. We have a ibw_jobeet_homepage route that matches the /hello/jobeet URL and sends us to the DefaultController, index action. Let’s change it to match the / URL and to call the index action from the JobController. To make the change, modify it to the following:
[crayon-5de9e247e0689026356996/]
Now, if you clear the cache and go to http://jobeet.local from your browser, you will see the Job homepage. We can now change the link of the Jobeet logo in the layout to use the ibw_jobeet_homepage route:
[crayon-5de9e247e068f831013226/]
For something a bit more involved, let’s change the job page URL to something more meaningful:
[crayon-5de9e247e0695545641235/]
Without knowing anything about Jobeet, and without looking at the page, you can understand from the URL that Sensio Labs is looking for a Web developer to work in Paris, France.

The following pattern matches such a URL:
[crayon-5de9e247e069a845532686/]
Edit the ibw_job_show route from the job.yml file:
[crayon-5de9e247e069f549882636/]
Now, we need to pass all the parameters for the changed route for it to work:
[crayon-5de9e247e06a4933400309/]
If you have a look at generated URLs, they are not quite yet as we want them to be:

http://jobeet.local/app_dev.php/job/Sensio Labs/Paris,France/1/Web Developer
We need to “slugify” the column values by replacing all non ASCII characters by a -. Open the Job.php file and add the following methods to the class:
[crayon-5de9e247e06aa009514358/]
You must also add the use statement before the Job class definition.
After that, create the src/Ibw/JobeetBundle/Utils/Jobeet.php file and add the slugify method in it:
[crayon-5de9e247e06b0049541611/]
We have defined three new “virtual” accessors: getCompanySlug(), getPositionSlug(), and getLocationSlug(). They return their corresponding column value after applying it the slugify() method. Now, you can replace the real column names by these virtual ones in the template:
[crayon-5de9e247e06b5918122290/]

Route Requirements

The routing system has a built-in validation feature. Each pattern variable can be validated by a regular expression defined using the requirements entry of a route definition:
[crayon-5de9e247e06bb908036373/]
The above requirements entry forces the id to be a numeric value. If not, the route won’t match.

Route Debugging

While adding and customizing routes, it’s helpful to be able to visualize and get detailed information about your routes. A great way to see every route in your application is via the router:debug console command. Execute the command by running the following from the root of your project:
[crayon-5de9e247e06c0765296856/]
The command will print a helpful list of all the configured routes in your application. You can also get very specific information on a single route by including the route name after the command:
[crayon-5de9e247e06c6974939992/]

Final Thoughts

That’s all for today! To learn more about the Symfony2 routing system read the Routing chapter form the book.

Creative Commons License
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.


Symfony2 Jobeet Day 4: The Controller and the View

* This article is part of the original Jobeet Tutorial, created by Fabien Potencier, for Symfony 1.4.

Today, we are going to customize the basic job controller we created yesterday. It already has most of the code we need for Jobeet:

  • A page to list all jobs
  • A page to create a new job
  • A page to update an existing job
  • A page to delete a job

Although the code is ready to be used as is, we will refactor the templates to match closer to the Jobeet mockups.

The MVC Arhitecture

For web development, the most common solution for organizing your code nowadays is the MVC design pattern. In short, the MVC design pattern defines a way to organize your code according to its nature. This pattern separates the code into three layers:

  • The Model layer defines the business logic (the database belongs to this layer). You already know that Symfony stores all the classes and files related to the Model in the Entity/ directory of your bundles.
  • The View is what the user interacts with (a template engine is part of this layer). In Symfony 2.3.2, the View layer is mainly made of Twig templates. They are stored in various Resources/views/ directories as we will see later in these lines.
  • The Controller is a piece of code that calls the Model to get some data that it passes to the View for rendering to the client. When we installed Symfony at the beginning of this tutorial, we saw that all requests are managed by front controllers (app.php and app_dev.php). These front controllers delegate the real work to actions.

The Layout

If you have a closer look at the mockups, you will notice that much of each page looks the same. You already know that code duplication is bad, whether we are talking about HTML or PHP code, so we need to find a way to prevent these common view elements from resulting in code duplication.

One way to solve the problem is to define a header and a footer and include them in each template. A better way is to use another design pattern to solve this problem: the decorator design pattern. The decorator design pattern resolves the problem the other way around: the template is decorated after the content is rendered by a global template, called a layout.

Symfony2 does not came with a default layout, so we will create one and use it to decorate our application pages.

Create a new file layout.html.twig in the src/Ibw/JobeetBundle/Resources/views/ directory and put in the following code:
[crayon-5de9e247e17b2037692173/]

Twig Blocks

In Twig, the default Symfony template engine, you can define blocks as we did above. A twig block can have a default content (look at the title block, for example) that can be replaced or extended in the child template as you will see in a moment.

Now, to make use of the layout we created, we will need to edit all the job templates (index, edit, new and show from src/Ibw/JobeetBundle/Resources/views/Job/) to extend the parent template (the layout) and to overwrite the content block we defined with the body block content from the original template
[crayon-5de9e247e17d5097180479/]

The Stylesheets, Images and JavaScripts

As this is not about web design, we have already prepared all the needed assets we will use for Jobeet: download the image files archive and put them into the src/Ibw/JobeetBundle/Resources/public/images/ directory; download the stylesheet files archive and put them into the src/Ibw/JobeetBundle/Resources/public/css/ directory.

Now run
[crayon-5de9e247e17dc702331570/]
to tell Symfony to make them available to the public.

If you look in the css folder, you will notice that we have four css files: admin.css, job.css,jobs.css and main.css. The main.css is needed in all Jobeet pages, so we included it in the layout in the stylesheet twig block. The rest are more specialized css files and we need them only in specific pages.

To add a new css file in a template, we will overwrite the stylesheet block, but call the parent before adding the new css file (so we would have the main.css and the additional css files we need).
[crayon-5de9e247e17e2601708706/]
[crayon-5de9e247e17e8206681548/]

The Job Homepage Action

Each action is represented by a method of a class. For the job homepage, the class is JobController and the method is indexAction(). It retrieves all the jobs from the database.
[crayon-5de9e247e17ee713301463/]
Let’s have a closer look at the code: the indexAction() method gets the Doctrine entity manager object, which is responsible for handling the process of persisting and fetching objects to and from database, and then the repository, that will create a query to retrieve all the jobs. It returns a Doctrine ArrayCollection of Job objects that are passed to the template (the View).

The Job Homepage Template

The index.html.twig template generates an HTML table for all the jobs. Here is the current template code:
[crayon-5de9e247e17f4511648324/]
Let’s clean this up a bit to only display a sub-set of the available columns. Replace the twig block content with the one below:
[crayon-5de9e247e17fc854295287/]
Day 4 - 2 jobs

The Job Page Template

Now let’s customize the template of the job page. Open the show.html.twig file and replace its content with the following code:
[crayon-5de9e247e1803920291456/]
Day 4 - individual job

The Job Page Action

The job page is generated by the show action, defined in the showAction() method of the JobController:
[crayon-5de9e247e180a225655497/]
As in the index action, the IbwJobeetBundle repository class is used to retrieve a job, this time using the find() method. The parameter of this method is the unique identifier of a job, its primary key. The next section will explain why the $id parameter of the actionShow() function contains the job primary key.

If the job does not exist in the database, we want to forward the user to a 404 page, which is exactly what the throw $this->createNotFoundException() does.

As for exceptions, the page displayed to the user is different in the prod environment and in the dev ennvironment.

Day 4 - error1

Day 4 - error2

That’s all for today! Tomorrow we will get you familiar with the routing features.

Creative Commons License
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.


Symfony2 Jobeet Day 3: The Data Model

* This article is part of the original Jobeet Tutorial, created by Fabien Potencier, for Symfony 1.4.

If you’re itching to open your text editor and lay down some PHP, you will be happy to know that today 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 work for us, we will have a fully functional web module without writing too much PHP code.

The Relational Model

The user stories from the previous day describe the main objects of our project: jobs, affiliates, and categories. Here is the corresponding entity relationship diagram:

Day3 - entity_diagram

 

In addition to the columns described in the stories, we have also added created_at and updated_at columns. We will configure Symfony to set their value automatically when an object is saved or updated.

The Database

To store the jobs, affiliates and categories in the database, Symfony 2.3.2 uses Doctrine ORM. To define the database connection parameters, you have to edit the app/config/parameters.yml file (for this tutorial we will use MySQL):
[crayon-5de9e247e28b0087414800/]
Now that Doctrine knows about your database, you can have it create the database for you by typing the following command in your terminal:
[crayon-5de9e247e28bd559511255/]

The Schema

To tell Doctrine about our objects, we will create “metadata” files that will describe how our objects will be stored in the database. Now go to your code editor and create a directory named doctrine, inside src/Ibw/JobeetBundle/Resources/config directory. Doctrine will contain three files: Category.orm.yml, Job.orm.yml and Affiliate.orm.yml.
[crayon-5de9e247e28c4410809257/]
[crayon-5de9e247e28ca386925989/]
[crayon-5de9e247e28d0245174610/]

The ORM

Now Doctrine can generate the classes that define our objects for us with the command:
[crayon-5de9e247e28d7112971497/]
If you take a look into Entity directory from IbwJobeetBundle, you will find the newly generated classes in there: Category.php, Job.php and Affiliate.php. Open Job.php and set the created_at and updated_at values as below:
[crayon-5de9e247e28dc447510997/]
You will do the same for created_at value of the Affiliate class:
[crayon-5de9e247e28e2476900534/]
This will make Doctrine to set the created_at and updated_at values when saving or updating objects. This behaviour was defined in the Affiliate.orm.yml and Job.orm.yml files listed above.

We will also ask Doctrine to create our database tables with the command below:
[crayon-5de9e247e28e7557224517/]

This task should only be used during the development. For a more robust method of systematically updating your production database, read about Doctrine migrations.

The tables have been created in the database but there is no data in them. For any web application, there are three types of data: initial data (this is needed for the application to work, in our case we will have some initial categories and an admin user), test data (needed for the application to be tested) and user data (created by users during the normal life of the application).

To populate the database with some initial data, we will use DoctrineFixturesBundle. To setup this bundle, we have to follow the next steps:

1. Add the following to your composer.json file, in the require section:
[crayon-5de9e247e28ed261666324/]
2. Update the vendor libraries:
[crayon-5de9e247e28f3772651292/]
3. Register the bundle DoctrineFixturesBundle in app/AppKernel.php:
[crayon-5de9e247e28f7736860571/]
Now that everything is set up, we will create some new classes to load data in a new folder, named src/Ibw/JobeetBundle/DataFixtures/ORM, in our bundle:
[crayon-5de9e247e28fd392828562/]
 
[crayon-5de9e247e2903412109320/]
Once your fixtures have been written, you can load them via the command line by using thedoctrine:fixtures:load command:
[crayon-5de9e247e290b714758742/]
Now, if you check your database, you should see the data loaded into tables.

See it in the browser

If you run the command below, it will create a new controller src/Ibw/JobeetBundle/Controllers/JobController.php with actions for listing, creating, editing and deleting jobs (and their corresponding templates, form and routes):
[crayon-5de9e247e2910311825640/]
After running this command, you will need to do some configurations the prompter requires you to. So just select the default answers for them.

To view this in the browser, we must import the new routes that were created in src/Ibw/JobeetBundle/Resources/config/routing/job.yml into our bundle main routing file:
[crayon-5de9e247e2916114559281/]
We will also need to add a _toString() method to our Category class to be used by the category drop down from the edit job form:
[crayon-5de9e247e291b225694286/]
Clear the cache:
[crayon-5de9e247e2920156949254/]
You can now test the job controller in a browser: http://jobeet.local/job/ or, in development environment, http://jobeet.local/app_dev.php/job/ .

Day 3 - index_page

You can now create and edit jobs. Try to leave a required field blank, or try to enter invalid data. That’s right, Symfony has created basic validation rules by introspecting the database schema.

That’s all. Today, we have barely written PHP code but we have a working web module for the job model, ready to be tweaked and customized. Tomorrow, we will get familiar with the controller and the view. See you next time!

Creative Commons License
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.


Symfony2 Jobeet Day 2: The Project

* This article is part of the original Jobeet Tutorial, created by Fabien Potencier, for Symfony 1.4.
We have not written a single line of code yet, but, in Day 1, we setup the environment and created an empty Symfony project.

This day is about the project specifications. Before diving into the code head-first, let’s describe the project a bit more. The following sections describe the features we want to implement in the first version/iteration of the project with some simple stories.

User Stories

The Jobeet website will have four type of users: admin (owns and manages the website), user (visits the website looking for a job), poster (visits the website to post jobs) and affiliate (re-publishes jobs on his website).

In the original tutorial, we had to make two applications, the frontend, where the users interact with the website, and the backend, where admins manage the website. Using Symfony 2.3.2, we would not do this anymore. We will have only one application and, in it, a separate secured section for admins.

Story F1: On the homepage, the user sees the latest active jobs

When a user comes to Jobeet website, he sees a list of active jobs. The jobs are sorted by category and then by publication date – newer jobs first. For each job, only the location, the position available and the company are displayed.

For each category, the list shows the first 10 jobs and a link that allows to list all the jobs for a given category (Story F2).

On the homepage, the user can refine the job list (Story F3) or post a new job (Story F5).

Story F2: A user can ask for all the jobs in a given category

When a user clicks on a category name or on a “more jobs” link on the homepage, he sees all the jobs for this category sorted by date.

The list is paginated with 20 jobs per page.

Story F3: A user refines the list with some keywords

The user can enter some keywords to refine his search. Keywords can be words found in the location, the position, the category or the company fields.

Story F4: A user clicks on a job to see more detailed information

The user can select a job from a list to see more detailed information.

Story F5: A user posts a job

A user can post a job. A job is made of several pieces of information:

  • Company
  • Type (full-time, part-time or freelance)
  • Logo (optional)
  • URL (optional)
  • Position
  • Location
  • Category (the user chooses in a list of possible categories)
  • Job description (URLs and emails are automatically linked)
  • How to apply (URLs and emails are automatically linked)
  • Public (wether the job can also be published on affiliate websites)
  • Email (email of poster)

The process has only two steps: first, the user fills in the form with all the needed information to describe the job, then validates the information by previewing the final job page.

There is no need to create an acount to post a job. A job can be modified afterwards thanks to a specific URL (protected by a token given to the user when the job is created).

Each job post is online for 30 days (this is configurable by admin). A user can come back to re-activate or extend the validity of the job for an extra 30 days, but only when the job expires in less than 5 days.

Story F6: A user applies to become an affiliate

A user needs to apply to become an affiliate and be authorized to use Jobeet API. To apply, he must give the following information:

  • Name
  • Email
  • Website URL

The affiliate account must be activated by the admin (Story B3). Once activated, the affiliate receives a token to use with the API via email.

Story F7: An affiliate retrieves the current active job list

An affiliate can retrieve the current job list by calling the API with his affiliate token. The list can be returned in the XML, JSON or YAML format. The affiliate can limit the number of jobs to be returned and, also, refine his query by specifying a category.

Story B1: An admin configures the website

An admin can edit the categories available on the website.

Story B2: An admin manages the jobs

An admin can edit and remove any posted job.

Story B3: An admin manages the affiliates

The admin can create or edit affiliates. He is responsible for activating an affiliate and can also disable one. When the admin activates a new affiliate, the system creates a unique token to be used by the affiliate.

As a developer, you never start coding from the first day. Firstly, you need to gather the requirements of your project and understand how your project is supposed to work. That’s what you have done today. See you tomorrow!

Creative Commons License
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.


Symfony2 Jobeet Day 1: Starting up the Project

* This article is part of the original Jobeet Tutorial, created by Fabien Potencier, for Symfony 1.4.

What is Jobeet?

Jobeet is an Open-Source job board software which provides you day-by-day tutorials, that will help you learn the latest Web Technolgy, Symfony 2.3.2 (for those who don’t know yet, Symfony is a framework for PHP).

Each chapter/day is meant to last about one hour, and will be the occasion to learn Symfony by coding a real website, from start to finish.

Every day, new features will be added to the application and we’ll take advantage of this development to introduce you to new Symfony functionalities, as well as good practices in Symfony web development.

Today, being your first day, you won’t be writing any code. Instead, you will setup a working development environment.

Setting up the working development environment

First of all, you need to check that your computer has a friendly working environment for web development. We will use Ubuntu 12.04 LTS Server installed in a VMware Player virtual machine. At a minimum, you need a web server (Apache, for instance), a database engine (MySQL) and PHP 5.3.3 or later.

1. Install Apache, your web server:
[crayon-5de9e247e3dd4590879254/]
and enable Apache mod-rewrite:
[crayon-5de9e247e3de1011169970/]
2, Install the MySQL Server:
[crayon-5de9e247e3de7238167919/]
3. Install PHP, the server scripting language
[crayon-5de9e247e3dec101046524/]
4. Install Intl extension:
[crayon-5de9e247e3df1951514241/]
5. Now, you need to restart Apache service:
[crayon-5de9e247e3df9937845041/]

Download and install Symfony 2.3.2

The first thing to do is to prepare a directory on your web server where you want to install the new project. Let’s call it jobeet: /var/www/jobeet.

[crayon-5de9e247e3e00738279278/]

We have a directory prepared, but what to put in it? Go to http://symfony.com/download, choose Symfony Standard 2.3.2 without vendors and download it. Now, unzip the files inside the Symfony directory to your prepared directory, jobeet.

Updating Vendors

At this point, you’ve downloaded a fully-functional Symfony project in which you’ll start to develop your own application. A Symfony project depends on a number of external libraries. These are downloaded into the vendor/ directory of your project via a library called Composer.

Composer is a dependency management library for PHP, which you can use to download the Symfony 2.3.2 Standard Edition. Start by downloading Composer onto your jobeet directory:
[crayon-5de9e247e3e06576929034/]

If you don’t have curl extension installed, you can install it using this command:
[crayon-5de9e247e3e0c055698307/]

Next, type the following command to start downloading all the necessary vendor libraries:
[crayon-5de9e247e3e11733222872/]

Web Server Configuration

A good web practice is to put under the web root directory only the files that need to be accessed by a web browser, like stylesheets, JavaScripts and images. By default, it’s recommended to store these files under the web/ sub-directory of a symfony project.

To configure Apache for your new project, you will create a virtual host. In order to do that, go to your terminal and type in the next command :
[crayon-5de9e247e3e16790440429/]
Now, a file named jobeet.local is created. Put the following inside that file, then hit Control – O and Enter to save it, then Control – X to exit the editor.
[crayon-5de9e247e3e1c451403225/]
The domain name jobeet.local used in the Apache configuration has to be declared locally. If you run a Linux system, it has to be done in the /etc/hosts file. If you run Windows, this file is located in the C:WindowsSystem32driversetc directory. Add the following line:
[crayon-5de9e247e3e21398466916/]

Replace 127.0.0.1 with the ip of your web server machine in case you are working on a remote server.

If you want this to work, you need to enable the newly created virtual host and restart your Apache. So go to your terminal and type:
[crayon-5de9e247e3e27396250272/]
Symfony comes with a visual server configuration tester to help make sure your Web server and PHP are correctly configured to use Symfony. Use the following URL to check your configuration:

http://jobeet.local/config.php

sf2-config (1)

If you don’t run this from your localhost, you should locate and open web/config.php file and comment the lines that restrict the access outside localhost:
[crayon-5de9e247e3e2c718729254/]
Do the same for web/app_dev.php:
[crayon-5de9e247e3e32446711716/]

Probably, you will get all kind of requirements when you go to config.php. Below, is a list of things to do for not getting all those “warnings”.

1. Change the permissions of app/cache and app/logs:
[crayon-5de9e247e3e38946814222/]

Install ACL if you don’t have it yet:
[crayon-5de9e247e3e3e320879599/]

2. Set the date.timezone setting in php.ini

[crayon-5de9e247e3e46556194213/]
[crayon-5de9e247e3e4b157566311/]

Find the date.timezone setting for [date] section and set it to your timezone. After that, erase “;”, placed at the beginning of the line.
3. Set the short_open_tag setting to off in the same php.ini file
[crayon-5de9e247e3e52577644481/]
4. Install and enable a PHP Accelerator (APC recommended)

[crayon-5de9e247e3e57350126201/]

After restarting Apache, open a browser window and type in http://jobeet.local/app_dev.php. You should see the following page:

Day 1 - SF_welcome

Symfony2 Console

Symfony2 comes with the console component tool that you will use for different tasks. To see a list of things it can do for you type at the command prompt:
[crayon-5de9e247e3e5d809753120/]

Creating the Application Bundle

What exactly is a bundle?

Is similar to a plugin in other software, but even better. The key difference is that everything is a bundle in Symfony 2.3.2, including both core framework functionality and the code written for your application.

A bundle is a structured set of files within a directory that implement a single feature.

Tips: A bundle can live anywhere as long as it can be autoloaded (app/autoload.php).

You can read more here: http://symfony.com/doc/current/book/page_creation.html#the-bundle-system – The Bundle System.

Creating a basic bundle skeleton

Run the following command to start the Symfony’s bundle generator:
[crayon-5de9e247e3e63465338973/]
The generator will ask you some questions before generating the bundle. Here are the questions and answers (all, except one, are the default answers):
[crayon-5de9e247e3e68861335132/]
Clear the cache after generating the new bundle with:
[crayon-5de9e247e3e87428912448/]
The new Jobeet bundle can be now found in the src directory of your project: src/Ibw/JobeetBundle. The bundle generator made a DefaultController with an index action. You can access this in your browser: http://jobeet.local/hello/jobeet or http://jobeet.local/app_dev.php/hello/jobeet.

How to remove the AcmeDemoBundle

The Symfony 2.3.2 Standard Edition comes with a complete demo that lives inside a bundle called AcmeDemoBundle. It is a great boilerplate to refer to while starting a project, but you’ll probably want to eventually remove it.

1. Type the command to delete Acme directory:
[crayon-5de9e247e3e92274024217/]
2. Go to: /var/www/jobeet/app/AppKernel.php and delete:
[crayon-5de9e247e3e98570215978/]
and now delete from app/config/routing_dev.yml:
[crayon-5de9e247e3e9d233412627/]
3. Finally, clear the cache.

The Environments

Symfony 2.3.2 has different environments. If you look in the project’s web directory, you will see two php files: app.php and app_dev.php. These files are called front controllers; all requests to the application are made through them. The app.php file is for production environment and app_dev.php is used by web developers when they work on the application in the development environment. The development environment will prove very handy because it will show you all the errors and warnings and the Web Debug Toolbar – the developer’s best friend.

That’s all for today. See you on the next day of this tutorial, when we will talk about what exactly the Jobeet website will be about!

Creative Commons License
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.