The new era of micro frameworks, welcome Symfony 4

Whoop Whoop! Symfony 3.4 and Symfony 4 were released a couple days ago with lots of hype around it!

But what is really different this time from other Symfony versions? Let’s have a look…

Decoupling components

First off, conceptually, Symfony framework is moving towards a more decoupled structure. You probably noticed that instead of creating a new project through the symfony installer, you now use the following command.

composer create-project symfony/skeleton your-project-name

 
The reason behind this is that in earlier versions, when creating a symfony project, you were installing lots of dependencies and components that you may or may not be using in your application.

The idea now is creating a skeleton type project, and then installing all the components we need for that project seperately. This allows the programer complete freedom to be using whatever component he or she needs.

This in turn means that each Symfony application you code might use different components, even if they were created by Symfony, and therefore you do not need to install all of them every time, which makes each project more light weight!

For example, an API project might not use Twig, so there’s no need to install it in the vendor directory right?

Or I might just install the command component because I need to write some php scripts and I need a quick wrapper to organise my code.

Neither of the projects above would need twig, or form, or entities, or orm… you get the point.

I still remember the days when you had one big bloated Symfony framework installed, and many apps inside it. Inside each app, there were bundles.

After that, it evolved into one app per symfony installation, and each app had it’s different bundles.

It’s now time for the bundle less symfony. Best practices now say that you should have one skeleton per project, and following the decoupling of components, each project will have just the component it needs. This is just great, because every project will now have the underlying code that is really necessary, and not a bloated version of all the Symfony components together.

Having said this, there’s a few components I use 99% of the time when creating websites, so I created this small wrapper script so it’s easy for me to get them all, feel free to grab it and add/remove at your taste :). I call it ‘symfony-create-project.sh’

#!/bin/bash
# This script is a wrapper for creating a skeleton and installing the basic components I use most of the time
# To use it: bash symfony-create-project name-of-your-project

if [ "$1" != "" ]; then
	composer create-project symfony/skeleton "$1"
	cd "$1"
	composer require annotations
	composer require --dev profiler
	composer require twig
	composer require orm
	composer require form
	composer require form validator
else
	echo "parameter expected: name-of-your-project"
fi

Directory Structure

First thing you notice is the disappearance of the web folder. You now have the public folder instead. Inside it we can also see that app.php and app_dev.php have disappeared. Instead, we now have a more default index.php. The environment will be controlled by a .env file in the root directory of the project.

Second of all, the whole Resources folder inside src/ has disapeard as well, and all of it’s contents are in different places. The config files (routing.yml, services.yml…) are in the config/ folder in the root directory. This makes sense now since we have bundle-less applications. All of the twig files have also moved to a general templates/ folder in the root directory.

Now the src/ folder is just for php code, which makes much more sense if you work on a team with frontend and backend dev’s, each of them can now focus on their own folder.

Autoconfiguring and Autowiring

This is my absolute favourite.

Let me just copy this with the comments, as it explains everything really well.

services:
    # default configuration for services in *this* file
    _defaults:
        autowire: true      # Automatically injects dependencies in your services.
        autoconfigure: true # Automatically registers your services as commands, event subscribers, etc.
        public: false       # Allows optimizing the container by removing unused services; this also means
                            # fetching services directly from the container via $container->get() won't work.
                            # The best practice is to be explicit about your dependencies anyway.

Let’s dive into the code.

So I created a new service class,

<?php

namespace App\Utils;

use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Symfony\Component\Routing\Annotation\Route;

class NumberGenerator
{
    public function __construct()
    {
    }

    public function getRandomNumber()
    {
        return  mt_rand(0, 100);
    }
}

Injected into the action,

<?php

namespace App\Controller;

use App\Utils\NumberGenerator;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Symfony\Component\Routing\Annotation\Route;

class DefaultController extends Controller
{
    /**
     * @Route("/default/home")
     */
    public function home(NumberGenerator $numberGenerator)
    {
        return $this->render('default/home.html.twig', array(
            'number' => $numberGenerator->getRandomNumber(),
        ));
    }
}

and BANG, it worked like expected.

Let’s recapitulate here… before, we had to create the service, add it in the dependency injection config file, and then get it from the container.

What we just did in Symfony4 is create the service and inject it in the action we needed it. No configuration, no getting… just injection. This REALLY speeds up the process, enough configuration and more coding!!

However, if you don’t want to inject your service in the action, you can still use the container with the get function as we did in the past, although best practices advise not to.

Firstly,


composer require dependency-injection

Secondly, we need to set the service to public.

services:

    App\Utils\NumberGenerator:
        public: true

You can now get the service from the container

...
return $this->render('default/home.html.twig', array(
            'number' => $this->get(NumberGenerator::class)->getRandomNumber(),
        ));
...

There’s another component/bundle, which although is not super necessary, makes your life much much easier: Yup, you guessed it, it’s the Maker Bundle

composer require maker-bundle

This components creates the skeleton files for you (controllers, entities, forms,… etc), for example

bin/console make:controller CarController

More info on the maker bundle here.
More info on all the different component recipes here.

Conclusion

I just love how Symfony keeps giving more and more control to the developer.

Lots uf us (me included) know that changing and evolving things that we’re used to doing is sometimes painful… but after playing with it a little bit, I see this upgrade as a great step forward for better code, better standards and better readability.

So thank you to the Symfony team and everyone who contributed for making this happen!

Happy coding!!

Namespaces and organizing business logic services in Symfony

I want to talk about namespacing services in Symfony, specifically Symfony3.

These are exciting times, Symfony 4 is just round the corner – coming out on November 30th – so this blog post might be irrelevant soon! Nevertheless, concepts are still the same so let´s get into it!

Lately, talking with my team in SlowCode, we defined a common way of defining services.

First rule – using a folder for logic services.

Any service which provides logic to the app would be inside a App\Service folder. This way everything is tidy, and all developers in the team know where to find them.

Second rule – using a folder for the domain name

The next layer is the domain name. This is again, to provide order. You might not think so, but when you end up with 8 domain names, and 2-3 services in each one, then things can get uggly if it’s not tidy 🙂

So for instance, let’s have a service that is related to Stock called StockAvailability, the service would end up with the namespace the folder AppBundle\Service\Stock\StockAvailability

Third rule – using . for folder separation and _ for word separation

The id of the service has to be separated by . when you enter into a new folder, and separated by _ when it’s more than one word.

So in the previous example, we would define the whole thing like so:

services:

    app.service.stock.stock_availability:
        class: AppBundle\Service\Stock\StockAvailability
        arguments:
            - '@doctrine.orm.entity_manager'
            ...

Lately in Symfony 3.3, a new way of defining services was brought up.

It´s now a good practice to define the id of the service with the full qualified name. So, instead of defining it like we did before, we would define it like so:

services:

    AppBundle\Service\Stock\StockAvailability:
    	public: true
        arguments:
            - '@doctrine.orm.entity_manager'
            ...

Declared like this, you can still get the service from the service container (with the new id of course, the full class name)

use AppBundle\Service\Stock\StockAvailability

public function fooAction(Request $request)
{
    // before Symfony 3.3, you would get it like so
    // $stockService = $this->get('app.service.stock.stock_availability');

    // in Symfony 3.3, you can get it like so
    // This is only available if you defined your service as public
    $stockService = $this->get(StockAvailability::class);
}

As Symfony’s official page point out, it’s a good practice to define your services as private, not public, and then inject any service you may need in the action inside the controller, instead of getting it from the service container (similar to the dependency injection inside services), for instance

use AppBundle\Service\Stock\StockAvailability

public function fooAction(Request $request, StockAvailability $stockService) { 
    // now we have it injected into our variable $stockService 
    // so we don't need to get it from the container 
} 

So first off, I think the id with the full class name instead of an invented nomenclature is a good thing. At least there will be no more confusion amongst different devs from the team.

About private/public services. I understand where Symfony is going, and I think restricting by ‘injecting’ instead of ‘getting’ makes code more robust, and probably more readable in the end. However, I still think there’s an upside on how things were prior to 3.3 version. Getting services from the container is VERY useful, and provices flexibility and speed.

I think that since you can still define public services, that’s what I’ll keep doing… what will you do?

More info here:
Symfony service container
Symfony 3.3 best practices
Symfony class for service id

Symfony PHPUnit testing database data

Today I had to test some complex algorithm logic we’re writing for a client app. The algorithm I want to test interacts with the DDBB several times through query builders and repositories, so it’s necessary to test this database access, as we need to know the sql queries give the right data also.

It’s the first time I set up a test environment (I worked with Unit Testing before, but never set up the env from scratch). So after reading a bit of doc from the internet, I set up the unit test environment, then wrote some tests that interacted with a test database and test fixtures.

I’ve put together a bit of guide for anyone wanting to get started on this.

Step 1 – Setting a separate database for testing.

Add these lines on your config_test.yml file.


#config_test.yml

...

# Doctrine Configuration
doctrine:
    dbal:
        driver:   pdo_mysql
        host:     "%test_database_host%"
        port:     "%test_database_port%"
        dbname:   "%test_database_name%"
        user:     "%test_database_user%"
        password: "%test_database_password%"
        # Workaround for DBAL 2.5 auto-detect -> with server_version allows to doctrine:database:create
        server_version: 5.6 # your database server version here

This will point to the new test database.

Then add the data in parameters.yml (don’t forget parameters.yml.dist for future installs)


# This file is auto-generated during the composer install
parameters:

    ...

    test_database_host: localhost
    test_database_port: null
    test_database_name: test_db_name
    test_database_user: test_db_user
    test_database_password: test_db_pw

Step 2 – Creating a TestCase that we will extend when ddbb fixtures are needed.

This is useful for reusing code, instead of writing it on every file. It also makes all the fixture tests more consistent.

class DataFixtureTestCase extends WebTestCase
{
    /** @var  Application $application */
    protected static $application;

    /** @var  Client $client */
    protected $client;
    
    /** @var  ContainerInterface $container */
    protected $container;

    /** @var  EntityManager $entityManager */
    protected $entityManager;

    /**
     * {@inheritDoc}
     */
    public function setUp()
    {
        self::runCommand('doctrine:database:drop --force');
        self::runCommand('doctrine:database:create');
        self::runCommand('doctrine:schema:create');
        self::runCommand('doctrine:fixtures:load --append --no-interaction --fixtures=tests/AppBundle/DataFixtures/ORM');

        $this->client = static::createClient();
        $this->container = $this->client->getContainer();
        $this->entityManager = $this->container->get('doctrine.orm.entity_manager');

        parent::setUp();
    }

    protected static function runCommand($command)
    {
        $command = sprintf('%s --quiet', $command);

        return self::getApplication()->run(new StringInput($command));
    }

    protected static function getApplication()
    {
        if (null === self::$application) {
            $client = static::createClient();

            self::$application = new Application($client->getKernel());
            self::$application->setAutoExit(false);
        }

        return self::$application;
    }
    
    /**
     * {@inheritDoc}
     */
    protected function tearDown()
    {
        self::runCommand('doctrine:database:drop --force');

        parent::tearDown();

        $this->entityManager->close();
        $this->entityManager = null; // avoid memory leaks
    }
}

Most of the code is taken from StackOverflow.

This will create the database and install the fixtures on every test that extends this TestCase. This is important as you want a consistent database with the same data every time!

It’s also important to pass the parameter

--fixtures=tests/AppBundle/DataFixtures/ORM'

This way you can set up all your test fixtures separate from your app fixtures, which will stay clean.

Step 3 – Creating the unit, functional and integration tests

After creating your test fixtures, now you can test your services logic easily by extending the TestCase we just created, like so.

class FooTest extends DataFixtureTestCase
{
    protected $fooService;

    /**
     * {@inheritDoc}
     */
    public function setUp()
    {
        parent::setUp();
        $this->fooService = $this->container->get('app.service.foo');
    }

    public function testFooTrue()
    {

        ... 
        //custom logic
        ... 

        $this->assertEquals(true, $value);
    }

  
}

And that’s all you need! Happy testing! 🙂

PS: This is a very easy way to get started. For more complex testing environment settings, you can try LiipFunctionalTestBundle

Deploy on OVH shared hosting with different PHP versions

Recently we’ve been working on a Symfony project that needed to be deployed on a shared hosting by OVH.

This server was running PHP 5.4 and we could not upgrade it because they had some legacy projects that needed to remain..

So after banging our head quite a few times, we found out that you could create a configuration file so that OVH server reads and reconfigures the settings of the server for that project/folder only.

The file must be called .ovhconfig and it must be on the target folder the DNS points to, so in our case being a Symfony project it should be in the /web folder

app.engine=php
app.engine.version=5.6
http.firewall=none
environment=production
container.image=stable

PHP 5.6 and PHP 7 on same Mac with Liip

So the other day I wanted to upgrade to php7 but didn’t want to completely remove php56 as I still have legacy projects to maintain and I’m not ‘dockerized’ yet..

You can install php with liip here.

Liip doesn’t overwrite Apple’s php binaries, it installs it under a php5 folder under /usr/local/php5 and then creates the link.

All you now need is this handy bash script to switch from one php version to the other.

#!/bin/bash

#usage:
#./switch-php.sh 
#./switch-php.sh php5
#./switch-php.sh php7

#activate php56
if [ "$1" == "php5" ]; then
   sudo rm /usr/local/php5
   sudo ln -s /usr/local/php5-5.6.29-20170114-210819 /usr/local/php5
   sudo pkill php-fpm && sudo php-fpm
   echo "activated php5;"
   sudo apachectl restart
elif [ "$1" == "php7" ]; then
   sudo rm /usr/local/php5
   sudo ln -s /usr/local/php5-7.1.9-20170914-100859 /usr/local/php5
   sudo pkill php-fpm && sudo php-fpm
   echo "activated php7;"
   sudo apachectl restart
else
   echo "parameter expected: php5 | php7"
fi

PS: You’ll have to obviously adapt the version to the one you installed!