Symfony

Installation

1. Install the Symfony installer

        
            
    sudo mkdir -p /usr/local/bin
    sudo curl -LsS https://symfony.com/installer -o /usr/local/bin/symfony
    sudo chmod a+x /usr/local/bin/symfony

2. Create your local working copy

Go to your websites directory and use the symfony command to initialize your project:

        
            
    cd /path/to/your/www_directory
    symfony new website.dev

The symfony command will initialize a fresh new Symfony 3 project and install the basic dependencies.

3. Git setup

Then, you can Initialize your working copy and remote repository:

        
            
    cd /path/to/your/www_directory/website.dev
    git init
    git remote add origin [email protected]:leapt/website.git

4. Check the result in your browser

You can then edit your host file in order to be able to access the website. On Mac OS, you can open the terminal and type:

        
            sudo nano /etc/hosts

Add the following lines to the host file:

        
            127.0.0.1 website.dev

You can also add a website config in nginx:

        
            
server {
    listen 80;
    server_name website.test;
    root /var/www/website.test/public;

    location /tests/ {
        alias /var/www/website.test/tests/_html/;
        index index.html;
        fastcgi_index index.html;
    }

    error_page 503 @maintenance;
    location @maintenance {
        rewrite ^(.*)$ /maintenance.html break;
    }

    location / {
        if (-f /var/www/website.test/public/maintenance.html) {
            return 503;
        }

        try_files $uri /index.php$is_args$args;
    }

    location ~ ^/index.php(/|$) {
        fastcgi_pass unix:/run/php/php7.4-fpm.sock;
        fastcgi_split_path_info ^(.+.php)(/.*)$;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_param DOCUMENT_ROOT $realpath_root;

        internal;
    }

    location ~ .php$ {
        return 404;
    }

    proxy_buffer_size   512k;
    proxy_buffers   4 512k;
    proxy_busy_buffers_size   512k;

    client_max_body_size 20M;

    error_log /var/log/nginx/website.test_error.log;
    access_log /var/log/nginx/website.test_access.log;
}

Normally, you can then access the newly created bundle in your browser: http://website.dev/

5. Commit and push

Assuming you are still in your project directory:

        
            
    git add .
    git commit -m "Project setup"
    git push origin master

Getting a working copy

1. Clone the project

        
            
    cd ~/Sites
    git clone [email protected]:leapt/website.git website.dev

2. Install vendors

Log in into your vagrant instance, and load vendors by

        
            
    cd /var/www/website.dev
    composer install

3. Assets

        
            
    bin/console assets:install --symlink web

    # Not necessarily needed
    npm install
    bower install

4. Database setup

        
            
    # Create the database
    bin/console doctrine:database:create

    # If your project runs under Doctrine migrations, you can launch
    bin/console doctrine:migrations:migrate

    # Otherwise, update the schema by introspection
    bin/console doctrine:schema:update --force

    # And if the project has fixtures
    bin/console doctrine:fixtures:load

5. Check the result in your browser

You can then edit your host file in order to be able to access the website. On Mac OS/Linux, you can open the terminal and type:

        
            
    sudo sh -c "echo '127.0.0.1       website.dev\n::1             website.dev' >> /etc/hosts"

You can also add a website config in nginx:

        
            
server {
    listen 80;
    server_name website.test;
    root /var/www/website.test/public;

    location /tests/ {
        alias /var/www/website.test/tests/_html/;
        index index.html;
        fastcgi_index index.html;
    }

    error_page 503 @maintenance;
    location @maintenance {
        rewrite ^(.*)$ /maintenance.html break;
    }

    location / {
        if (-f /var/www/website.test/public/maintenance.html) {
            return 503;
        }

        try_files $uri /index.php$is_args$args;
    }

    location ~ ^/index.php(/|$) {
        fastcgi_pass unix:/run/php/php7.4-fpm.sock;
        fastcgi_split_path_info ^(.+.php)(/.*)$;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_param DOCUMENT_ROOT $realpath_root;

        internal;
    }

    location ~ .php$ {
        return 404;
    }

    proxy_buffer_size   512k;
    proxy_buffers   4 512k;
    proxy_busy_buffers_size   512k;

    client_max_body_size 20M;

    error_log /var/log/nginx/website.test_error.log;
    access_log /var/log/nginx/website.test_access.log;
}

Normally, you can then access the newly created bundle in your browser: http://website.dev/

Basic bundle development

This section explains the basics of how to work with Models, Views & Controllers in Symfony 3.

The goal here is not to take the place of the official Symfony documentation, but rather

  • to help you put the pieces together
  • to document the coding standard and practices

Before you dive into the next sections, please make sure you have read and understood the two following articles in the official Symfony2 documentation:

1. Creation of a base layout template

If you are not already familiar with Twig, go ahead and read the following resources:

Your first step will be to create a base layout template. You can create it in the app/Resources/views directory. Our convention is to call it base.html.twig.

Here is a sample base.html.twig template, with the blocks you will need to create:

        
            
<!DOCTYPE html>
<html>
    <head>
        <title>Page title</title>
        <meta charset="UTF-8">
        {% if app.environment == 'dev' %}
            <link rel="stylesheet" type="text/css" href="{{ asset('build/styles/main.css') }}" media="all">
            <link rel="stylesheet" type="text/css" href="{{ asset('build/styles/vendor.css') }}" media="all">
        {% else %}
            <link rel="stylesheet" type="text/css" href="{{ asset('build/styles/main.min.css') }}" media="all">
            <link rel="stylesheet" type="text/css" href="{{ asset('build/styles/vendor.min.css') }}" media="all">
        {% endif %}
        <link rel="icon" type="image/x-icon" href="{{ asset('build/images/favicon.ico') }}">
    </head>
    <body>
        {% block body %}{% endblock body %}

        {% if app.environment == 'dev' %}
            <script src="{{ asset('build/scripts/vendor.js') }}"></script>
            <script src="{{ asset('build/scripts/main.js') }}"></script>
        {% else %}
            <script src="{{ asset('build/scripts/vendor.min.js') }}"></script>
            <script src="{{ asset('build/scripts/main.min.js') }}"></script>
        {% endif %}
    </body>
</html>

2. Assets setup

As you can see in the example above, asset files (js and css) are located in a "public" directory in your app Resources folder. You will need to create that directory yourself.

We use the following structure:

  • Resources
    • public
      • fonts
      • images
      • less
      • js
      • vendor

If you need to call some javascript libraries and they can't be managed using bower/gulp, download them in the vendor directory. But keep their directory structure if it's the case.

For example:

  • vendor (folder)
    • bootstrap (folder)
    • jquery.js
    • modernizr.js
    • respond.js

Please avoid using Assetic and prefer gulp instead.

3. Controller and templates

Now, you can start the generated controller by the installation of Symfony. Usually, the first step is to have an index action in the default controller, without any parameter, to serve as the starting point of the website or application.

You can achieve that result by modifying the indexAction method and the associated @Route annotation:

        
            
    /**
     * @Route("")
     * @Template()
     */
    public function indexAction($name)
    {
        return [];
    }

You will find more information about how to use route and controllers in the following articles:

Note : The controller renders the AppBundle:default:index.html.twig template, which uses the following naming convention:

        
            bundle_name:controller_name:template_name

This is the logical name of the template, which is mapped to a physical location using the following convention:

        
            app/Resources/views/controller_name/template_name

Now, you probably would extend the base.html.twig template into child templates. The extends tag should be the first tag in the template. Simply add this line into your child template:

        
            
	{% extends "::base.html.twig" %}

If you want to print a block multiple times you can however use the block function. Define some blocks in your base.html.twig template:

        
            
	{% block title %}
	{% block body %}
	{% block stylesheets %}
	{% block javascripts %}

You will find more information about how to use the block function: Twig blocks

4. Coding standards

PSR-0 is a standard that has been adopted by some frameworks like Zend Framework 2 to facilitate the autoloading process across platforms. This is accomplished by following namespace and class naming standards that correspond to the relative location of the resource or file in question.

If you are not already familiar with PHP Specification Request, go ahead and read the following resource: PSR-0

CamelCase for Symfony entity:

When contributing code to Symfony, you must follow its coding standards. Symfony follows the standards defined in the PSR-0, PSR-1 and PSR-2 documents.

In short :

  • Use camelCase, not underscores, for variable, function and method names, arguments;
  • Use underscores for option names and parameter names;
  • Use namespaces for all classes;
  • Prefix abstract classes with Abstract. Please note some early Symfony classes do not follow this convention and have not been renamed for backward compatibility reasons. However all new abstract classes must follow this naming convention;
  • Suffix interfaces with Interface;
  • Suffix traits with Trait;
  • Suffix exceptions with Exception;
  • Use alphanumeric characters and underscores for file names;
  • Don't forget to look at the more verbose Conventions document for more subjective naming considerations.

If you need more documentation, read those articles below:

Twig coding standards

Twig is the default template engine of Symfony. Twig uses a syntax similar to the Django and Jinja template languages which inspired the Twig runtime environment.

Filters, variables and functions names are in lowercase and can be more readable by using underscore to separate parts of their name.

Example:

        
            
	{% set foo_bar = 'foo' %}

	{{ a_variable }}

	{{ 'some example text'|custom_filter(some_parameters) }}

	{{ render_my_function(some_parameters) }}

If you want to learn more about how to use Twig synthax and semantic, please visit those pages:

Translations

This section explains the basics of how to use translations in Symfony.

1. Install i18n Bundle

        
            composer require leapt/im-bundle:~1.0

2. Register bundle in AppKernel

        
            
    # in app/AppKernel.php:
    public function registerBundles()
    {
        $bundles = [
            ...
            new Leapt\I18nBundle\LeaptI18nBundle(),
        ];

3. Change site routing and add available languages

Change type of site's routing in annotation_i18n :

        
            
    # in app/config/routing.yml
    yourname_site:
        type: annotation_i18n

Add all languages needed. See example below:

        
            
    # in app/config/config.yml
    leapt_i18n:
        locales: ["fr", "nl", "en"]

4. Enabling the translation Twig filter

Remove the comment tag '#' before the translator filter on line 7:

        
            
    # in app/config/config.yml
	framework
		translator:  { fallback: %locale% }

5. Enable i18nRoute in a Controller

See example below:

        
            
    use Leapt\I18nBundle\Annotation\I18nRoute;

    class DefaultController
    {
        /**
         * @I18nRoute("/", name="app_default_index")
         */
        public function indexAction()
        {

6. Create translation files

In src/AppBundle/Resources/ create the 'translations' directory For each language, create a messages.'thechosenlanguage'.yml

Now you can structure the yml file as you will. Keep in mind to make it simple, don't use to many sub-levels. We recommend you to use only 3 levels.

For example:

        
            
	sitename: Your site name

	meta:
	    home:
	        title: Home
	    default:
	        title: Your campaign name
	        description: ...

In your twig template, simply call the translated message this way:

        
            
	{{ 'meta.home.title'|trans }}