Creating pages with Symfony 4

After getting started and created your first project with Symfony 4 (visit my previous story about it by clicking here) the natural step is to create pages to be consumed by users.

With this ready to go Symfony Skeleton you can start develop in an MVC oriented way. If you are not familiar with it, MVC (TL; DR;) is a development architecture where you split the ownership in Models (the objects you manage inside your application), Views (the template layer to show the information to your consumer) and Controllers (receive and process the request to return a response).

Learning some essentials: Symfony Components

As a developer, you don’t need to go deep into the framework to show some content. You need to understand which is the workflow of receiving a request and how to send back a response. If you aren’t new with Symfony probably you already know this part so I’ll continue for those who don’t know…

Symfony Components are a bunch of single and independent PHP packages that you can use in your very own PHP applications. In fact, many other PHP frameworks/projects are using Symfony components to handle some specific parts like Laravel, Drupal, etc.…
Which Symfony Components you should learn at the very beginning?

HTTP Foundation

In my opinion the most basic Symfony Component. The documentation says:

The HttpFoundation component defines an object-oriented layer for the HTTP specification. (https://symfony.com/doc/current/components/http_foundation.html)

This component allows you to use in your application the request made to your application as an object (Request class). With this object you can get the data sent from the client (the form data, the query parameters on the URL, the headers defined…) like $request->get('userId') .
Also, you can make usage of Response / JsonResponse class objects to define the content to send to your client.

HTTP Kernel

The magician component…

The HttpKernel component provides a structured process for converting a Request into a Response by making use of the EventDispatcher component. It's flexible enough to create a full-stack framework (Symfony), a micro-framework (Silex) or an advanced CMS system (Drupal).
(https://symfony.com/doc/current/components/http_kernel.html)

As a “TL; DR;”, this component will guide your request through a workflow and returns something as soon as a Response class is created. This component will request a route match (match url with your possible application routes), parse data sent into request attributes and execute your controller logic. I really recommend you to read the documentation for this component (it has a very nice chart!).

Dependency Injection

The real Symfony engine

The DependencyInjection component implements a PSR-11 compatible service container that allows you to standardize and centralize the way objects are constructed in your application.

More than the advantages of a Dependency Injection pattern, this component allows you to have a cleaner architecture and code. With the Autowire and auto configure features, using the v4.+ the developers can just require the type of object you need to use and this component will prepare an instance and inject at your object.

Creating a page

(Obviously) A page is the content you get when you browse an URL (ex: http://google.com). That page can have just text content, forms to accept data for server-side processing, etc…
So, what do we need to create out first page?

The long answer is “you need HTTPFoundation, HTTPKernel, Router Symfony components”. I really recommend you to visit Symfony documentation and read more about these components.
The best answer is “let’s code”.

The controller

A controller is one class. Inside this controller, you will create functions that will receive a request and return one response (whatever the content be).

For our first page (our homepage), we will return a simple message. Within src/Controller folder you create your first controller IndexController.php.

<?php
namespace App\Controller;
use Symfony\Component\HTTPFoundation\Response;
class IndexController
{
  // This is an action, the function that gives you the content for
  //your page
  public function index()
  {
    return new Response('Hello world from your controller');
  }
}

The IndexController will respond to many requests. For now it contains only the index action (index function), responsible to return the message Hello world from your controller .
Now that you have an action ready to respond we still need to tell to Symfony that calling http://<site-url>/ will execute this index function. The right place to do this is the routing.

The router

The router is the component responsible for translating the request to be mapped into a bunch of configurations (http://symfony.com/doc/current/components/routing.html). The HTTPKernel will grab that configuration and find the action (function inside a Controller class) responsible to return the content. Where can you do this bind? Inside config/routes.yaml. The routes file is the way for you to describe which URLs/pages/addresses your website has.

index: 
    path: / 
    controller: App\Controller\IndexController::index

First you say your route name. As child keys of this route you define the path (the url part user is browsing at your website) and the controller (the controller and function that will be called from that URL).

How to validate that the application is getting this new route? In the console run:

$ bin/console debug:router

You can use the Symfony Console component to debug all your routes. After running the debugger, you should see one route:

------- -------- -------- ------ ------
  Name    Method   Scheme   Host   Path
 ------- -------- -------- ------ ------
  index   ANY      ANY      ANY    /
 ------- -------- -------- ------ ------

This is good! You can browse now your application and see the content showing up in your browser.

The output for this first controller > action

If you get to here without problems, congrats! You are able to create your pages!

Creating pages like a Pro

So, is very simple to create a page. You create your controller class, you add inside of it all the actions you need to, and you expose this by routes at route.yaml file.

Of course, there are other ways to do it. Not because is a best practice, but honestly depends on the your “personal taste” regarding code organisation. I prefer this way because… well, I’m lazy… So let’s code.

The Controller

Instead of manually creating a new class I’ll use the Symfony console. Please remember that if you run bin/console make: you will get a full list of “file makers”. If you followed the last story we saw how to install maker bundle, if you not, then require it with Composer.

$ bin/console make:controller

And the result, possibly will be an error. The console will warn us that we need first a new dependency, the Annotations package. This package will allow us, using the DocBlocks to describe our controller and also call other features. so…

$ composer require annotations

… and then run the console again to create the controller (I’ll do it for a PagesController)

$ bin/console make:controller
 Choose a name for your controller class (e.g. FierceGnomeController):
 > <here you will be prompted to name your controller>
created: src/Controller/<yourControllerName>.php
Success!
Next: Open your new controller class and add some pages!

so, you just created a new controller and the router already knows about it:

bin/console debug:router
 ------- -------- -------- ------ --------
  Name    Method   Scheme   Host   Path
 ------- -------- -------- ------ --------
  pages   ANY      ANY      ANY    /pages
                   ...
 ------- -------- -------- ------ --------

What about the controller code?

<?php
// path: src/Controller/PagesController.php
namespace App\Controller;
use Symfony\Component\Routing\Annotation\Route;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
class PagesController extends Controller
{
    /**
     * @Route("/pages", name="pages")
     */
    public function index()
    {
        return $this->json([
            'message' => 'Welcome to your new controller!',
            'path' => 'src/Controller/PagesController.php',
        ]);
    }
}

Comparing with our primary controller class, there’s two things we can notice very quickly.
First, out controller class is extending another Controller class. This controller class acts as a “base class” to give us more functionalities out of the box (such as call twig rendering, expose the Dependency Injection container to require all kinds of services, and much more).
The second change is the DocBlock on top of index action. Using that notation we are able to give a path and name to our route, the same we did with our route.yaml file. You don’t need to worry about which is more powerful because both have the same features, it’s all about the way you write it and where do you store them.

After you can change the index action and make it return your new Response object with your content.

Story recap

• Read some info about some main Symfony Components.
• We saw how we can create static content pages (even with a lazy way)

In the next story I’ll cover up twig and how to create dynamic content pages.