Jérémy DECOOL (@jdecool), Ingénieur Etudes et Développement à Lyon

Profilez vos tests PHPUnit avec OpenTelemetry

Mon, 01 Jun 2026 00:00:00 +0200

Un projet de développement informatique qui grossit, c’est une base de code qui grossit par la même occasion et la batterie de tests qui évolue en conséquence. On ajoute des tests semaine après semaine, les temps d’exécution s’allongent. Et puis, à un moment, la CI s’arrête net: Allowed memory size exhausted. Le premier réflexe est alors d’augmenter la mémoire allouée à PHP. Et ce cycle peut continuer un certain temps, jusqu’au moment où l’on atteint des seuils critiques.

Je l’ai rencontré dans plusieurs expériences professionnelles. Corriger des problèmes de mémoire est compliqué et l’outillage restreint. On est donc aveugle, on ne sait pas quels tests consomment de la mémoire, lesquels prennent du temps à s’exécuter. Monitorer une application en production est une bonne pratique, pourquoi n’en serait-il pas de même pour nos tests ?

Pour l’observabilité de nos applications de production, un standard est en train de s’imposer: OpenTelemetry. Pourquoi, alors, ne pas utiliser ce dernier pour également suivre ce qu’il se passe sur nos tests: produire des traces et des métriques que nous pourrions analyser ?

Il existe d’ailleurs une bibliothèque pour intégrer de l’observabilité dans nos tests PHPUnit avec OpenTelemetry: flow-php/phpunit-telemetry-bridge. Il s’agit d’une extension PHPUnit qui collecte la télémétrie de votre suite de tests et l’exporte vers n’importe quel backend compatible OTLP.

Pour l’installer, rien de plus simple:

composer require --dev flow-php/phpunit-telemetry-bridge

Il restera ensuite à ajouter la configuration nécessaire dans PHPUnit:

<?xml version="1.0" encoding="UTF-8"?>
<phpunit>
    <!-- ... -->
    <extensions>
        <bootstrap class="Flow\Bridge\PHPUnit\Telemetry\TelemetryExtension">
            <parameter name="service_name" value="phpunit-opentelemetry"/>
            <parameter name="transport" value="curl"/>
            <parameter name="endpoint" value="http://localhost:4318"/>
            <parameter name="emit_traces" value="true"/>
            <parameter name="emit_metrics" value="true"/>
            <parameter name="emit_test_spans" value="true"/>
            <parameter name="emit_test_case_spans" value="true"/>
            <parameter name="curl_connect_timeout_ms" value="1000"/>
            <parameter name="curl_timeout_ms" value="2000"/>
        </bootstrap>
    </extensions>
</phpunit>

Une fois configuré, il ne reste plus qu’à lancer vos tests, les données de télémétrie seront automatiquement envoyées, vous permettant ensuite de les visualiser dans des tableaux de bord.

On y retrouvera chaque suite de tests avec le détail de chaque test: sa durée, son empreinte mémoire, son statut.

Quelques points d’attention néanmoins. Instrumenter chaque test a un coût. Cela ne sera pas forcément intéressant sur une petite suite de test. C’est surtout lorsque le projet commence à grossir que ce type de donnée a de la valeur et que vous souhaitez arrêter de naviguer à l’aveugle.

Et si vous désirez en savoir plus, n’hésitez pas à consulter la documentation de l’outil.

Faire des requêtes CTE avec Doctrine ORM en PHP

Sat, 09 May 2026 00:00:00 +0200

J’ai déjà évoqué sur ce blog que le développement “moderne” avec les ORM masque les fonctionnalités avancées des SGBD au point que dorénavant les développeurs ne maitrisent et ne connaissent guère plus que le classique SELECT ... FROM ... WHERE ....

Dans les mécanismes méconnus et qui pourtant, pourrait permettre de soulager certains traitements applicatifs, on retrouve les CTE (Common Table Expressions). Voyons comment les utiliser avec Doctrine ORM en PHP.

Commençons par expliquer ce qu’est une CTE. Il s’agit d’une sous-requête utilisable comme une table temporaire. C’est une technique utile pour décomposer des requêtes complexes, éviter la duplication de sous-sélections ou écrire des requêtes récursives.

En presque 20 ans d’expérience professionnelle, j’ai très rarement eu l’occasion d’en voir dans le code que je peux être amené à parcourir quotidiennement. Prenons par exemple, un blog où les articles sont rattachés à des catégories, ces dernières organisées sous forme arborescente sous la forme Category(id, label, parent_id). Je suis certain que, si l’on demande à un développeur de récupérer toutes les catégories parentes d’une catégorie précise, ce dernier fera le traitement en PHP avec un code ressemblant au suivant:

// src/Repository/CategoryRepository.php
class CategoryRepository extends ServiceEntityRepository
{
    // ...

    /**
     * @return list<Category>
     */
    function getCatagoriesWithParents(int $categoryId): array
    {
        $category = $this->categoryRepository->find($categoryId);

        $categories = [
            $category,
        ];

        while ($parent = $category->getParent()) {
            $categories[] = $parent;
        }

        return $categories;
    }
}

L’inconvénient majeur ici est qu’en interne, Doctrine va faire une requête à chaque tour de boucle. C’est ce que l’on appelle le problème N+1. Pour résoudre ce problème, via une requête SQL, il n’est pas possible de faire un simple SELECT ... FROM ... WHERE, c’est exactement dans ce cas qu’une CTE récursive est utile. Cette dernière peut être écrite de la manière suivante:

WITH RECURSIVE cte_category AS (
    -- point de départ
    SELECT id, label, parent_id, 0 AS depth
    FROM category
    WHERE id = :id

    UNION ALL

    -- récursivité
    SELECT c.id, c.label, c.parent_id, cp.depth + 1
    FROM category c
    INNER JOIN cte_category cp ON c.id = cp.parent_id
)
SELECT id, label, parent_id FROM cte_category
ORDER BY depth DESC

La requête commence par récupérer la catégorie identifiée par :id, puis se joint récursivement à elle-même en remontant via parent_id jusqu’à ce qu’il n’y ait plus de parent. La colonne depth permet ensuite de trier du plus ancien ancêtre jusqu’à la catégorie cible.

Le problème pour faire cette requête avec un ORM tel que Doctrine, c’est que ce dernier ne permet pas de gérer les CTE nativement au travers de son QueryBuilder ni même en DQL. Il est alors nécessaire de passer par une requête native où le résultat final sera mappé sur un objet.

// src/Repository/CategoryRepository.php
class CategoryRepository extends ServiceEntityRepository
{
    // ...

    public function findAllWithParents(int $categoryId)
    {
        $rsm = new ResultSetMappingBuilder($this->getEntityManager());
        $rsm->addRootEntityFromClassMetadata(Category::class, 'c');

        $sql = <<<SQL
            WITH RECURSIVE with_categories AS (
                SELECT id, label, parent_id, 0 AS depth
                FROM category
                WHERE id = :id

                UNION ALL

                SELECT c.id, c.label, c.parent_id, cp.depth + 1
                FROM category c
                INNER JOIN with_categories cp ON c.id = cp.parent_id
            )
            SELECT id, label, parent_id FROM with_categories
            ORDER BY depth DESC
        SQL;

        return $this->getEntityManager()
            ->createNativeQuery($sql, $rsm)
            ->setParameter('id', $categoryId)
            ->getResult();
    }
}

Dans le code précédent, le ResultSetMappingBuilder se charge de faire correspondre les colonnes retournées avec les propriétés de l’entité Category. On obtient alors en sortie une liste d’instances de Category ordonnés de la racine jusqu’à la catégorie demandée.

Avec ce type de requête, on peut faire énormément de choses, il est par exemple, possible de récupérer tous les articles appartenant à une catégorie enfant en réutilisant la requête précédente:

WITH RECURSIVE category_path AS (
    SELECT id, label, parent_id
    FROM category
    WHERE id = :id

    UNION ALL

    SELECT c.id, c.label, c.parent_id
    FROM category c
    INNER JOIN category_path cp ON c.id = cp.parent_id
)
SELECT a.id, a.title, a.category_id
FROM article a
INNER JOIN category_path cp ON a.category_id = cp.id
ORDER BY a.published_date DESC

En une seule requête, on récupère tous les articles liés à la catégorie cible ou à n’importe lequel de ses ancêtres. Sans CTE récursive, il faudrait soit faire plusieurs requêtes successives pour parcourir la hiérarchie une approche bien moins efficace. Un point d’attention néanmoins, étant donné que l’on exécute une requête SQL native, il faudra faire attention à la portabilité de cette dernière, les CTE pouvant ne pas être disponible sur toutes les bases de données supportées par Doctrine.

De plus, l’utilisation du ResultSetMappingBuilder nécessite que le SELECT de la requête contienne l’ensemble des colonnes nécessaire à l’alimentation de l’objet. À défaut, l’entité sera hydratée de manière incomplète sans qu’aucune erreur explicite ne soit levée.

Simplifier vos objets immuables avec PHP 8.5

Mon, 16 Feb 2026 00:00:00 +0100

PHP 8.5 a été publié le 20 novembre 2025 et, dans les nouvelles fonctionnalités proposées par cette version, on trouve notamment la possibilité de mettre à jour des propriétés lors du clonage d’objets. Une amélioration qui va permettre de simplifier nos objets immuables.

En programmation orientée objet, un objet immuable est un objet dont l’état ne peut pas être modifié après sa création. Ainsi, toute “modification” visant à changer l’état de ce dernier conduit à la création d’une nouvelle instance avec les valeurs mises à jour. Cela représente un réel avantage, car leur état ne changeant jamais, les effets de bord et bugs liés à des modifications inattendues de l’objet sont ainsi limités.

Avant PHP 8.5, la modification d’un objet immuable pouvait s’avérer fastidieuse, car il était nécessaire de créer une nouvelle instance avec les nouvelles valeurs. Cela pouvait être d’autant plus contraignant si l’objet avait de nombreuses propriétés.

Par exemple:

readonly class GPSLocation
{
    public function __construct(
        public float $latitude,
        public float $longitude,
        public float $altitude,
        public DateTimeImmutable $timestamp,
    ) {
    }

    public function withCoordinates(float $latitude, float $longitude): GPSLocation
    {
        return new GPSLocation(
            $latitude,
            $longitude,
            $this->altitude,
            $this->timestamp,
        );
    }

    public function withAltitude(float $altitude): GPSLocation
    {
        return new GPSLocation(
            $this->latitude,
            $this->longitude,
            $altitude,
            $this->timestamp,
        );
    }
}

PHP 8.5 nous permet de simplifier cette opération en permettant de cloner l’objet tout en autorisant de mettre à jour certaines propriétés lors du clonage. Seules les propriétés devant être modifiées doivent être précisées:

readonly class GPSLocation
{
    public function __construct(
        public float $latitude,
        public float $longitude,
        public float $altitude,
        public DateTimeImmutable $timestamp,
    ) {
    }

    public function withCoordinates(float $latitude, float $longitude): GPSLocation
    {
        return clone($this, [
            'latitude' => $latitude,
            'longitude' => $longitude,
        ]);
    }

    public function withAltitude(float $altitude): GPSLocation
    {
        return clone($this, [
            'altitude' => $altitude,
        ]);
    }
}

Testez votre documentation OpenAPI (avec PHP)

Mon, 28 Jul 2025 00:00:00 +0200

Il n’y a rien de plus frustrant que d’utiliser une API qui ne se comporte pas de la manière qui est décrite dans sa documentation. Nombreux sont les développeurs ayant déjà vécu cette situation. Et pour cause, maintenir une documentation précise et à jour peut s’avérer être une tâche complexe et laborieuse (et ce, même si cette dernière est générée automatiquement). Pour éviter ces désagréments, il est primordial de pouvoir comparer ce qui est décrit dans la documentation avec le comportement réel du code.

Dans le cadre d’une API, une partie de ce travail consiste à s’assurer de la conformité de la documentation OpenAPI. Une solution pouvant être mise en place consiste à intégrer la validation et la vérification de la documentation au sein de tests fonctionnels. L’objectif de cette approche est de vérifier que la requête HTTP effectuée, ainsi que la réponse retournée lors du test correspondent à ce qui est spécifié. Ainsi, si les tests s’exécutent à chaque modification du code, cela permettra de garantir que l’API se comporte bien tel que décrit dans la documentation OpenAPI tout au cours de la vie du projet.

Pour mettre en place ces tests dans un projet PHP, j’utilise généralement la bibliothèque league/openapi-psr7-validator qui permet de valider des requêtes et réponses HTTP par rapport à une spécification OpenAPI.

Pour faciliter leur intégration dans vos bases de code, je recommande généralement d’utiliser une classe abstraitre pour mutualiser le code de vérification nécessaire et qui sera dédié aux tests de l’API. Cela pourrait ressembler au code suivant:

// ...
use Symfony\Bundle\FrameworkBundle\KernelBrowser;
use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;

abstract class ApiTestCase extends WebTestCase
{
    protected static KernelBrowser $client;

    protected function setUp(): void
    {
        parent::setUp();

        static::$client = static::createClient();
    }

    protected function makeRequest(
        string $method,
        string $uri,
        array $parameters = [],
        array $files = [],
        array $server = [],
        ?string $content = null,
        bool $changeHistory = true,
    ): Response {
        static::$client->request($method, $uri, $parameters, $files, $server, $content, $changeHistory);
        $response = static::$client->getResponse();

        // TODO: insérer le code de validation de la requête
        // TODO: insérer le code de validation de la réponse

        return $response;
    }
}

Le code précédent est basé sur l’utilisation du framework Symfony, mais sa logique est universelle. L’idée étant d’avoir une méthode dans laquelle on puisse faire un appel HTTP, récupérer la requête HTTP effectuée ainsi que la réponse retournée afin de pouvoir effectuer des contrôles sur ces dernières.

Ajoutons maintenant le code permettant d’effectuer la vérification des données avec la spécification OpenAPI.

// ...
use League\OpenAPIValidation\PSR7\OperationAddress;
use League\OpenAPIValidation\PSR7\ValidatorBuilder;
use Nyholm\Psr7\Request as Psr7Request;
use Nyholm\Psr7\Response as Psr7Response;

abstract class ApiTestCase extends WebTestCase
{
    private const OPENAPI_SPECIFICATION_FILE = '/path/to/specification.json';

    private static ?ValidatorBuilder $validatorBuilder = null;

    // ...

    protected function makeRequest(
        // ...
        bool $enableOpenApiSpecificationRequestCheck = true,
        bool $enableOpenApiSpecificationResponseCheck = true,
    ): Response {
        // ...

        if ($enableOpenApiSpecificationRequestCheck) {
            $this->validateOpenApiRequestSpecification($method, $uri, static::$client->getRequest());
        }

        if ($enableOpenApiSpecificationResponseCheck) {
            $this->validateOpenApiResponseSpecification($method, $uri, static::$client->getResponse());
        }

        return $response;
    }

    private function validateOpenApiRequestSpecification(string $method, string $endpoint, Request $request): void
    {
        $validator = $this->getValidatorBuilder()->getRequestValidator();
        $validator->validate(
            new Psr7Request(strtolower($method), $endpoint, $request->headers->all(), $request->getContent()),
        );
    }

    private function validateOpenApiResponseSpecification(string $method, string $endpoint, Response $response): void
    {
        $validator = $this->getValidatorBuilder()->getResponseValidator();
        $validator->validate(
            new OperationAddress($endpoint, strtolower($method)),
            new Psr7Response($response->getStatusCode(), $response->headers->all(), (string) $response->getContent()),
        );
    }

    private function getValidatorBuilder(): ValidatorBuilder
    {
        return self::$validatorBuilder ??= new ValidatorBuilder()->fromJsonFile(self::OPENAPI_SPECIFICATION_FILE);
    }
}

De cette manière, à chaque appel à votre API, vous avez la possibilité de vérifier la documentation qui lui est associée. Vous remarquerez au passage qu’il est possible de désactiver la vérification soit de la requête soit de la réponse. Si la désactivation de la vérification de la réponse peut-être discutable, pouvoir désactiver la vérification de la requête est indispensable pour pouvoir tester les cas d’erreurs avec des appels HTTP invalides (afin de pouvoir tester le comportement d’un client qui effectuerait un mauvais appel).

L’intégration de la validation OpenAPI dans vos tests fonctionnels vous permettra de faire “d’une pierre deux coups”: vous aurez la possibilité d’écrire des tests fonctionnels pour tester le comportement de votre code tout en permettant d’assurer sa cohérence avec votre documentation. Cette approche renforcera la qualité de votre API et évitera des désagréments auprès de vos utilisateurs. N’hésitez pas à adapter cette méthode à votre contexte et les différents frameworks que vous utilisez.

Évaluez la qualité de vos tests avec les tests de mutation

Sun, 11 May 2025 00:00:00 +0200

Très souvent, lorsque l’on souhaite mettre en place des indicateurs sur les tests d’un projet, la première mesure que l’on va mettre en place est celle de la couverture de code. Et pour beaucoup, il s’agit de la métrique principale permettant d’avoir une idée de qualité des tests d’un projet. Cette dernière sous-entend que plus la couverture est élevée et plus les tests assurent la sécurité du fonctionnement de notre code. Il s’agit pourtant d’un indicateur qui peut être trompeur.

Il s’agit d’un sujet que j’ai déjà abordé dans ce blog, expliquant que ce n’est pas parce qu’un test exécute une ligne de code que la vérification du comportement associé est efficace et pertinente. C’est dans ce cadre-là, qu’il est possible de mettre en place des tests de mutation (du mutation testing en anglais).

Les tests de mutation introduisent volontairement des défauts dans le code source d’un projet dans le but de vérifier si les tests permettent de détecter les changements de comportement introduits. Ces “défauts” sont appelés des “mutants” (d’où le nom de tests de mutation) et correspondent à des modifications mineures du code tentant de simuler des erreurs de programmation courantes. À la suite de l’exécution de ces tests, un score de mutation est retourné. Ce dernier représente le pourcentage de mutants tués. Plus le score est élevé, plus les tests sont efficaces pour détecter les erreurs.

Parmi les mutations les plus courantes, on retrouve:

le remplacement des opérateurs mathématiques: un + qui devient un -,
la modification des opérateurs de comparaison: une condition d’égalité === qui devient une négation !==,
la suppression de lignes de code,
la modification des valeurs booléennes: un true qui devient false,
la modification de valeurs de retour dans les fonctions.

Les tests de mutation permettent alors d’évaluer la capacité des tests à détecter des erreurs et pas simplement à exécuter du code. Ils mettent en évidence les parties du code où les tests sont insuffisants ou inefficaces. Cela permet ainsi d’ajouter des tests aux endroits les plus pertinents. Au final, ils permettent d’améliorer la confiance envers la suite de tests.

En PHP, l’outil le plus connu pour cela est certainement Infection. Ce dernier supporte PHPUnit, PhpSpec et Codeception, nécessite PHP 7.4 au minimum avec au moins une des extensions suivantes: Xdebug, phpdbg ou pcov installée. Son installation est extrêmement simple, puisqu’il suffira de faire un composer require --dev infection/infection. Une configuration de base sera automatiquement créée au premier lancement d’Infection permettant un démarrage extrêmement rapide.

Prenons un exemple simple pour illustrer le principe. Une classe Calculator qui permet d’effectuer des opérations de calcul:

class Calculator
{
    public function add(int $x, int $y): int
    {
        return $x + $y;
    }

    public function divide(int $x, int $y): float
    {
        if ($y === 0) {
            throw new \InvalidArgumentException('Division by zero is not allowed.');
        }

        return $x / $y;
    }
}

Cette classe est associée aux tests suivants:

use PHPUnit\Framework\TestCase;

final class CalculatorTest extends TestCase
{
    public function testAdd(): void
    {
        $addition = new Calculator();

        $result = $addition->add(2, 3);

        $this->assertEquals(5, $result);
    }

    public function testDivide(): void
    {
        $addition = new Calculator();

        $result = $addition->divide(6, 2);

        $this->assertEquals(3, $result);
    }
}

En lançant les tests de mutation (via la commande vendor/bin/infection), nous obtenons le rapport suivant:

Metrics:
   Mutation Score Indicator (MSI): 71%
   Mutation Code Coverage: 85%
   Covered Code MSI: 83%

Le Mutation Score Indicator représente le pourcentage de mutants tués par rapport au nombre total de mutants générés. Un mutant tué correspond à au moins un test qui échoue après l’application d’un mutant. Elle constitue la métrique principale des tests de mutation. Elle qui permet de mesurer l’efficacité des tests à détecter des erreurs. Le score doit alors être le plus élevé possible.

Le Mutation Code Coverage correspond au pourcentage de code parcouru par les tests de mutation. Cette métrique est similaire à la couverture de code “classique”, mais du point de vue des mutations.

La dernière métrique, le Covered code MSI est un calcul effectué uniquement sur le code couvert par les tests. Elle permet notamment d’isoler l’efficacité des tests existants. Cet indicateur répond à la question: “Parmi le code que mes tests exécutent, quelle est leur efficacité à détecter des erreurs”. Cet indicateur permet de détecter si vos tests sont suffisamment présents (indicateur élevé) ou si ces derniers ne permettent pas de détecter les problèmes de manière efficace (indicateur bas).

Pour améliorer le score des tests de mutation et par rebond la qualité de vos tests en général, il faudra tester tous les chemins d’exécution de votre code (incluant les cas limites et les exceptions). De plus, il ne faut pas se contenter de tester les cas nominaux, il est important de tester les cas d’erreurs.

Par exemple dans les tests que nous avons écrit précédemment, nous n’avons pas testé le cas d’erreur de la division par zéro. Modifions le code précédent, pour ajouter ce dernier:

use PHPUnit\Framework\TestCase;

final class CalculatorTest extends TestCase
{
    public function testAdd(): void
    {
        $addition = new Calculator();

        $result = $addition->add(2, 3);

        $this->assertEquals(5, $result);
    }

    public function testDivide(): void
    {
        $addition = new Calculator();

        $result = $addition->divide(6, 2);

        $this->assertEquals(3, $result);
    }

    public function testDivideByZero(): void
    {
        $addition = new Calculator();

        $this->expectException(\InvalidArgumentException::class);
        $this->expectExceptionMessage('Division by zero is not allowed.');

        $addition->divide(6, 0);
    }
}

Nous obtenons alors le résultat ci-dessous:

Metrics:
   Mutation Score Indicator (MSI): 100%
   Mutation Code Coverage: 100%
   Covered Code MSI: 100%

Si mettre en place un calcul de la couverture de code de vos tests est un bon premier point, si vous souhaitez aller plus loin et avoir une métrique pertinente pour avoir une idée de la qualité de vos tests, les tests de mutation sont une très bonne approche. Vous aurez alors les outils pour identifier et combler les “trous” de vos tests. Et comme toute solution, il sera nécessaire de prêter attention à quelques points.

Tout d’abord, il est important de noter que les tests de mutation sont des tests qui sont coûteux en termes de performance. La création et la mise en place de mutants sont consommatrices de ressources de calcul et de temps d’exécution. La génération de mutants peut ne pas être parfaite et peut ne pas changer le comportement observable du code. Dans ce dernier cas de figure, les mutants ne peuvent être tués, faussant ainsi le calcul final. On parle alors de “mutants équivalents”. Ces derniers entraînent alors de faux positifs, car ils ne changent pas réellement le comportement attendu.

Les constructeurs nommés comme alternative aux constructeurs multiples en PHP

Mon, 20 Jan 2025 00:00:00 +0100

En PHP et, contrairement à d’autre langage, il n’est pas possible d’avoir plusieurs constructeurs dans une classe. Pouvoir définir plusieurs constructeurs peut-être intéressants dans de nombreux cas, comme par exemple, pouvoir construire un objet à partir de différents types de données. Si cela n’est pas possible en PHP, il est possible d’utiliser des constructeurs nommés pour avoir un fonctionnement similaire.

Mais qu’est-ce qu’un constructeur nommé? Il s’agit d’une méthode statique que l’on va pouvoir appeler afin de construire une instance de classe. Ces méthodes ont l’avantage d’être potentiellement plus explicites que le constructeur de base parce qu’elles vont pouvoir ajouter une sémantique lors de la construction de notre objet.

Prenons un premier exemple:

readonly class Color
{
    public function __construct(
        public int $red,
        public int $blue,
        public int $green,
    ) {}
}

Le code précédent définit un objet permettant de stocker une couleur. Cette dernière est composant d’un niveau de rouge, de bleu et de vert. Le constructeur principal permet ainsi de renseigner les valeurs correspondantes. Mais dans certains cas d’utilisation, nous pourrions avoir envie de créer une couleur depuis sa valeur hexadécimale. Pour cela, nous pouvons imaginer introduire un constructeur nommé fromHexCode pour réaliser cette tâche:

readonly class Color
{
    public static function fromHexCode(string $code): self
    {
        $code = ltrim($code, '#');

        $red = hexdec(substr($code, 0, 2));
        $blue = hexdec(substr($code, 2, 2));
        $green = hexdec(substr($code, 4, 2));

        return new self($red, $blue, $green);
    }

    public function __construct(
        public int $red,
        public int $blue,
        public int $green,
    ) {}
}

Les utilisations de constructeur nommé sont multiples et permettent de simplifier la création d’objets, de fournir des valeurs par défaut en fonction d’un contexte d’utilisation tout en encapsulant la logique de création potentiellement complexe au sein de l’objet lui-même. Cela améliore ainsi la lisibilité et la compréhension du code.

C’est également une technique appréciée en Domain Driven Design pour expliciter le processus métier qui a conduit à la création de la donnée. Prenons par exemple la création d’un utilisateur dans une application, nous pourrions imaginer la modélisation suivante:

class User
{
    public static function fromRegistration(string $name, string $email, string $password): self
    {
        $user = new self($name, $email, $password);

        // additionnal business logic related to registration

        return $user;
    }

    public static function fromSocialLogin(string $name, string $email): self
    {
        $user = new self($name, $email);

        // additionnal business logic related to social login

        return $user;
    }

    private function __construct(
        public string $name,
        public string $email,
        public ?string $password = null,
    ) {}
}

Ce dernier exemple définit une classe User avec un constructeur privé. Pour pouvoir créer une instance de notre objet, il sera nécessaire d’utiliser un des constructeurs nommés définis dans cette même classe. Le constructeur nommé à utiliser se fera en fonction du contexte métier dans lequel le traitement est effectué. Il y a ici un réel avantage à utiliser cette méthodologie, car elle permet de voir les éléments nécessaires à la création de notre utilisateur en fonction de l’action effectuée dans l’application.

Car si un utilisateur se doit d’avoir un nom, un email et potentiellement un mot de passe, le code précédent rend visible le fait qu’il est obligatoire de renseigner toutes ces informations dans le cas d’un enregistrement de l’utilisateur depuis notre projet, alors que le mot de passe n’est pas nécessaire dans le cas d’une connexion d’un réseau social.

Le concept de constructeur nommé est très puissant et peut se révéler extrêmement utile pour la maintenance et la compréhension d’une base de code. Le principe a été très brièvement introduit dans cet article et je vous recommande vivement de vous y intéresser plus en profondeur, ces derniers étant bien souvent sous-exploités.

Écrire une API idempotente (exemple en PHP avec Symfony)

Mon, 13 Jan 2025 00:00:00 +0100

D’après la RFC 9110 qui spécifie la sémantique d’une requête HTTP, une requête est considérée comme idempotente si elle peut être effectuée plusieurs fois et obtenir un résultat identique lors de chaque appel. Par exemple, si l’on tente d’accéder à une ressource REST GET /resource/42, deux appels à cet endpoint retourneront toujours le même résultat. Les appels GET à une API REST sont alors considérés comme idempotents (il en va de même pour des appels PUT ou DELETE par exemple). Mais ce n’est pas le cas d’un appel POST /resource qui créera alors une nouvelle ressource à chaque appel. Nous allons voir dans ce billet comment rendre un appel POST idempotent.

Pour rendre une API idempotente, il va falloir être en mesure d’identifier de manière unique un appel à une ressource. Généralement, le client API va générer une clé unique et l’ajouter à l’appel effectué. La clé est ensuite vérifiée par le serveur pour qu’il puisse savoir si la requête reçue a déjà été traitée ou non:

Si la clé n’est pas connue, le traitement va être effectué et le résultat sauvegardé avant de retourner la réponse HTTP.
Dans le cas contraire, le serveur va retourner la réponse précédemment enregistrée.

La plupart du temps, la clé d’idempotence est envoyée dans les en-têtes de l’appel HTTP afin d’éviter de polluer le corps de la requête.

Prenons par exemple, le code source d’une API permettant de créer un billet de blog:

class BlogController extends AbstractController
{
    #[Route('/api/articles', methods: ['POST'])]
    public function create(Request $request): JsonResponse
    {
        $post = new stdClass();
        $post->id = Uuid::v7();
        $post->title = $request->request->get('title', 'Default title');
        $post->createdAt = new DateTimeImmutable();
        // [...] enregistrement en base de données

        return new JsonResponse($post, JsonResponse::HTTP_CREATED);
    }
}

Comme expliqué précédemment, cette API n’est pas idempotente. Car si une même requête est effectuée deux fois de suite, un même article My awesome article sera ajouté en base de données.

Nous allons maintenant ajouter à notre API la gestion d’une clé permettant de s’assurer de l’unicité du traitement d’une requête. Cette clé doit être envoyée par le client dans une en-tête que nous nommerons X-Idempotent-Key. Cette clé sera stockée dans un système de cache (via le composant symfony/cache) pendant une durée d’une heure. Si la clé n’existe pas, elle sera créée et dans le cas contraire, la réponse du traitement de la requête sera renvoyée une nouvelle fois depuis les données mises en cache.

Cela pourrait conduire à l’implémentation suivante:

class BlogController extends AbstractController
{
    public function __construct(
        private readonly Psr\Cache\CacheItemPoolInterface $cache,
    ) {}

    #[Route('/api/blog', methods: ['POST'])]
    public function create(Request $request): JsonResponse
    {
        if (
            // si l'en-tête X-Idempotent-Key est présente
            ($idempotentKey = $request->headers->get('X-Idempotent-Key')) !== null

            // et que la donnée est en cache
            && ($postCache = $cache->getItem($idempotentKey))->isHit()
        ) {
            // on retourne la réponse présente dans le cache
            return new JsonResponse($postCache->get(), JsonResponse::HTTP_CREATED);
        }

        // dans le cas contraire, on effectue le traitement

        $post = new stdClass();
        $post->id = Uuid::v7();
        $post->title = $request->request->get('title', 'Default title');
        $post->createdAt = new DateTimeImmutable();
        // [...] enregistrement en base de données

        // dans le cas où la clé d'idempotence est définie
        if ($idempotentKey !== null) {
            // on enregistre le résultat du traitement en cache
            $item = $cache->getItem($idempotentKey);
            $item->set($post);
            $item->expiresAfter(3600)
            $cache->save($item);
        }

        return new JsonResponse($post, JsonResponse::HTTP_CREATED);
    }
}

De cette manière notre API pourra être idempotente, améliorant ainsi sa fiabilité ainsi que la cohérence des données du service. L’idempotence permet de garantir que les requêtes identiques produisent toujours le même résultat, évitant ainsi les doublons involontaires qui pourraient survenir en cas de problème réseau par exemple.

Faut-il mettre en place ce mécanisme partout ? Pas nécessairement. Focalisez les opérations les plus critiques de votre système et en particulier les opérations de modification de l’état de ce dernier.

Le pattern Optional, le conteneur de valeur qui va remplacer vos données nullables

Fri, 25 Oct 2024 00:00:00 +0200

Nous manipulons tous au quotidien des données nullables, or manipuler des données qui peuvent être null implique de devoir effectuer de nombreuses vérifications afin de savoir si la donnée que l’on manipule contient bien une valeur avant de l’utiliser. Auquel cas, nous aurons une erreur de type:

PHP Warning:  Uncaught Error: Call to a member function method() on null in php shell code:1
Stack trace:
#0 {main}
  thrown in php shell code on line 1

Pour éviter l’utilisation de conditions de type if ($var !== null), il est possible d’utiliser le pattern Optional qui peut s’apparenter à la monade Maybe.

Un Optional est un conteneur permettant d’encapsuler une valeur qui peut être présente ou non. Ainsi, plutôt que d’utiliser une variable null pour représenter une valeur absente, nous allons pouvoir manipuler systématiquement un objet et appeler des méthodes sur ce dernier qui effectuera des opérations en fonction que la valeur soit présente ou non.

Prenons un exemple concret pour illustrer ce concept. Sur un site d’e-commerce, un événement est émis une fois un achat effectué par un utilisateur afin de lui envoyer un récapitulatif de sa commande. La gestion de l’envoi de l’email pourrait ressembler au code suivant:

class Customer
{
    public ?string $email;
}

readonly class OrderConfirmed
{
    public Customer $customer;
}

readonly class OrderNotification
{
    public function __construct(private EmailSender $email) {}

    public function sendConfirmatinEmailOnOrderConfirmed(OrderConfirmed $event): void
    {
        if ($event->getCustomer() == null) { // invite account
            return;
        }


        if ($event->getCustomer()->getEmail() == null) { // no email filled
            return;
        }

        $this->email->send($event->getCustomer()->getEmail(), 'Email content');
    }
}

Nous voyons dans ce cas d’exemple, qu’il est nécessaire de faire deux vérifications avant de pouvoir envoyer notre e-mail de confirmation:

Dans un premier temps, il est nécessaire de vérifier que la commande n’a pas été effectuée en “mode invité”, ce qui impliquerait d’avoir une commande sans notion d’acheteur,
Il est ensuite nécessaire de vérifier que l’on a bien une adresse de renseignée pour pouvoir envoyer l’e-mail.

Voyons maintenant ce que pourrait donner ce même code avec l’utilisation du pattern Optional:

class Customer
{
    /** @var Optional<string> */
    public Optional $email;
}

readonly class OrderConfirmed
{
    /** @var Optional<Customer> */
    public Optional $customer;
}

readonly class OrderNotification
{
    public function __construct(private EmailSender $email) {}

    public function sendConfirmatinEmailOnOrderConfirmed(OrderConfirmed $event): void
    {
        $event->customer
            ->flatMap(static fn (Customer $customer) => $customer->email)
            ->ifPresent(static fn (string $email) => $this->email->send($event->getCustomer()->getEmail(), 'Email content'));
    }
}

Dans cette seconde version, nous constatons que toutes nos vérifications (les if) ont été supprimées. Le code s’en retrouve plus concis et surtout se concentre sur les opérations utiles au traitement de l’envoi de notre e-mail, ce qui le rend plus expressif. Il n’est plus question de devoir vérifier si la donnée est présente ou non, la structure de données Optional va appliquer les transformations demandées uniquement si la valeur est présente et ne fait rien dans le cas contraire.

Les monades gagnant en popularité ces dernières années, on commence à voir des implémentations du pattern Optional directement dans les langages de programmation. Ce n’est (malheureusement) pas le cas en PHP. Mais on retrouve quelques implémentations sur Packagist.

Bien que son utilisation dans l’écosystème PHP reste marginale, à la vue des nombreux avantages qu’il représente, vous avez tout intérêt à regarder ça de plus près. Pour ma part, j’ai commencé à introduire cette notion en construisant ma propre implémentation qui se résume à quelques lignes de code.

Installer des extensions PHP facilement dans une image Docker

Wed, 23 Oct 2024 00:00:00 +0200

Si vous avez déjà construit des images Docker pour des applications ou projet PHP, vous avez certainement utilisé l’outil docker-php-ext-install. Ce dernier permet d’installer et configurer simplement des extensions PHP qui seront disponibles dans le conteneur. Néanmoins, cet outil se limite malheureusement aux extensions officielles fournies avec le langage.

Pour résoudre ce problème et permettre d’installer de nombreuses extensions PHP dans un conteneur Docker, il existe un outil disponible librement sur Github: mlocati/docker-php-extension-installer. Ce dernier met à disposition un script nommé install-php-extensions qui vous permettra d’installer et de configurer des extensions PHP au sein de votre image. À la différence du script officiel, il ne se limite pas aux seules extensions fournies directement avec PHP puisqu’il couvre un très large panel d’extensions parmi lesquelles: amqp, cassandra, ioncube_loader, jsonpath, newrelic, rdkafka, xdebug et bien d’autres encore.

Mais il permet d’aller encore plus loin en installer également les dépendances nécessaires à l’installation des extensions. Il installera par exemple la bibliothèque rabbitmq-c nécessaire au bon fonctionnement de l’extension amqp permettant entre autres de communiquer avec RabbitMQ.

Fonctionnant avec les images basées sur Debian et Alpine, vous aurez la possibilité d’installer les extensions pour les versions de 7.1 à 8.4 de PHP, de quoi couvrir un grand nombre de besoins et cas d’utilisation.

Et pour finir, voici un exemple d’utilisation:

FROM php:8.3-cli

ADD --chmod=0755 https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions /usr/local/bin/

RUN install-php-extensions amqp gd xdebug

Si vous êtes passé à côté de cet outil et que vous utilisez encore une combinaison des utilitaires officiels et/ou pecl, je ne peux que vous encourager à tester cet outil.

Comment récupérer le nombre d'erreurs ignorées dans une analyse PHPStan

Wed, 04 Sep 2024 00:00:00 +0200

Je travaille au quotidien avec PHPStan que ce soit pour mes projets personnels, mais également professionnels. Pour des projets complexes et ayant plusieurs années d’existence, il n’est pas rare d’ajouter des règles d’analyses graduellement afin d’éviter un trop grand nombre d’erreurs à corriger (ou à ignorer) d’un seul coup. Aussi dans une optique d’amélioration continue, il peut être intéressant de suivre le nombre d’erreurs ignorées afin de pouvoir s’assurer que le chiffre diminue (ou n’augmente pas de manière disproportionnée) au fil du temps.

Malheureusement, c’est une information que PHPStan ne permet pas de récupérer simplement.

J’ai donc cherché une solution, car c’est une métrique que je cherche à suivre. L’idée étant d’avoir une idée de l’état du code et de détecter si une équipe a tendance à ignorer des erreurs relevées par l’analyse statique ou si au contraire, elle est dans une optique d’amélioration continue du code.

Lors de mes recherches, j’ai trouvé le projet phpstan-baseline-analysis qui permet d’analyser une baseline PHPStan pour fournir un résumé de la typologie des erreurs qui sont présentes dans le fichier. C’est un outil intéressant, dont l’auteur Markus Staab, a publié un article pour présenter le projet. Bien qu’intéressant, il ne permet pas de déterminer le nombre d’erreurs réellement ignorées dans le projet. Se basant sur un fichier de configuration, le projet fait par exemple l’impasse sur les erreurs directement ignorées dans le code ou ne permet pas de compter avec précision les erreurs ignorées au travers d’une expression régulière.

Je me suis alors intéressé plus en détail au fonctionnement de PHPStan et à son mécanisme d’analyse. J’ai notamment pu découvrir le fonctionnement du système de cache. L’essentiel des informations est stocké dans un fichier unique (resultCache.php), lequel contient l’ensemble des erreurs détectées. Ainsi, en analysant le contenu du fichier, en lisant les informations telles que errorsCallback, locallyIgnoredErrorsCallback et linesToIgnore, il est possible de récupérer avec détails et précision, l’ensemble des erreurs présentes dans la base de code (et ainsi de pouvoir en extraire des métriques).

C’est ainsi qu’est né phpstan-report, une surcouche à PHPStan, capable de lancer une analyse et de lire le fichier de cache afin d’en extraire des métriques permettant de tracer et suivre l’évolution des erreurs de l’analyse statique.

Tester un bundle avec plusieurs versions de Symfony

Mon, 29 Jul 2024 00:00:00 +0200

Lorsque l’on travaille et maintient un bundle Symfony, il n’est pas rare de devoir gérer la compatibilité de ce dernier avec plusieurs versions du framework. Par exemple, au moment où je publie ces lignes, les versions 5.4, 6.4 et 7.1 sont officiellement maintenues. Exécuter sa batterie de tests automatisés sur plusieurs versions peut alors être fastidieux.

Le minimum que l’on puisse faire serait de tester le bundle en installant les dépendances Composer avec les options --prefer-stable et --prefer-lowest (pour récupérer les versions minimales des dépendances autorisées). Cela fonctionne, mais si une version du bundle supporte les trois versions courantes, ce dernier serait alors testé avec les versions 5.4 et 7.1.

Pour remédier à ce problème, on pourrait alors à l’installation des dépendances utiliser la commande composer require pour installer spécifiquement les versions désirées. Par exemple, si l’on souhaite installer une version 6.4, on pourrait utiliser la commande composer require symfony/framework-bundle:6.4.*. Cela fonctionne bien, mais peut rapidement être fastidieux si le nombre de dépendances Symfony est important.

Pour résoudre cette problématique, les équipes de Symfony ont intégré une fonctionnalité dans Symfony Flex permettant d’installer une version spécifique pour toutes les dépendances Symfony en une seule opération. Flex est une extension Composer bien connue des développeurs Symfony. Ainsi, pour mettre à jour vos dépendances sur une version spécifique, il vous suffira d’utiliser la variable d’environnement SYMFONY_REQUIRE.

Par exemple, la commande ci-dessous mettre toutes vos dépendances symfony/* en version 6.4:

$ SYMFONY_REQUIRE=6.4 composer update

À noter que symfony/flex peut être installé en tant que dépendance de votre projet, mais peut également être installé sur l’OS et donc en dehors de votre projet via la commande: composer global require --no-progress --no-scripts --no-plugins symfony/flex.

Cela vous permettra de grandement simplifier vos workflows d’intégration continue. Et pour conclure cet article, voici par exemple, une configuration Github Actions que vous pouvez utiliser sur vos projets:

name: Run tests
on: [ push ]
jobs:
    phpunit:
        runs-on: ubuntu-latest
        strategy:
            matrix:
                composer-prefs: [ '--prefer-stable', '--prefer-lowest' ]
                php-version: [ '8.2', '8.3' ]
                symfony-version: [ '5.4.*', '6.4.*', '7.1.*' ]
        name: 'PHPUnit - PHP/${{ matrix.php-version }} - SF/${{ matrix.symfony-version }} ${{ matrix.composer-prefs }}'
        steps:
            -   name: Checkout
                uses: actions/checkout@v2
            -   name: Setup PHP
                uses: shivammathur/setup-php@v2
                with:
                    php-version: ${{ matrix.php-version }}
                    coverage: xdebug
            -   run: composer global config --no-plugins allow-plugins.symfony/flex true
            -   run: composer global require --no-progress --no-scripts --no-plugins symfony/flex
            -   run: composer update --prefer-dist --no-interaction ${{ matrix.composer-prefs }}
                env:
                    SYMFONY_REQUIRE: ${{ matrix.symfony-version }}
            -   name: PHPUnit
                run: vendor/bin/phpunit

Utiliser PHPUnit 10 avec Symfony

Mon, 09 Oct 2023 00:00:00 +0200

Au moment où j’écris ce billet, PHPUnit 10 a été publié il y a près de 8 mois (le 3 février 2023). Et pourtant si on tente de l’utiliser dans un projet Symfony utilisant le bridge symfony/phpunit-bridge, nous obtenons l’erreur suivante: PHP Fatal error: Uncaught Error: Class "PHPUnit\TextUI\Command.

PHP Fatal error:  Uncaught Error: Class "PHPUnit\TextUI\Command" not found in /home/jdecool/Workspace/sandbox/test/bin/phpunit:11
Stack trace:
#0 {main}
  thrown in /home/jdecool/Workspace/sandbox/test/bin/phpunit on line 11

Fatal error: Uncaught Error: Class "PHPUnit\TextUI\Command" not found in /home/jdecool/Workspace/sandbox/test/bin/phpunit on line 11

Error: Class "PHPUnit\TextUI\Command" not found in /home/jdecool/Workspace/sandbox/test/bin/phpunit on line 11

Call Stack:
    0.0001     396248   1. {main}() /home/jdecool/Workspace/sandbox/test/bin/phpunit:0

La raison étant que le script fourni par Symfony utilise du code qui a été supprimé dans la dernière version majeure du framework de test.

Il y a plusieurs propositions en cours pour corriger ce problème, mais aucune n’est actuellement mergée.

Pour corriger cela, vous pouvez simplement modifier le fichier bin/phpunit en remplaçant la ligne ci-dessous:

-    PHPUnit\TextUI\Command::main();
+    exit((new PHPUnit\TextUI\Application)->run($_SERVER['argv']));

Le pattern "Parameter Object"

Sat, 26 Feb 2022 00:00:00 +0100

Après avoir publié mon billet concernant le pattern Commande hier, on m’a demandé s’il était possible d’utiliser une commande pour remplacer un groupe de paramètre d’une fonction ou d’une méthode avec pour objectif de simplifier le code et sa lisibilité sans pour autant mettre en place un bus de commande.

Pour répondre sans détour à cette question, oui il est tout à fait possible de remplacer des paramètres de fonction par un objet, cela correspond même à un autre patron de conception nommé le paramètre objet (ou Parameter Object en anglais).

Ce pattern permet de regrouper un ensemble de paramètres au sein d’un ou plusieurs objets qui seront transmis à votre fonction afin de rendre le code plus lisible en simplifiant les signatures de méthodes.

Il permet également de supprimer de la duplication de code dans le cas ou différentes méthodes définissent systématiquement un même groupe de paramètre parce que ces derniers sont fonctionnellement liés.

Par exemple, je travaille sur une application de calendrier dans laquelle j’ai énormément de méthodes qui travaillent avec des dates de début et des dates fins de période:

public function filterEventByDate(DateTime $start, DateTime $end);
public function getEvents(DateTime $start, DateTime $end);
public function getAvailableSlot(DateTime $start, DateTime $end);

On remarque ici que de nombreuses méthodes partagent les paramètres $start et $end qui partage une même sémantique fonctionnelle. On pourra alors regrouper ces deux paramètres au sein d’un object DateRange:

class DateRange
{
    public function __construct(
        public readonly DateTime $start,
        public readonly DateTime $end,
    ) {
    }
}
public function filterEventByDate(DateRange $dateRange);
public function getEvents(DateRange $dateRange);
public function getAvailableSlot(DateRange $dateRange);

Si l’exemple précédent est relativement simpliste, dans des cas d’utilisation réels, on peut facilement imaginer que notre objet paramètre pourra regrouper bien plus de données.

Le pattern "Commande"

Fri, 25 Feb 2022 00:00:00 +0100

Si je reprends la définition de wikipedia, il s’agit d’un patron de conception (ou design pattern en anglais) qui permet d’encapsuler la notion d’invocation. C’est un moyen très utile de rendre votre code modulaire et lisible en découpant votre code en différentes commandes, chacune ayant des responsabilités uniques et spécifiques.

Un objet Command est un DTO (Data Transfer Object) qui permet d’encapsuler toutes les informations nécessaires pour réaliser une action. La commande n’a aucune logique, elle s’utilise au travers d’un bus (command bus pattern) qui est chargé de recevoir une commande valide et de déclencher les actions associées. Son unique responsabilité est de gérer les différents cas d’utilisation en déléguant l’exécution de la commande à une classe spécifique au traitement en question. L’objectif est de permettre au développeur d’émettre une intention d’effectuer une action sans que ce dernier n’ait à se soucier de la manière dont elle va être traitée et/ou implémentée.

<?php

class CreateCustomer {
    public function __construct(
        public readonly string $name,
        public readonly string $phonenumber,
    ) {
        // assert data validity
    }
}

$this->bus->execute(new CreateCustomer(/* ... */));

Il existe de nombreux composants PHP qui vous permettent d’implémenter ce pattern dans vos projets. Mais concevoir un bus de commande n’est fondamentalement pas compliqué. Dans sa version minimaliste, il s’agit de faire un lien entre une commande et son gestionnaire (ou handler en anglais).

<?php

class CommandBus {
    /** Handler[] */
    public function __construct(
        private readonly array $handlers,
    ) {
    }

    public function execute(object $command): void
    {
        $commandClass = get_class($command);
        $handler = $this->handlers[$commandClass] ?? throw new RuntimeException("No handler for $commandClass command.");

        $handler($command);
    }
}

class MyCommand {}
class MyCommandHandler
{
    public function __invoke(MyCommand $command): void
    {
        echo "Hello World", PHP_EOL;
    }
}

$bus = new CommandBus([
    MyCommand::class => new MyCommandHandler(),
]);
$bus->execute(new MyCommand()); // will display "Hello World"

Si ce type d’architecture a été popularisé par la montée en puissance du Domain Driven Design ou des architectures CQRS, il est tout à fait possible de l’utiliser dans n’importe quel projet.

J’en suis pour ma part très friand car il y a de nombreux avantages à utiliser ce paradigme. Il permet de bien découper le code, d’avoir des petites classes avec des responsabilités uniques et isolées, donc faciles à tester. Au-delà de ces avantages purement techniques, cela permet également de pouvoir dresser simplement la liste de cas d’utilisation qui sont gérés par notre projet.

Un autre aspect que j’apprécie particulièrement est la facilité que l’on a d’étendre le comportement d’un bus de commande. Il est possible de décorer un bus afin de lui ajouter des comportements supplémentaires qui ne sont pas directement liéss à l’intention métier que l’on souhaite réaliser dans l’application. Il sera par exemple possible de créer un bus de commande qui gérera les transactions de base de données, de gérer des logs ou d’effectuer diverses tâches de monitoring, tout cela de manière complètement découplée de votre code orienté métier.

Utiliser MinIO comme stockage de données objets en PHP

Tue, 07 Jul 2020 00:00:00 +0200

Je travaille sur un projet où il est question de stocker un grand nombre de fichiers. Ce dernier devrait être hébergé dans le Cloud et notamment sur des infrastructures orientées Serverless. Il est donc impensable d’utiliser un système de fichiers “classique” pour stocker des fichiers. Je me suis donc tourné vers les systèmes de stockage objet (type Amazon S3). C’est alors qu’en effectuant quelques recherches, j’ai découvert MinIO. Il s’agit d’un serveur de stockage open source compatible Amazon S3.

Pour utiliser MinIO avec PHP, vous pouvez simplement utiliser le SDK d’AWS. Après avoir créé votre bucket dans le serveur MinIO, vous pouvez commencer à travailler avec le système de fichier comme vous le feriez avec S3:

$s3 = new Aws\S3\S3Client([
    'version' => 'latest',
    'region'  => 'eu-east-1', // cette configuration n'a pas d'importance pour MinIO
    'endpoint' => 'http://localhost:9000',
    'use_path_style_endpoint' => true, // ce paramètre doit obligatoirement être actif
    'credentials' => [
        'key'    => 'ACCESSKEYID',
        'secret' => 'SECRETACCESSKEY',
    ],
]);

// enregistrer un fichier
$insert = $s3->putObject([
     'Bucket' => 'bucket',
     'Key'    => 'key',
     'Body'   => 'Hello from MinIO!!',
]);

// récupérer un fichier
$retrive = $s3->getObject([
     'Bucket' => 'bucket',
     'Key'    => 'key',
     'SaveAs' => 'key_local',
]);

Voila, ce n’est guère plus compliqué.

Pour ma part, lorsque je travaille avec le système de fichiers, j’ai pour habitude d’utiliser la bibliothèque Flysystem. Si vous ne connaissez pas Flysystem, je vous recommande vivement de vous y intéresser. Il s’agit de composant permettant d’abstraire l’accès à tout système de fichiers. Cela vous permettra d’écrire un code qui sera automatiquement compatible avec votre système de fichiers local, un FTP, mais également un grand nombre de fournisseur Cloud tel que Amazon S3 ou Azure Blob Storage.

Une fois le composant de base league/flysystem et l’extension league/flysystem-aws-s3-v3 installé avec l’aide de Composer. Il vous suffit de créer l’adapteur qui va bien:

$s3 = new Aws\S3\S3Client([
    'version' => 'latest',
    'region'  => 'eu-east-1', // cette configuration n'a pas d'importance pour MinIO
    'endpoint' => 'http://localhost:9000',
    'use_path_style_endpoint' => true, // ce paramètre doit **obligatoirement** être actif
    'credentials' => [
        'key'    => 'ACCESSKEYID',
        'secret' => 'SECRETACCESSKEY',
    ],
]);

$adapter = new League\Flysystem\AwsS3v3\AwsS3Adapter($client, 'bucket');
$filesystem = new League\Flysystem\Filesystem($adapter);

// enregistrer un fichier
$filesystem->put('my-file.txt', 'Hello from MinIO!!');

// récupérer un fichier
$object = $filesystem->get('my-file.txt');

Si vous utilisez Symfony, en ce qui me concerne j’utilise le bundle oneup/flysystem-bundle. Pour Laravel le composant le plus complet semble être graham-campbell/flysystem.

Tout ça pour dire, que si vous souhaitez utiliser un système de stockage objet et que vous souhaitez héberger vous même ce dernier, je ne peux que vous conseiller de jeter un coup d’oeil à MinIO.

La gestion des enums en PHP

Mon, 07 Oct 2019 00:00:00 +0200

Un enum, on parle également de type énuméré ou énumération en français, “est un type de donnée qui consiste en un ensemble de valeurs constantes” (source Wikipédia). Il s’agit d’une structure très pratique, mais qui n’existe malheureusement pas nativement dans PHP.

Si l’on se réfère à la documentation officielle de PHP, il existe bien un type similaire au travers de la classe SplEnum. Mais cette structure de données a le défaut de nécessiter l’installation d’une extension supplémentaire ce qui peut ne pas être une opération triviale pour une application de production si cela n’est pas prévu en avance.

C’est pour cela qu’il existe de nombreux composants qui permettent de mettre en place un système qui se rapproche d’un enum. Pour ma part, j’utilise régulièrement myclabs/php-enum. Une bibliothèque qui m’a rendu de nombreux services à maintes reprises et qui fait très bien le travail.

Elle a pourtant un défaut qui m’a posé un problème sur un projet récemment. La plupart des composants d’enum en PHP fonctionnent suivant le même principe. Il s’agit d’une classe de base qui est étendue dans notre code et à laquelle on attache des constantes. Par exemple:

class WeekDay extends Enum
{
    public const MONDAY = 'monday';
    public const TUEDAY = 'tuedsay';
    // ...
}

Il est ensuite possible dans notre code, d’utiliser la notation WeekDay::MONDAY() pour récupérer une instance de notre enum.

Le problème que j’ai par exemple rencontré avec myclabs/php-enum est que chaque appel à WeekDay::MONDAY() retourne une nouvelle instance de classe. Cela signifie que lorsque l’on récupère deux fois le même enum.

WeekDay::MONDAY() == WeekDay::MONDAY() // true
WeekDay::MONDAY() === WeekDay::MONDAY() // false

Cela peut-être problématique car dans mon cas, il m’arrive par exemple d’utiliser la classe SplObjectStorage pour stocker des associations de données.

Par exemple, si je conçois une application qui permet à des utilisateurs d’indiquer leur humeur de la journée, je souhaite par exemple pouvoir associer un jour de la semaine (via notre enum WeekDay) avec une humeur (qui serait également géré au travers d’un enum Mood). Or si chaque élément de mon énumération est systématiquement une instance d’objet différente, il est alors impossible de travailler avec le code suivant:

$userMood = new SplObjectStorage();
$userMood->attach(WeekDay::MONDAY(), Mood::GOOD());

$userMood->contains(WeekDay::MONDAY()); // false

Pour remédier à cette problématique, j’ai découvert le composant marc-mabe/php-enum qui permet également de gérer un système d’énumération. À la différence de myclabs/php-enum, cette bibliothèque renverra toujours la même instance pour une même donnée de notre enum. Ce qui en reprenant notre code précédent, donnerait la chose suivante:

WeekDay::MONDAY() == WeekDay::MONDAY() // true
WeekDay::MONDAY() === WeekDay::MONDAY() // true

À ce stade, vous vous dites certainement que mon choix est maintenant fait et que dorénavant j’utiliserai de manière systématique marc-mabe/php-enum. Pourtant tout n’est pas aussi simple. Si on a vu un avantage d’une des bibliothèques par rapport à l’autre, il y a une fonctionnalité de myclabs/php-enum que j’affectionne tout particulièrement: le fait de pouvoir mettre les constantes en privées.

class WeekDay extends Enum
{
    private const MONDAY = 'monday';
    private const TUEDAY = 'tuedsay';
    // ...
}

C’est pour moi un énorme avantage car lorsque j’utilise un enum, je ne souhaite pas savoir comment il est construit à l’intérieur, comment il fonctionne. Je veux simplement l’utiliser. Or si les constantes sont publiques, cela signifie que la donnée est visible par le développeur et pire encore, qu’il est possible qu’il l’utilise en dehors de l’énumération.

Comme toujours dans l’ingénierie logicielle, il vous faudra faire le bon choix selon votre problématique et le choix de votre implémentation technique.

Tout ce que vous devez savoir sur PHP 7.4

Thu, 03 Oct 2019 00:00:00 +0200

La fin de l’année approche à grand et comme d’habitude, nous autres développeurs PHP auront sous le sapin une nouvelle version de PHP à notre disposition. La version 7.4 est une version que j’attends avec impatience notamment pour la possibilité de pouvoir typer les propriétés de classe. Ce changement s’inscrit dans la continuité du langage d’avoir un typage fort.

Comme avec l’arrivée de chaque nouvelle version, les équipes de PHP ont publié un guide de migration de la version 7.3 vers la version 7.4 incluant notamment les nouvelles évolutions du langage, les nouvelles classes, interfaces fonction et constante à disposition des développeurs, mais aussi les fonctionnalités dépréciées, les changements non rétro-compatibles ainsi que les extensions supprimées.

Je vous conseille fortement d’y jeter un coup d’oeil, mais attention le guide est tout frais et n’est actuellement disponible qu’en anglais !

Déployer un projet PHP depuis un monorepo

Sun, 19 May 2019 00:00:00 +0200

Je parlais dans un billet précédent de comment publier des composants PHP sur Packagist depuis un dépôt de code monolithique. Une autre question récurrente venant des équipes projet qui souhaitent mettre en place ce type de structure est: comment déployer un sous-projet du dépôt de manière indépendante ?

En effet, il y a quelques années un formidable outil, Capistrano, a modifié la manière dont nous déployons nos applications. Capistrano est un outil Open Source développé en Ruby qui permet d’automatiser le processus de création et de publication d’une application sur un ou plusieurs serveurs Web (source Wikipédia). L’outil a eu un tel succès que différentes alternatives basées sur le même principe sont apparues. On peut par exemple citer Deployer en PHP ou Ansistrano une solution équivalente fonctionnant avec Ansible.

Nous avons donc avec ces solutions pris l’habitude de déployer nos applications en clonant directement le dépôt de sources (que ce soit Git ou Subversion auparavant) afin de déployer le tag ou la branche de production de nos projets. Or lorsque l’on souhaite opter pour une approche monorepo, cela signifie que notre déploiement va cloner tous les projets composant notre dépôt de code. Bien que cela puisse être envisagé dans certains cas, c’est loin d’être une solution optimale (notamment quand vous allez vouloir mettre vos applications sur différents serveurs).

Cloner un dépôt de source n’est qu’une solution parmi tant d’autres pour déployer nos projets. C’est également omettre que les outils qui font ce travail pour nous sont un peu plus intelligents que cela et offrent de nombreuses autres possibilités. En plus de pouvoir cloner un dépôt Git, les solutions d’automatisations sont bien souvent capables de copier des fichiers localement sur un système de fichiers, par FTP ou encore via SSH. C’est donc une stratégie de copie qui peut ne pas remettre en cause votre processus de déploiement ni même la configuration (ou très peu) de ce dernier.

Prenons par exemple une configuration de base générée par Deployer (le principe sera le même pour l’ensemble des outils, mais la syntaxe de configuration variera):

<?php

namespace Deployer;

require 'recipe/common.php';

set('application', 'my_project');
set('repository', 'https://github.com/foo/bar.git');

set('git_tty', true);

set('shared_files', ['shared-files.php']);
set('shared_dirs', ['var/log']);
set('writable_dirs', ['data/uploads']);

host('project.com')
    ->set('deploy_path', '~/');

desc('Deploy your project');
task('deploy', [
    'deploy:info',
    'deploy:prepare',
    'deploy:lock',
    'deploy:release',
    'deploy:update_code',
    'deploy:shared',
    'deploy:writable',
    'deploy:vendors',
    'deploy:clear_paths',
    'deploy:symlink',
    'deploy:unlock',
    'cleanup',
    'success'
]);

after('deploy:failed', 'deploy:unlock');

Comme je l’ai évoqué juste avant, par défaut la configuration se base sur un dépôt Git pour déployer (ici https://github.com/foo/bar.git). Lors du processus de déploiement l’ensemble des tâches deploy seront exécutées. C’est au niveau de la tâche deploy:update_code que tout se joue. C’est cette dernière qui va mettre à jour le code sur notre serveur project.com en clonant le dépôt spécifié dans la configuration repository.

Nous devons donc modifier cette tâche afin de déployer non plus via Git, mais en effectuant une copie de fichier en SSH (via rsync dans notre cas). Pour cela, nous allons installer les recettes additionnelles de Deployer via Composer : composer require --dev deployer/recipes. Nous pourront ensuite ajouter la configuration nécessaire au fonctionnement de cette dernière:

<?php

namespace Deployer;

require 'recipe/common.php';
require 'recipe/rsync.php'; // inclusion de la recette

set('application', 'my_project');
set('repository', 'https://github.com/foo/bar.git');

set('git_tty', true);

set('shared_files', ['shared-files.php']);
set('shared_dirs', ['var/log']);
set('writable_dirs', ['data/uploads']);

// configuration de rsync
set('rsync',[
    'exclude'      => [
        '.git',
        'var',
        'vendor',
        'deploy.php',
    ],
    'exclude-file' => false,
    'include'      => [],
    'include-file' => false,
    'filter'       => [],
    'filter-file'  => false,
    'filter-perdir'=> false,
    'flags'        => 'rzcE',
    'options'      => ['delete'],
    'timeout'      => 60,
]);

// configuration du répertoire devant être copié et sa destination
set('rsync_src', __DIR__);
set('rsync_dest', '');

host('project.com')
    ->set('deploy_path', '~/');

desc('Deploy your project');
task('deploy', [
    'deploy:info',
    'deploy:prepare',
    'deploy:lock',
    'deploy:release',
    'rsync', // pour finir nous remplaçons la tâche de déploiement Git
    'deploy:shared',
    'deploy:writable',
    'deploy:vendors',
    'deploy:clear_paths',
    'deploy:symlink',
    'deploy:unlock',
    'cleanup',
    'success'
]);

after('deploy:failed', 'deploy:unlock');

Et voilà ! Nous avons maintenant notre projet dont le fonctionnement est identique à la première version mis à part que la copie des fichiers ne se fait plus via un clone du dépôt Git, mais via une copie de fichier en SSH.

Il se peut que vous ne souhaitiez pas modifier ce qui est fait par la tâche deploy. C’est le cas, si par exemple vous déployez un projet Symfony en utilisant la recette fournie par Deployer. Dans ce cas, remplacer la tâche update_code par rsync vous obligerez à redéfinir l’ensemble des opérations de déploiement, ce qui peut-être gênant.

Il est alors préférable de redéfinir uniquement le fonctionnement de la tâche update_code.

<?php

namespace Deployer;

require 'recipe/symfony4.php';
require 'recipe/rsync.php';

set('application', 'my_symfony_project');

add('shared_files', ['.env']);
add('shared_dirs', ['var/log']);
add('writable_dirs', ['var']);

set('rsync',[
    /* configuration rsync */
]);

set('rsync_src', __DIR__);
set('rsync_dest', '');

// surchage de la tâche `deploy:update_code`
task('deploy:update_code', function() {
    invoke('rsync'); // appel de la tâche `rsync`
});

host('symfony-project.com')
    ->set('deploy_path', '~/');

Avec ce genre de configuration, vous avez donc la possibilité de déployer les projets présents dans votre monorepo de manière complètement indépendante.

J’ai dans ce billet, principalement évoqué comment configurer Deployer, mais comme je l’ai précisé au début de ce billet, les autres outils peuvent fonctionner avec le même principe. Par exemple, si vous utilisez Ansistrano, vous devrez rajouter les configurations ci-dessous à votre playbook Ansible pour effectuer une copie de fichier rsync:

vars:
    # ...
    ansistrano_deploy_via: "rsync"
    ansistrano_rsync_extra_params: ""
    ansistrano_rsync_set_remote_user: yes
    ansistrano_rsync_path: ""
    ansistrano_rsync_use_ssh_args: no

Publier des dépendances PHP sur Packagist dans un projet monorepo

Sat, 18 May 2019 00:00:00 +0200

Les dépôts monolithiques (on parle également de dépôt monorepo ou monorepository) consistent tout simplement à avoir un dépôt de code unique regroupant plusieurs projets. Cela peut être des applications distinctes (dans le cas de microservices), des composants d’un même projet (une API, avec son interface et éventuellement des bibliothèques de code autonomes) ou tout le code appartenant à une société.

À la différence d’un projet de type monolithe, chaque projet gère de manière indépendante ses propres dépendances. Cela permet d’avoir une gestion plus fine des dépendances de chaque projet, mais également de pouvoir utiliser des technologies différentes si le besoin le nécessite. On peut par exemple imaginer: une UI de type SPA développée en Javascript fonctionnant avec un backend composé d’une API PHP et d’un service de gestion des utilisateurs développé en Go. Tout cela centralisé au sein d’un même dépôt.

Je passerai sur les avantages et inconvénients de ce type de gestion du code. Si vous n’êtes pas à l’aise avec le sujet, je vous laisserai vous faire votre propre opinion en parcourant cette liste de ressources.

Si le sujet n’a rien de nouveau, je ne l’ai vu que très rarement utilisé. Je connais très peu de sociétés françaises utilisant ce modèle (je peux les compter sur les doigts de la main). S’il ne s’agit aucunement d’une silver bullet, je suis convaincu que c’est une méthode efficace pour travailler sur certains projets. Par exemple, je travaille actuellement sur une plateforme orientée microservices (une dizaine), utilisée par 3 fronts et également composée de quelques bibliothèques de code indépendantes. Cette plateforme est gérée par une seule et même équipe, ce qui en fait un excellent candidat. Pourtant, nous gérons actuellement chaque brique au sein de son propre dépôt de code.

Mais nous ne sommes pas là pour débattre autour de ce point, mais plutôt pour évoquer comment gérer les dépendances Composer dans un dépôt de code monolithique. C’est un sujet que j’ai déjà abordé il y a quelques années dans un article de ce blog. Mais comment faire lorsque l’on souhaite partager une dépendance Composer sur Packagist.

Vous ne le savez peut-être pas, mais pour déclarer un composant PHP comme une bibliothèque de code pouvant être utilisée via Composer, il est nécessaire que votre code PHP soit présent dans un dépôt de code indépendant avec un fichier composer.json à la racine. Ce mode de fonctionnement n’est donc pas compatible avec un dépôt monolithique.

Pour obtenir ce dépôt de code indépendant, il est bien entendu hors de question de copier à la main les changements. Mais quelles solutions s’offrent à nous dans ce cas ?

La première solution (en partant du principe que vous gérez votre code avec Git) est d’utiliser les subtrees. Ces derniers vont permettre d’extraire une sous-arborescence de votre dépôt afin de le pousser code dans un autre dépôt.

Supposons que notre dossier contienne l’arborescence ci-dessous :

.git
/api
/backend
/ui
/packages
    /package-1
    /package-2

Nous souhaitons extraire le dossier /packages/package-2 dans son propre dépôt afin de publier ce dernier sur Packagist. Pour cela, nous allons commencer par créer le dépôt de code qui accueillera le projet:

$ cd <chemin-nouveau-depot>
$ git init --bare

Nous allons ensuite créer notre sous-arbre Git sur le dépôt original et indiquer un nom de branche :

$ git subtree split --prefix=packages/package-2 -b split

Il ne nous reste plus qu’à pousser les modifications dans le dépôt du composant :

$ git push <chemin-nouveau-depot> split:master

Vous pouvez ensuite pousser le dépôt de code indépendant là où vous le souhaitez et déclarer ce dernier dans Package comme n’importe quel autre dépôt.

Par la suite, vous n’aurez plus qu’à répéter les étapes 2 et 3 afin de mettre à jour le dépôt du composant avec les modifications du dépôt principal. Pour simplifier et automatiser ces mises à jour, je vous recommande vivement d’ajouter ces opérations dans votre intégration continue.

L’utilisation de git subtree split n’est en soi pas compliquée, mais elle est un peu verbeuse et nécessite de jongler entre différents dépôts de code. Il existe des outils pour simplifier cette opération.

Le premier outil auquel je pense (même si je ne l’ai jamais utilisé) est splitsh. Il s’agit de l’outil utilisé pour découper le projet monolithique de Symfony.

Le second outil est un composant PHP développé par Tomáš Votruba, membre reconnu de la communauté PHP. Tomáš a développé un composant qu’il a nommé MonorepoBuilder et qui contient tout un ensemble d’outils pour aider les développeurs à gérer un monorepo. Ce qui nous intéresse particulièrement est la commande de split. Pour l’utiliser, vous devrez récupérer la dépendance via Composer au travers de la commande composer require symplify/monorepo-builder --dev. Il faudra ensuite écrire un fichier de configuration monorepo-builder.yml qui permettra de configurer quel dossier doit être extrait vers quel dépôt.

# monorepo-builder.yml
parameters:
    directories_to_repositories:
        packages/package-1: 'git@github.com:Foo/Package1.git'
        packages/package-2: 'git@github.com:Foo/Package2.git'

Vous n’avez ensuite plus qu’à lancer l’opération via la commande vendor/bin/monorepo-builder split pour extraire le dossier dans son propre dépôt.

Tester une connexion SMTP avec SwiftMailer

Mon, 13 May 2019 00:00:00 +0200

J’ai pour habitude de créer une page de statut dans les applications que je développe afin de tester que l’ensemble des services nécessaires au bon fonctionnement de cette dernière (base de données, serveur mail, API…) sont lancés et correctement configurés. Nous allons voir dans cet article comment tester une connexion SMTP au sein d’une application utilisant le composant SwiftMailer.

Si l’on prend le cas d’usage simple proposé en introduction dans la documentation du composant :

// Create the Transport
$transport = (new Swift_SmtpTransport('smtp.example.org', 25))
  ->setUsername('your username')
  ->setPassword('your password')
;

// Create the Mailer using your created Transport
$mailer = new Swift_Mailer($transport);

// Create a message
$message = (new Swift_Message('Wonderful Subject'))
  ->setFrom(['john@doe.com' => 'John Doe'])
  ->setTo(['receiver@domain.org', 'other@domain.org' => 'A name'])
  ->setBody('Here is the message itself')
  ;

// Send the message
$result = $mailer->send($message);

Le principe pour une connexion est simple, il faut tester que la couche transport puisse se connecter au service. Pour cela, il faut démarrer la connexion vers le serveur SMTP et vérifier si une erreur s’est produite :

try {
    $transport->start();
    $isSmtpOk = true;
} catch (Swift_TransportException $e) {
    $isSmtpOk = false;
}

L’exemple ci-dessus marche bien, mais dans la plupart des cas, nous envoyons rarement directement un mail. Dans une grande majorité des cas, nous allons utiliser un spool de mail qui va stocker les mails que l’on souhaite envoyer pour par la suite effectuer un traitement en lot. C’est par exemple, le fonctionnement par défaut de SwiftMailer dans Symfony.

$spool = new FileSpool(__DIR__.'/var/spool');
$transport = new Swift_SpoolTransport($spool);
$mailer = new Swift_Mailer($transport);

Or dans ce cas, on ne peut pas réellement tester la couche de transport directement car notre instance de la classe Swift_SpoolTransport ne gère pas réellement l’envoi des mails, mais gère la logique permettant de traiter le mail plus tard. De ce fait l’ implémentation de la méthode $transport->start() est vide et ne fait donc aucune action.

Il faudra donc dans ce cas, tester la méthode start directement sur l’instance du spool, à savoir sur notre objet $spool. Et si vous utilisez Symfony, le framework configure un service swiftmailer.transport.real permettant d’accéder à l’instance de l’objet qui gérera réellement l’envoi des mails.

phpdaily le blog

Wed, 06 Mar 2019 00:00:00 +0100

Si vous suivez sur ce blog ou les réseaux sociaux, vous n’êtes pas sans savoir que depuis le mois de février, je travaille sur un projet qui met à disposition des images Docker pour tester les versions en cours de développement de PHP.

En plus de simplifier l’accès aux futures versions du langage, j’avais envie d’avoir un espace de publication pour communiquer les nouveautés de chaque version. C’est pour cela que j’ai démarré un blog (en anglais) rattaché au projet. Ce dernier servira à publier des articles pour décrire, expliquer et mettre en oeuvre au travers d’exemples les futures fonctionnalités du langage. Ce dernier est accessible à l’adresse https://phpdaily.github.io. Un flux RSS est disponible et un compte Twitter a été créé pour l’occasion.

Le blog est actuellement hébergé sur GitHub Pages et le code source est disponible. Aussi, je souhaite que ce blog soit communautaire. Donc si vous souhaitez écrire un billet (en anglais) à propos d’une prochaine évolution du langage, n’hésitez pas à faire une pull request sur le projet.

Envie de tester PHP 7.4 ? Il y a une image Docker pour ça !

Fri, 01 Feb 2019 00:00:00 +0100

La version 7.4 de PHP est prévue pour la fin de cette année 2019. Elle apportera un certain nombre de nouvelles fonctionnalités dont celle que j’attends avec la plus grande impatience: les propriétés typées. PHP est un langage dont le code source est librement disponible, il est alors possible de tester les nouveautés du langage au fil du développement de ce dernier.

Compiler PHP peut sembler être une tâche complexe et nécessitant d’installer un certain nombre d’outils avec lequel nous (développeurs PHP) ne sommes pas habitués. Pour éviter ce travail et faciliter l’utilisation de la version de développement de PHP, j’ai décidé d’utiliser Docker. En prenant comme base le dépôt des images officielles, j’ai adapté ces dernières afin de compiler la version en cours de développement de PHP.

J’ai rendu ce travail disponible sur Github et les images sont librement accessibles sur le registre officiel de Docker. Ces dernières sont construites (presque) quotidiennement.

Si vous souhaitez commencer à jouer simplement via le mode interactif de la CLI, rien de plus simple:

$ docker run --rm -it phpdaily/php:7.4.0-dev php -a

Si vous souhaitez tester un code existant, ce n’est guère plus compliqué:

$ docker run --rm -it -v "$PWD:/src" -w /src phpdaily/php:7.4.0-dev php script.php

Il se peut que vous souhaitiez tester des fonctionnalités qui ne soient pas actives de base dans les images. C’est par exemple le cas de l’extension FFI (Foreign Function Interface) qui nécessite des options de compilation spécifiques. Pour utiliser cette dernière, les images Docker mettent en place tout le nécessaire pour que vous puissiez facilement l’installer au sein d’une image personnalisée.

# phpdaily/php:7.4.0-dev est une image basée sur Linux Alpine
FROM phpdaily/php:7.4.0-dev

RUN apk add --no-cache --virtual .persistent-deps libffi-dev \
    && docker-php-ext-configure ffi --with-ffi \
    && docker-php-ext-install ffi

Construisez ensuite l’image Docker correspondante au travers de la commande:

$ docker build -t you/php-ffi .

L’extension sera alors utilisable dans les conteneurs qui seront basés sur votre image (vous pouvez vérifier cela en listant les extensions disponibles docker run --rm -it you/php-ffi php -m).

Toutes les images phpdaily/php étant basées sur les images officielles, vous avez accès aux mêmes possibilités d’utilisation et d’extension que sur ces dernières.

C’est maintenant à vous de jouer !

Déploiement avec Deployer et Gitlab CI

Mon, 03 Sep 2018 00:00:00 +0200

Chez Opéra Energie, la société dans laquelle je travaille, nous développons nos outils en PHP et utilisons Deployer pour le déploiement de nos différents projets. Notre code est hébergé sur une instance Gitlab et c’est tout naturellement que nous utilisons Gitlab CI pour notre intégration continue et le déploiement de nos applications.

Si déployer du code depuis les instances de nos runners Gitlab CI ne posent pas de problème particulier (il est facile d’y déposer une clé SSH autorisant la connexion à nos serveurs de productions et de tests), nous utilisons également les instances des runners Gitlab. Avec ces derniers, il est alors impossible d’y déposer une clé SSH permettant de se connecter à nos serveurs.

Les runners Gitlab que nous utilisons fonctionnent exclusivement sur Docker. Pour le déploiement, nous installons Deployer dans une image php:7-alpine des plus classiques (à laquelle nous avons néanmoins ajouté le nécessaire pour démarrer une connexion SSH, à savoir le paquet openssh-client dans le cas d’une distribution Alpine). Afin de pouvoir s’assurer que nos conteneurs Docker puissent se connecter sur les serveurs qui hébergeront nos applications, nous avons commencé par créer des clés SSH par serveurs (afin de pouvoir avoir une gestion fine d’une éventuelle révocation de ces dernières). Nos clés SSH seront ensuite injectées dans le conteneur qui effectuera le déploiement lors de son démarrage.

Il convient tout d’abord d’ajouter les clés publiques sur chacun des serveurs concernés. Ensuite, dans Gitlab, nous créons des variables Gitlab CI qui contiendront les clés privées que nous avons précédemment générées. Ces dernières sont automatiquement transmises aux runners lors de leurs exécutions.

Une fois Gitlab correctement configuré, il est maintenant possible d’éditer le fichier .gitlab-ci.yml décrivant les actions qui seront réalisées par notre intégration continue. C’est dans ce dernier, que nous allons récupérer le contenu de nos variables d’environnement et ajouter dynamiquement nos clés SSH à l’agent pour ensuite effectuer le déploiement de notre projet :

image: php:7-cli-alpine

stages:
  - deploy

before_script:
    - apk add --update git openssh-client
    - mkdir -p ~/.ssh && echo -e "Host *\n\tStrictHostKeyChecking no\n\n" > ~/.ssh/config
    - eval $(ssh-agent -s)
    - echo "$SERVER_TEST1_KEY" | ssh-add -
    - echo "$SERVER_TEST2_KEY" | ssh-add -
    - echo "$SERVER_PROD1_KEY" | ssh-add -

deploy:app:
    stage: deploy
    script:
        - curl --show-error --silent https://getcomposer.org/installer | php
        - php composer.phar install
        - vendor/bin/dep deploy
    when: manual
    only:
        - master
    environment:
        name: prod
        url: https://my-app.domain.com

Vous remarquerez que le déploiement s’effectuant dans un conteneur Docker et ne pouvant prévoir le serveur sur lequel la tâche sera lancée, nous désactivons un contrôle de la clé SSH via l’option StrictHostKeyChecking no. Cette action n’est à effectuer qu’au sein d’un conteneur Docker et peut-être potentiellement dangereux, car elle permet à des attaques de type man-in-the-middle de pouvoir être effectué.

Et c’est ainsi, en injectant dynamiquement des clés SSH au sein d’un conteneur Docker, qu’il est possible de déployer une application PHP avec Deployer (au n’importe quel autre outil de déploiement en réalité) via des runners Gitlab.

Réalisez vos benchmarks de code PHP avec PHPBench

Mon, 14 May 2018 00:00:00 +0200

Pour mes besoins personnels, je souhaitais tester du code PHP et obtenir certaines données sur l’exécution de ce dernier (temps d’exécution, mémoire consommée, …) sans pour autant sortir l’artillerie lourde. En effectuant quelques recherches, j’ai alors découvert PHPBench qui comme son nom l’indique est un framework de benchmark PHP.

PHPBench permet de réaliser simplement des benchmarks sur du code PHP. Il permet de standardiser l’écriture du code et génère des rapports permettant de comparer différents cas d’utilisation.

Le framework vous propose d’écrire vos benchmarks un peu comme vous écririez un test PHPUnit. Vous allez ainsi commencer par écrire une classe contenant le code que vous souhaitez mesurer.

<?php

namespace Acme;

class TimeConsumer
{
    public function consume()
    {
        usleep(100);
    }
}

Puis le code permettant d’effectuer la mesure:

<?php

use Acme\TimeConsumer;

class TimeConsumerBench
{
    public function benchConsume()
    {
       $consumer = new TimeConsumer();
       $consumer->consume();
    }
}

Il ne restera plus qu’à exécuter le benchmark au travers de la commande : vendor/bin/phpbench run benchmarks --report=default.

Pour plus d’informations et pour découvrir les nombreuses fonctionnalités offertes par l’outil, consultez la documentation officielle.

Améliorez vos applications avec l'analyse statique de code

Fri, 11 May 2018 00:00:00 +0200

Pour corriger des problèmes sur un projet, il est primordial de détecter ces derniers le plus rapidement possible. Effectivement, au plus tôt un problème est détecté et au moins il sera coûteux de résoudre ce dernier. Il est pour cela possible d’avoir recours à de l’analyse statique. Il s’agit d’une opération permettant de détecter automatiquement des erreurs de programmation sans avoir à exécuter de code. Les outils utilisés vont analyser le code source afin de trouver d’éventuelles erreurs et rechercher des modèles de code reconnu comme étant à risque.

Ce billet a été originalement publié sur le blog de la société Novaway dans le cadre de mon travail.

Dans sa forme la plus simple, le mode CLI de PHP propose une option permettant d’analyser un fichier PHP. Il ne s’agit en réalité pas d’une analyse statique, mais plutôt d’une analyse syntaxique (l’opération qui va vérifier que le programme ne contient pas d’erreur de syntaxe). Néanmoins, cela permet d’avoir un premier retour sur le code écrit. Pour effectuer cette opération, il faut utiliser l’argument “-l” de l’interpréteur.

Evaluer l’envergure d’un projet

Obtenir des informations quantifiées sur la taille d’un projet est une opération qui peut s’avérer particulièrement intéressante lors de la prise en main d’un nouveau projet. Un suivi des données recueilli peut également être utile pour mesurer la façon dont le code grossi.

Dans ce cas, PHPLoc est l’outil idéal pour effectuer cette analyse. Ce dernier permet de mesurer rapidement la taille d’un projet PHP et d’en analyser la structure pour ensuite visualiser les résultats sous la forme de statistiques. Cet outil est particulièrement intéressant lors de la prise en main d’un nouveau projet car il permet de se rendre compte de l’envergure de ce dernier.

Les informations fournies par PHPLoc sont exhaustives. Il est possible de connaître le nombre de fichiers composant le projet, le nombre de lignes de code et de commentaires ainsi que le nombre de classes et de méthodes existantes (découpés en fonction de leurs visibilités).

En plus de ces données, PHPLoc fournit des indicateurs sur les dépendances décrites dans le code (utilisation de variables globales, accès direct à des attributs de classes ou l’utilisation de méthodes statiques). Il fournira également quelques informations sur la complexité cyclomatique du projet.

Analyser la complexité du code d’un projet

Il est primordial pour la pérennité d’un projet de pouvoir mesurer la complexité de sa base de code. Cette mesure permet d’avoir des informations sur la facilité de maintenabilité du projet. Des outils d’analyse permettent ainsi de détecter des éventuels problèmes au travers d’un ensemble de règles prédéfinies.

Dans ce sens, PHP Mess Detector (communément appelé PHPMD) vous aidera à identifier les fonctions, méthodes, paramètres ou variables inutilisés. Mais aussi de mettre en évidence des séquences de codes complexes ou des bugs potentiels. Au travers de ces différentes analyses PHPMD sera également capable de proposer des optimisations pour certaines portions de votre projet.

Dans le même esprit, PHP Depend (qui est le portage PHP de JDepend) est une application d’analyse de code et de mesure de la qualité. Les instructions de l’application sont examinées afin de déterminer l’extensibilité, la facilité de réutilisation et de maintenance de la base de code.

Avec l’arrivée de PHP 7, de nouveaux outils ont également fait leur apparition. C’est le cas de Phan. Développé par Etsy, Phan est un analyseur de code statique qui tente de minimiser au maximum les faux positifs. L’outil va se focaliser sur les problèmes les plus fréquents en détectant par exemple les types des paramètres passés aux fonctions et vérifier que ces derniers sont correctement définis.

Respecter les standards de code

Les standards de code sont très importants pour le travail en équipe car ils permettent d’uniformiser la manière dont les développeurs écrivent du code et facilite ainsi la lecture, la compréhension et la prise en main du projet.

Dans ce sens, plusieurs outils sont à la disposition du développeur. Le plus connu et plus ancien est certainement PHP_CodeSniffer. Il s’agit d’un ensemble de scripts qui vont analyser votre code PHP (mais aussi Javascript et CSS) afin de relever les violations de vos standards. En plus de la détection des erreurs, il sera possible de corriger automatiquement les erreurs détectées.

Dans le même esprit, il existe également PHP CS Fixer, un outil plus récent que le précédent et bénéficiant d’une gestion de la configuration plus « actuelle » afin d’éviter d’écrire de la configuration au format XML.

Tester la compatibilité avec une version de PHP

Proposé peu avant l’arrivée de PHP 7, php7cc est l’analyseur de code statique qui vous permettra de faciliter la migration de vos projets PHP 5 vers PHP 7. Une analyse de php7cc vous permettra de détecter les portions de votre code qui ne sont pas compatibles avec les dernières versions du langage et facilitera ainsi la transition vers la dernière branche majeure du langage.

Il existe également une solution nommée PHP CompatInfo qui est une librairie PHP qui va rechercher la version minimum du langage avec laquelle votre code est compatible.

Les solutions complètes

Il existe également des solutions plus complètes et qui permettent de regrouper l’ensemble des analyses citées précédemment. Ma solution préférée est certainement PhpMetrics, une des solution les plus récentes de ce billet.

PhpMetric, tout comme les outils précédents, permet d’analyser un projet pour obtenir des métriques sur la complexité et la maintenabilité du code. Le principal élément différenciateur de ce projet est qu’il se focalise sur les critères de qualité et fait un grand travail sur la présentation des résultats afin que ces derniers puissent être compris et interprétés par des développeurs de tout niveau au travers d’une interface agréable.

Un rapport de démo est disponible sur le site de l’outil afin de se faire une idée des capacités de ce dernier.

Notons également la présence de nombreuses autres solutions telles que SonarQube qui contrairement à l’ensemble des outils présentés jusqu’à maintenant, est un outil multilangage. Ce dernier est entre autres compatibles avec les langages tels que Java, C, C++, Objective-C, JavaScript, Python… Disponible dans une version open source, SonarSource l’éditeur de la solution propose également une version commerciale disponible en SaaS avec un support technique et proposant des analyses pour des langages tel que COBOL, Objective-C, Swift.

Parmi les autres outils existants, on peut également citer :

Scrutinizer, une solution propriétaire massivement utilisée pour analyser la qualité des projets open source
Sensiolabs Insight, le produit de la société Sensiolabs créatrice du framework Symfony
Exakat

Voilà qui conclut notre tour d’horizon des outils d’analyse de code statique. Notons que la plupart des outils évoqués s’intègrent très facilement dans les principaux IDE (PHPStorm, Eclipse, …) et éditeur de textes spécialisés (tels que SublimeText, Atom ou VSCode) de base ou au travers de leurs systèmes d’extensions.

Les solutions d’analyse statique sont nombreuses et il est souvent simple de les mettre en place pour obtenir les premiers rapports et indicateurs qui permettront d’améliorer la qualité d’un projet. Il est important de signaler que les résultats obtenus ne sont intéressants et pertinents que dans le contexte où ils sont mis en place.

Il est également intéressant de signaler, qu’il ne faut pas prendre les recommandations émises par ces outils comme étant une vérité absolue. Les analyses effectuées doivent être mises en place pour indiquer le chemin à suivre et fournir des indicateurs, elles ne remplacent en aucun cas l’expérience d’un développeur.

Les outils de profiling PHP open source

Wed, 09 May 2018 00:00:00 +0200

L’activité de profiling consiste à collecter un certain nombre d’informations sur l’exécution d’un code PHP. Une telle opération est effectuée lorsque l’on souhaite par exemple analyser le code d’un projet pour améliorer sa scalabilité ou encore optimiser ce dernier pour corriger un problème de performance applicative.

Ce billet a été originalement publié sur le blog de la société Novaway dans le cadre de mon travail.

Lorsque Facebook a rendu public XHProf, son outil de profiling dédié à PHP en mars 2009, cela a été une petite révolution pour la communauté. Effectivement avant cet outil, il était nécessaire d’utiliser XDebug, mais ce dernier n’est pas recommandé pour un usage en production car l’activation du mode de profiling entraîne de gros ralentissement de l’application.

Contrairement à XDebug, XHProf a été conçu pour pouvoir être utilisé en production et l’impact sur les performances de l’application est minimal. Un autre avantage et qu’il est possible de profiler uniquement une portion de code. Il sera donc possible de récupérer des données telles que la consommation CPU, la consommation mémoire, le nombre d’appels et le temps passé dans chaque fonction. L’analyse de ces données est facilité par le fait que XHProf fournit l’ensemble des scripts nécessaires à cette opération.

Malheureusement, Facebook se concentre désormais sur le développement de sa machine virtuelle HHVM qui intègre nativement XHProf. De ce fait l’extension PHP n’est actuellement plus maintenue. Si l’extension reste compatible avec les versions 5.x de PHP, il n’est pas possible de l’utiliser avec les versions 7 du fait de changement interne dans la structure du moteur. On a alors vu ces dernières années se développer des solutions de profiling commerciales. La plus en vogue est certainement Blackfire.

Pour remédier à ce problème, les développeurs de la société Tideways ont décidé de forker le projet XHProf et de créer leur propre extension PHP. Cette dernière propose des fonctionnalités équivalentes à XHProf, mais est compatible avec toutes les versions de PHP depuis la version 5.3. Elle est également proposée en open source et disponible sur un dépôt Github.

<?php

include __DIR__ . '/common.php';
include __DIR__ . '/tideways_symfony.php';

tideways_enable();

$kernel = new \Symfony\Component\HttpKernel\Kernel();
$kernel->boot();

$httpKernel = new \Symfony\Component\HttpKernel\HttpKernel();
$httpKernel->handle('indexAction');
$httpKernel->handle('helloAction');

print_spans(tideways_get_spans());

tideways_disable();

Mais le profiling avec l’extension Tideways ne s’arrête pas à un simple fork iso-fonctionnel de XHProf, puisque les développeurs ont également ajouté des fonctionnalités supplémentaires telles que notamment la détection du framework exécutant le code “profilé” afin d’ajouter des informations essentielles et de diminuer “le bruit généré” par le code du framework. À l’heure de l’écriture de ce billet, l’extension supporte 13 frameworks.

L’extension fait maintenant partie du cœur de la solution “Tideways Profiler Platform” une solution commerciale SaaS proposée par la société. Cette partie commerciale n’est en rien obligatoire, mais apporte notamment une interface de visualisation des informations remontées par l’application ainsi qu’un stockage de ces dernières directement sur les serveurs de la société.

Au final, les solutions de profiling open source sont rares, mais existantes. Bien que XHProf ne soit aujourd’hui plus maintenu par Facebook pour PHP, l’extension fournie par Tideways est une excellente alternative aux diverses solutions commerciales existantes. Il sera cependant nécessaire de passer par une phase de configuration et de trouver l’outil nécessaire pour traiter les données de profiling. Cela reste certainement la meilleure solution pour des besoins ponctuels. Si par contre vous souhaitez avoir une solution fonctionnelle rapidement et avec un minimum d’effort, vous pourrez vous tourner vers les nombreuses solutions SaaS existantes.

D’ailleurs si vous souhaitez tester le profiling avec Tideways, n’hésitez pas à télécharger les stubs de l’extension afin d’avoir une auto-complétion dans votre IDE préféré.

Tutorial Jobeet pour Symfony 4 - Partie 6: Aller plus loin avec le modèle

Sat, 24 Feb 2018 00:00:00 +0100

Notre application Jobeet commence à devenir utilisable. Nous savons maintenant créer des pages, les afficher et naviguer entre elles en utilisant le framework Symfony via les différents composants qui sont à notre disposition. Attardons-nous un peu sur la couche modèle de notre projet.

Cette dernière est actuellement composée de nos entités (les classes qui représentent les données stockées en base). Nous allons dans ce chapitre, travailler sur l’optimisation de notre code, ce qui vous permettra d’en apprendre un peu plus sur le sujet.

Revenons sur nos différents scénarios et plus précisément sur le scénario F1: En tant qu'utilisateur, je vois les dernières offres actives sur la page d'accueil. Car si vous avez bien suivi ce que nous avons réalisé, la page d’accueil liste actuellement toutes les offres d’emploi aussi bien celles qui sont actives que celles qui ne le sont pas.

Un emploi est considéré actif s’il a été posté il y a moins de 30 jours. Commençons par modifier la requête effectuée dans la méthode JobController::index :

<?php // src/Controller/JobController.php

namespace App\Controller;

// ...
use DateTime;

class JobController extends AbstractController
{
    public function index(EntityManagerInterface $em): Response
    {
        $queryBuilder = $em->getRepository(Job::class)->createQueryBuilder('j');
        $queryBuilder->andWhere('j.createdAt > :date');
        $queryBuilder->setParameter('date', new DateTime('-30 day'));
        $jobs = $queryBuilder->getQuery()->getResult();

        return $this->render('job/index.html.twig', [
            'jobs' => $jobs,
        ]);
    }
}

Pour écrire une requête “complexe”, nous utilisons l’objet QueryBuilder fourni par Doctrine et qui permet comme son nom l’indique de créer une requête compréhensible par l’ORM sans devoir écrire de code SQL. L’avantage est que Doctrine adaptera la requête au type de base de données avec lequel il communique (SQLite, MySQL, PostgresSQL, …). L’inconvénient est que cela masque complètement la requête qui est générée.

Notre requête commence à devenir plus complexe et il devient intéressant de l’extraire de notre contrôleur pour que cette dernière puisse être réutilisée sans devoir dupliquer le code. Jusqu’à maintenant, la méthode EntityManager::getRepository nous permettait d’obtenir un objet générique que Doctrine utilise pour fournir des méthodes de base permettant de faire des requêtes en base de données.

Nous allons maintenant définir une classe de type Repository. Les objets de types Repository contiennent des méthodes permettant de récupérer des données en base. Définissons donc une classe JobRepository, qui comme son nom l’indique, nous permettra de récupérer des données liées aux offres d’emploi.

<?php // src/Repository/JobRepository.php

namespace App\Repository;

use DateTime;
use Doctrine\ORM\EntityRepository;

class JobRepository extends EntityRepository
{
    public function findActive(DateTime $date)
    {
        return $this->createQueryBuilder('j')
            ->andWhere('j.createdAt > :date')
            ->setParameter('date', $date)
            ->getQuery()
            ->getResult();
    }
}

Une fois notre classe créée, nous allons devoir modifier la configuration du mapping de l’entité Job pour indiquer à Doctrine la classe que l’ORM devra utiliser pour accéder aux données. Cela se passe dans le fichier config/doctrine/mapping/Job.orm.yml.

# config/doctrine/mapping/Job.orm.yml
App\Entity\Job:
    type: entity
    repositoryClass: App\Repository\JobRepository

    # ...

Pour finir, supprimons le code du contrôleur pour utiliser notre nouvelle classe :

<?php // src/Controller/JobController.php

namespace App\Controller;

// ...

class JobController extends AbstractController
{
    public function index(EntityManagerInterface $em): Response
    {
        $jobs = $em->getRepository(Job::class)->findActive(new DateTime('-30 day'));

        return $this->render('job/index.html.twig', [
            'jobs' => $jobs,
        ]);
    }
}

Et voilà, nous utilisons maintenant une classe pour la récupération des données de notre offre d’emploi, ce qui permet d’isoler le code dédié à la récupération des données et permet ainsi d’améliorer la maintenabilité de notre projet.

Il est possible de consulter la requête générée par Doctrine en consultant les logs générés par l’application. Par défaut, Symfony crée les logs sur la sortie standard et son donc consultable directement sur le terminal.

2018-02-10T19:32:20+01:00 [debug] SELECT j0_.id AS id_0, j0_.type AS type_1, j0_.company AS company_2, j0_.logo AS logo_3, j0_.url AS url_4, j0_.position AS position_5, j0_.location AS location_6, j0_.description AS description_7, j0_.how_to_apply AS how_to_apply_8, j0_.token AS token_9, j0_.is_public AS is_public_10, j0_.is_activated AS is_activated_11, j0_.email AS email_12, j0_.expires_at AS expires_at_13, j0_.created_at AS created_at_14, j0_.updated_at AS updated_at_15, j0_.category_id AS category_id_16 FROM job j0_ WHERE j0_.created_at > ?

Un moyen plus simple d’accéder à ces informations est d’installer le composant symfony/profiler-pack.

$ composer require symfony/profiler-pack --dev

Ce dernier permet la mise en place d’une interface graphique qui affiche un certain nombre d’informations sur votre application. Chaque bundle peut ainsi y afficher des données. Cette interface ajoute une barre permettant d’avoir un résumé des informations disponibles :

Il est également possible d’accéder à un détail des informations récupérées en cliquant sur l’icône du composant concerné :

Pour l’heure, notre code est encore loin d’être parfait. Pour récupérer toutes les offres actives, nous sommes systématiquement obligés de passer en paramètre la date à partir de laquelle les offres sont visibles. Cela revient à dupliquer le calcul de la date et serait source d’erreurs. Pour corriger ce problème, nous allons créer une constante qui nous permettra de masquer ce calcul. Et pour optimiser notre requête, nous allons utiliser le champ expiresAt afin de stocker la date d’expiration d’une offre plutôt que de devoir la calculer.

Tout comme pour les dates de création et de modification de nos offres d’emploi, nous allons utilisons le gestionnaire d’événement de Doctrine pour mettre à jour la valeur du champ automatiquement. Commençons par ajouter le code nécessaire à notre entité :

<?php // src/Entity/Job.php

namespace App\Entity;

// use ...

class Job
{
    public const OFFER_LIFETIME = 30; // durée de vie d'une offre en jours

    // ...

    public function setExpiresAtValue(LifecycleEventArgs $event): self
    {
        // nous remplissons automatiquement la date d'expiration si cette dernière n'a pas été saisie
        // manuellement
        if (!$this->expiresAt) {
            $this->expiresAt = new DateTime('+'.self::OFFER_LIFETIME.' day');
        }

        return $this;
    }
}

N’oublions pas d’ajouter la configuration liée à cette gestion d’événement.

# config/doctrine/mapping/Job.orm.yml
App\Entity\Job:
    # ...
    lifecycleCallbacks:
        prePersist: [ setCreatedAtValue, setExpiresAtValue ]

Nous pouvons maintenant mettre à jour notre requête :

<?php // src/Repository/JobRepository.php

namespace App\Repository;

use DateTime;
use Doctrine\ORM\EntityRepository;

class JobRepository extends EntityRepository
{
    public function findActive()
    {
        return $this->createQueryBuilder('j')
            ->andWhere('j.expiresAt >= :date')
            ->setParameter('date', new DateTime())
            ->getQuery()
            ->getResult();
    }
}

N’oubliez pas d’enlever le paramètre dans l’appel de la méthode dans la classe JobController::index

Le code de notre application est maintenant plus simple et plus maintenable, mais si nous voulons pouvoir tester que tout fonctionne correctement, encore faut-il mettre à jour nos données de test. Car dans les données actuelles, nous avons défini une date d’expiration des offres au 10/10/2012 et nous ne voyons donc maintenant plus aucune offre. Supprimons les dates d’expiration de notre jeu actuel et ajoutons une offre expirée (consultez directement ce fichier pour avoir le code correspondant).

En rechargeant les fixtures au travers de la commande bin/console doctrine:fixtures:load, l’affichage ne devrait pas avoir changé, mais si vous regardez les données en base, vous constaterez qu’il y a pourtant bien 3 offres d’emploi enregistrées.

Si nous revenons à nos scénarios utilisateurs, nous avons spécifié que les offres devaient être classées par catégories, ce qui n’est actuellement pas le cas. Pour répondre à ce besoin, nous allons créer une classe de type Repository pour notre entité Category. Cette dernière nous permettra de lister les catégories existantes avec les offres d’emploi correspondantes.

Commençons par modifier le mapping Doctrine :

# config/doctrine/mapping/Job.orm.yml
App\Entity\Category:
    type: entity
    repositoryClass: App\Repository\CategoryRepository

    # ...

Créons maintenant la classe correspondante avec la nouvelle méthode de récupération des offres par catégorie :

<?php // src/Entity/CategoryRepository.php

declare(strict_types=1);

namespace App\Repository;

use DateTime;
use Doctrine\ORM\EntityRepository;

class CategoryRepository extends EntityRepository
{
    public function findCategoriesWithJobs()
    {
        return $this->createQueryBuilder('c')
            ->join('c.jobs', 'j')
            ->where('j.expiresAt >= :date')
            ->setParameter('date', new DateTime())
            ->getQuery()
            ->getResult();
    }
}

La requête Doctrine a été construite via le QueryBuilder. Doctrine implémente également son propre langage de requête appelé DQL (dérivé du SQL). Le QueryBuilder tout comme le DQL se base sur nos entités pour construire les requêtes effectuées en base de données, cela permet ensuite à Doctrine de créer les objets correspondants.

Utilisons maintenant cette dernière dans l’affichage de notre homepage :

<?php // src/Controller/JobController.php

namespace App\Controller;

// ...

class JobController extends AbstractController
{
    public function index(EntityManagerInterface $em): Response
    {
        $categories = $em->getRepository(Category::class)->findCategoriesWithJobs();

        $jobsCategories = [];
        foreach ($categories as $category) {
            $jobsCategories[$category->getName()] = $em->getRepository(Job::class)->findActiveByCategory($category);
        }

        return $this->render('job/index.html.twig', [
            'categories' => $jobsCategories,
        ]);
    }
}

Ajoutons la méthode permettant de récupérer les offres actives d’une catégorie :

<?php // src/Entity/JobRepository.php

declare(strict_types=1);

namespace App\Repository;

use DateTime;
use Doctrine\ORM\EntityRepository;

class JobRepository extends EntityRepository
{
    public function findActiveByCategory(Category $category)
    {
        return $this->createQueryBuilder('j')
            ->where('j.category = :category')
            ->andWhere('j.expiresAt >= :date')
            ->setParameter('category', $category)
            ->setParameter('date', new DateTime())
            ->getQuery()
            ->getResult();
    }
}

Modifions ensuite le template en conséquence :

{# templates/job/index.html #}
{% extends "base.html.twig" %}

{% block body %}
    <h1 class="my-4">Liste des offres</h1>

    {% for category, jobs in categories %}
        <div class="row">
            <h2 style="font-weight: bold; margin: 2rem 0;">{{ category }}</h2>

            {% for job in jobs %}
                <div class="row">
                    <div class="col-md-7">
                        <a href="#">
                            <img class="img-fluid rounded mb-3 mb-md-0" src="{{ asset('images/' ~ job.logo) }}" alt="{{ job.company }}">
                        </a>
                    </div>
                    <div class="col-md-5">
                        <h3>{{ job.position }}</h3>
                        <p>{{ job.description }}</p>
                        <p>Posted on {{ job.createdAt|date("m/d/Y") }}</p>
                        <a class="btn btn-primary" href="{{ path('job_show', { 'id': job.id, 'company': job.companySlug, 'location': job.locationSlug, 'position': job.positionSlug }) }}">See more</a>
                    </div>
                </div>

                <hr>
            {% endfor %}
        </div>
    {% endfor %}

    <ul class="pagination justify-content-center">
        <li class="page-item disabled">
            <a class="page-link" href="#" aria-label="Previous">
                <span aria-hidden="true">&laquo;</span>
                <span class="sr-only">Previous</span>
            </a>
        </li>
        <li class="page-item">
            <a class="page-link" href="#">1</a>
        </li>
        <li class="page-item disabled">
            <a class="page-link" href="#" aria-label="Next">
                <span aria-hidden="true">&raquo;</span>
                <span class="sr-only">Next</span>
            </a>
        </li>
    </ul>
{% endblock %}

Pour finir, nous allons sécuriser la page de consultation des offres. Effectivement, si vous connaissez l’URL d’une offre, il est possible d’accéder à cette dernière, et ce, même si la date d’expiration est dépassée. Pour cela, rajouter un contrôle dans notre action d’affichage :

<?php // src/Controller/JobController.php

namespace App\Controller;

// ...
use DateTime;

class JobController extends AbstractController
{
    public function show(EntityManagerInterface $em, int $id, string $company, string $location, string $position) : Response
    {
        // dans un projet réel, il sera nécessaire de faire une requête permettant de vérifier que tous les éléments
        // correspondent à une offre d'emploi valide
        $job = $em->getRepository(Job::class)->find($id);
        if (null === $job) {
            throw new NotFoundHttpException();
        }

        $currentDate = new DateTime();
        if ($job->getExpiresAt() < $currentDate) {
            throw new NotFoundHttpException();
        }

        return $this->render('job/show.html.twig', [
            'job' => $job,
        ])
}

Retrouvez tous les tutorials Jobeet disponibles depuis le billet d’introduction de la série. Le code source de cette application est également disponible sur Github. Vous trouverez une branche associée à l’état du projet après chaque chapitre.

Symfony 4 et les tests avec le logger par défaut

Wed, 06 Dec 2017 00:00:00 +0100

Symfony 4 est sortie il y a quelques jours. Ce dernier est dorénavant fourni avec un minimum de dépendances. Monolog n’étant plus fourni par défaut, un logger proposant le strict nécessaire est inclus par défaut. Ce dernier, compatible PSR-3, va logger les informations par défaut sur la sortie standard. Ce fonctionnement peut ne pas être sans impact sur vos tests.

Effectivement, certains frameworks de tests interpréteront les sorties sur la sortie standard comme un défaut de fonctionnement et considérons de ce fait votre test comme échoué.

Pour cela, il sera peut-être nécessaire dans vos tests de remplacer le logger par défaut par le Psr\Log\NullLogger.

PHP Meminfo, l'extension qui vous fait voyager dans la mémoire PHP

Thu, 23 Nov 2017 00:00:00 +0100

Savez-vous vraiment comment est consommé la mémoire de votre application PHP ? Si la réponse est non, alors devriez considérer l’utilisation de PHP Meminfo.

PHP Meminfo est une extension PHP vous permettant d’avoir un aperçu de l’utilisation de la mémoire de vos scripts PHP. Cette dernière a été créé dans le but de comprendre l’origine des fuites mémoires de vos applications et de mieux comprendre le comportement de cette dernière.

L’extension vient tout récemment de sortir sa version 1.0.0 apportant notamment un support de PHP 7 et fournit une documentation plus complète.

En bonus, si vous êtes sous macOS et que vous utilisez Homebrew en tant que gestionnaire de paquet, vous aurez la possibilité d’installer très facilement l’extension sur votre système, un paquet étant disponible pour chaque version de PHP.

Tutorial Jobeet pour Symfony 4 - Partie 5: Les routes

Mon, 16 Oct 2017 00:00:00 +0200

Vous connaissez maintenant le principe d’une architecture MVC et comment cette dernière se met en place au sein d’un projet Symfony. Nous avons également rapidement évoqué le principe du routage (ou routing en anglais). Ce chapitre sera entièrement consacré à ce dernier point.

Dans un contexte web, une URL (Uniform Resource Locator) désigne un contenu accessible. Lorsque vous accédez à une page au travers de son URL, vous demandez au navigateur d’aller cherche un contenu identifié. C’est cette information que nous allons devoir décrire dans notre projet.

Dans la section consacrée au contrôleur et à la vue, nous avons commencé à modifier le fichier config/routes.yaml qui permet de faire le lien entre l’URL courante du navigateur et l’action de notre contrôleur devant être exécutée. Nous ne sommes pas rentré dans les détails, mais une route est définie par un nom, un schéma d’URL ainsi que le contrôleur avec la méthode associée.

C’est le composant Routing de Symfony qui s’occupe d’établir la correspondance entre notre configuration et le code de notre projet. Signalons que si deux routes possèdent le même nom, la seconde route écrase la première. De ce fait la première configuration ne sera jamais prise en compte.

Dans l’état actuel de notre projet, notre fichier config/routes.yaml contient la configuration suivante :

# config/routes.yaml
index:
    path: /
    defaults: { _controller: 'App\Controller\JobController::index' }

# Depends on sensio/framework-extra-bundle, doctrine/annotations, and doctrine/cache
#   install with composer req sensio/framework-extra-bundle annot
#controllers:
#    resource: ../src/Controller/
#    type: annotation

Une seule route y est déclarée. Cette dernière correspond à la page d’accueil de notre application qui liste les offres d’emploi disponible. Ajoutons maintenant une route qui permettra d’afficher le détail d’une offre.

Les offres d’emploi sont créées dynamiquement par un utilisateur. Pour accéder au détail d’une offre, nous allons faire référence à son identifiant unique de base de données (autrement dit, la propriété $id de notre classe Job). Nous allons créer une route qui contiendra un paramètre dynamique permettant de récupérer cette information et de la transmettre à notre action.

Modifions le fichier de configuration en conséquence :

# config/routes.yaml
index:
    path: /
    defaults: { _controller: 'App\Controller\JobController::index' }

job_show:
    path: /job/{id}
    defaults: { _controller: 'App\Controller\JobController::show' }

# Depends on sensio/framework-extra-bundle, doctrine/annotations, and doctrine/cache
#   install with composer req sensio/framework-extra-bundle annot
#controllers:
#    resource: ../src/Controller/
#    type: annotation

Nous venons donc de rajouter une nouvelle route nommée job_show qui correspond à l’appel de la méthode show de notre classe JobController. Le paramètre de la route est indiqué entre crochet ({id}), ce dernier correspond au nom de la variable qui sera automatiquement passé à la méthode du contrôleur.

Sur notre environnement de développement local, il sera possible d’accéder à une offre d’emploi au travers de l’URL http://localhost:8000/job/1 ou http://localhost:8000/job/2

Ajoutons maintenant l’action correspondante dans notre contrôleur :

<?php // src/Controller/JobController.php

namespace App\Controller;

use App\Entity\Job;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

class JobController extends AbstractController
{
    // ...

    public function show(EntityManagerInterface $em, int $id): Response
    {
        $job = $em->getRepository(Job::class)->find($id);
        if (null === $job) {
            throw new NotFoundHttpException();
        }

        return $this->render('job/show.html.twig', [
            'job' => $job,
        ]);
    }
}

La vue affichée par cette action ne sera pas détaillée car elle ne présente pas d’intérêt pour le routing. Je vous invite à récupérer le contenu du fichier directement sur le dépôt du projet.

Nous découvrons dans ce contrôleur comment décrire une route contenant un paramètre dynamique. Dans l’exemple précédent, le paramètre $id est automatiquement extrait de l’URL et transmis à l’action de notre contrôleur. Symfony faisant correspondre le nom du paramètre de notre configuration avec le nom de la variable de présent dans la définition de notre action.

Notons au passage l’utilisation de la méthode find de Doctrine permettant de récupérer l’objet via sa clé primaire de base de données.

Après avoir effectué notre requête en base de données avec Doctrine, il convient de contrôler que l’identifiant transmis correspond bien à une offre d’emploi. Si ce n’est pas le cas, nous générons une exception afin d’indiquer que l’utilisateur tente d’accéder à une ressource qui n’existe pas.

La classe Symfony\Component\HttpKernel\Exception\NotFoundHttpException est une exception fournie par le composant HttpFundation de Symfony. Elle permet de lancer d’indiquer au framework que l’erreur rencontrée est de type “ressource introuvable”. Le framework générera ainsi automatiquement une réponse renvoyant le code HTTP 404 au navigateur.

Nous avons créé une route qui permet de capter un paramètre correspondant à l’identifiant d’une offre d’emploi. Mais à ce stade, nous n’avons défini aucune restriction sur ce paramètre. Une donnée de type numérique est attendue, mais actuellement rien n’empêche un utilisateur d’entrer une URL du type /job/mon-offre. Cette adresse est valide mais va provoquer une erreur car nous avons indiqué dans notre action que la paramètre $id était de type int.

Pour éviter ce problème, il est possible de définir des règles de validations des adresses pouvant être captées par nos routes. Ajoutons donc un prérequis sur le paramètre {id} afin d’indiquer que ce dernier ne doit prendre en compte que les valeurs numériques entières.

# config/routes.yaml

# ...
job_show:
    path: /job/{id}
    defaults: { _controller: 'App\Controller\JobController::show' }
    requirements:
        id: '\d+'

# ...

Pour définir une contrainte sur un paramètre de notre URL, nous utilisons le mot-clé requirements qui permet de définir une liste de prérequis. Dans l’exemple précédent, nous spécifions que le paramètre id doit être de valeur numérique.

Le format des validateurs est en réalité une expression régulière. Le format raccourci \d+ correspond en réalité à l’expression [0-9]+.

Si nous réfléchissons d’un point de vue SEO, nos URL de type /job/1 ne sont pas très explicites et pourraient pénaliser notre référencement dans les moteurs de recherche. Une URL du type /job/sensio-labs/1/web-developer serait plus pertinente car elle décrit mieux la ressource à laquelle elle fait référence. Effectuons cette modification :

# config/routes.yaml

# ...
job_show:
    path: /job/{company}/{location}/{id}/{position}
    defaults: { _controller: 'App\Controller\JobController::show' }
    requirements:
        id: '\d+'
        company: '[A-Za-z0-9\-]+'
        location: '[A-Za-z0-9\-]+'
        position: '[A-Za-z0-9\-]+'

# ...

Et adaptons notre classe JobController en conséquence :

<?php // src/Controller/JobController.php

namespace App\Controller;

use App\Entity\Job;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

class JobController extends AbstractController
{
    // ...

    public function show(EntityManagerInterface $em, int $id, string $company, string $position, string $location): Response
    {
        // Faire les contrôles sur les variables $company et $position
        // ou les inclures dans la requête SQL
        $job = $em->getRepository(Job::class)->find($id);
        if (null === $job) {
            throw new NotFoundHttpException();
        }

        return $this->render('job/show.html.twig', [
            'job' => $job,
        ]);
    }
}

Nous n’implémenterons pas les requêtes ni les vérifications, ce n’est pas l’objectif de ce tutorial. Qui se concentre sur l’écriture d’une application avec Symfony.

Maintenant que nous avons ajouté notre page permettant de visualiser le détail d’une offre d’emploi, nous allons devoir mettre à jour les liens permettant à un utilisateur de naviguer au sein de notre application. Pour faciliter la navigation entre les pages dans nos templates Twig, le module TwigBridge met en place des fonctions permettant de faire référence à une page au travers du nom de la route associée. C’est notamment le cas de la fonction path. Cette dernière prend en paramètre le nom de la route à laquelle nous allons faire référence ainsi que les différentes variables nécessaires à la génération de l’URL.

<!-- templates/job/index.html.twig -->
{% extends "base.html.twig" %}

{% block body %}
    <h1 class="my-4">Liste des offres</h1>

    {% for job in jobs %}
        <div class="row">
            <div class="col-md-7">
                <a href="#">
                    <img class="img-fluid rounded mb-3 mb-md-0" src="{{ asset('images/' ~ job.logo) }}" alt="{{ job.company }}">
                </a>
            </div>
            <div class="col-md-5">
                <h3>{{ job.position }}</h3>
                <p>{{ job.description }}</p>
                <p>Posted on {{ job.createdAt|date("m/d/Y") }}</p>
                <a class="btn btn-primary" href="{{ path('job_show', { 'id': job.id, 'company': job.companySlug, 'location': job.locationSlug, 'position': job.positionSlug }) }}">See more</a>
            </div>
        </div>

        <hr>
    {% endfor %}

    <!-- ... -->
{% endblock %}

Pour générer le lien vers une offre d’emploi, nous avons utilisé les propriétés job.companySlug, job.locationSlug et job.positionSlug de notre classe Job. Ces dernières correspondent en réalité à des appels de méthode (au besoin, je vous invite à relire le chapitre concernant Twig pour plus d’informations). L’implémentation des méthodes ne sera pas détaillée, consultez le code source de la classe pour plus de détails.

Au fur et à mesure que nous allons ajouter des fonctionnalités à notre application, cette dernière va grossir et contenir de plus en plus de code et de configuration. Il peut être parfois utile de lister l’ensemble des routes disponibles sans pour autant devoir parcourir les différents fichiers de configuration. Pour cela, Symfony met à disposition des développeurs une commande permettant d’afficher ces dernières :

Cette commande permet également d’obtenir des informations détaillées sur une route. Il suffit pour cela d’indiquer le nom de la route en question :

Ce chapitre a introduit la notion de route et explique comment créer des liens entre les pages de votre application. Vous avez ainsi appris à utiliser le composant Routing de Symfony. Le prochain sera consacré à l’approfondissement du concept de modèle. Nous y expliquerons plus en détail comment structurer l’information et faire des requêtes complexes.

Retrouvez tous les tutorials Jobeet disponibles depuis le billet d’introduction de la série. Le code source de cette application est également disponible sur Github. Vous trouverez une branche associée à l’état du projet après chaque chapitre.

Proxifier des requêtes HTTP en PHP

Wed, 11 Oct 2017 00:00:00 +0200

Ce soir, je me suis demandé comment il était possible de “proxifier” une requête HTTP effectuée depuis un script PHP. Pour être plus précis, je souhaitais faire une requête sur le réseau TOR (ou via n’importe quel proxy de manière générale) via une commande PHP.

En fait cela est beaucoup plus simple que je ne le pensais car l’extension CURL de PHP contient tout le nécessaire pour réaliser cette tâche. Il suffit pour cela de passer les bonnes options à notre ressource :

<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://check.torproject.org');
curl_setopt($ch, CURLOPT_PROXY, 'localhost:9150'); // l'URL de notre proxy
curl_setopt($ch, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS5); // le type du proxy
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 0);
curl_setopt($ch, CURLOPT_HEADER, 1);
$curl_scraped_page = curl_exec($ch);
curl_close($ch);

echo $curl_scraped_page;

Si vous utilisez une bibliothèque type Guzzle, ces dernières fournissent généralement tout le nécessaire pour proxifier vos requêtes HTTP.

D’ailleurs concernant cette dernière, j’ai trouvé un middleware megahertz/guzzle-tor dédié à la mise en place d’une connexion via TOR.

Tutorial Jobeet pour Symfony 4 - Partie 4B: La gestion des assets avec Twig

Sat, 30 Sep 2017 00:00:00 +0200

Dans la section précédente, nous avons commencé à afficher nos premières pages et avons défini une charte graphique. Nous avons donc inclus un certain nombre de fichiers CSS, Javascript et utilisé des images. Voyons avant de continuer quelques bonnes pratiques sur la gestion des assets.

Les assets sont des fichiers statiques qui sont utilisés par l’interface de notre site. Il peut s’agir de fichiers CSS (pour la mise en page et la charte graphique du site), Javascripts (pour gérer l’interactivité de notre interface avec l’utilisateur), d’images ou par exemple des fichiers pouvant être téléchargées par l’utilisateur.

Tout d’abord, revoyons notre template base.html.twig qui inclut nos différentes feuilles de style :

# templates/base.html.twig
<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
        <title>{% block title %}Jobeet{% endblock %}</title>
        <link rel="stylesheet" href="/vendor/bootstrap/css/bootstrap.min.css">
        <link rel="stylesheet" href="/vendor/1-col-portfolio.css">
        {% block stylesheets %}{% endblock %}
    </head>
    <body>
        <nav class="navbar navbar-expand-lg navbar-dark bg-dark fixed-top">
            <div class="container">
                <a class="navbar-brand" href="#">Jobeet</a>
                <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarResponsive" aria-controls="navbarResponsive" aria-expanded="false" aria-label="Toggle navigation">
                    <span class="navbar-toggler-icon"></span>
                </button>
            </div>
        </nav>

        <div class="container">
            {% block body %}{% endblock %}
        </div>

        <script src="/vendor/jquery/jquery-3.2.1.slim.min.js"></script>
        <script src="/vendor/popper/popper.min.js"></script>
        <script src="/vendor/bootstrap/js/bootstrap.min.js"></script>
        {% block javascripts %}{% endblock %}
    </body>
</html>

Pour inclure nos différents fichiers, nous avons spécifié le chemin complet pour accéder à nos ressources. Cette pratique n’est pas recommandée car elle possède de nombreux désavantages :

Elle rend nos templates verbeux en nous obligeant à écrire pour chaque fichier le chemin complet pour y accéder.
Le versionnement des fichiers est compliqué car il nécessite d’être géré manuellement pour chaque ressource.
Le déplacement des assets peut être source d’erreurs.
L’utilisation d’un CDN est impossible avec cette gestion manuelle.

Afin de résoudre toutes ces problématiques, il existe de nombreux composants PHP permettant de mettre en place une gestion d’asset simple, efficace et maintenable. Symfony propose également un composant pour ça, installons-le :

$ composer require symfony/asset

Using version ^3.3 for symfony/asset
./composer.json has been updated
Loading composer repositories with package information
Updating dependencies (including require-dev)
Package operations: 1 install, 0 updates, 0 removals
  - Installing symfony/asset (v3.3.9): Downloading (100%)
Writing lock file
Generating autoload files
Executing script make cache-warmup [OK]
Executing script assets:install --symlink --relative public [OK]

Une fois téléchargé, le composant est tout de suite prêt à être utilisé dans notre projet. Lors de notre découverte de Twig, nous avons rapidement évoqué le composant TwigBridge comme étant un module permettant d’étendre le fonctionnement de Twig en ajoutant des fonctionnalités spécifiques aux différents modules de de Symfony. Le composant Asset en fait partie. TwigBridge fournit ainsi une fonction asset permettant d’accéder à une ressource.

Modifions notre template d’origine :

# templates/base.html.twig
<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
        <title>{% block title %}Jobeet{% endblock %}</title>
        <link rel="stylesheet" href="{{ asset('vendor/bootstrap/css/bootstrap.min.css') }}">
        <link rel="stylesheet" href="{{ asset('vendor/1-col-portfolio.css') }}">
        {% block stylesheets %}{% endblock %}
    </head>
    <body>
        <nav class="navbar navbar-expand-lg navbar-dark bg-dark fixed-top">
            <div class="container">
                <a class="navbar-brand" href="#">Jobeet</a>
                <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarResponsive" aria-controls="navbarResponsive" aria-expanded="false" aria-label="Toggle navigation">
                    <span class="navbar-toggler-icon"></span>
                </button>
            </div>
        </nav>

        <div class="container">
            {% block body %}{% endblock %}
        </div>

        <script src="{{ asset('vendor/jquery/jquery-3.2.1.slim.min.js') }}"></script>
        <script src="{{ asset('vendor/popper/popper.min.js') }}"></script>
        <script src="{{ asset('vendor/bootstrap/js/bootstrap.min.js') }}"></script>
        {% block javascripts %}{% endblock %}
    </body>
</html>

Nous pouvons également modifier l’affichage de l’image d’une offre d’emploi dans le fichier templates/job/index.html.twig. Notons au passage l’utilisation de l’opérateur de concaténation de chaine de caractère Twig ~.

Peut-être que vous ne remarquez que très peu de différences. Pour le moment, nous avons juste utilisé notre fonction asset mais le code reste le même et le chemin vers le fichier est toujours présent.

S’il y a peu de différences, c’est tout d’abord parce que nous avons placé nos fichiers dans le répertoire public (qui est le point d’entrée du serveur HTTP pour rechercher nos fichiers accessibles publiquement). C’est donc le répertoire où le composant Asset va rechercher nos fichiers par défaut.

Imaginons que nous souhaitons changer le répertoire contenant nos ressources, pour par exemple le déplacer dans un sous-répertoire public/assets. Il ne sera maintenant plus nécessaire de modifier tous les chemins des fichiers que nous avons utilisés. Il suffira de modification la configuration du framework afin de spécifier le répertoire racine qui contient nos assets comme dans l’exemple ci-dessous :

# config/packages/framework.yml
framework:
    # ...
    assets:
        base_path: '/assets'

Au travers de cet exemple, il est possible de commencer à voir les avantages d’utiliser un composant pour gérer nos ressources. Une autre des fonctionnalités majeures du module Asset est la gestion du versionnement des fichiers. Pour plus d’informations sur le versionnement des assets, je vous propose de consulter la documentation officielle qui fournira tous les informations utiles.

Si vous souhaitez spécifier une version d’asset dans notre projet, voici la configuration que vous allez devoir renseigner :

# config/packages/framework.yml
# app/config/config.yml
framework:
    # ...
    assets:
        version: 'v2' # asset('/images/logo.png') ==> /images/logo.png?v2

Le versionnement des assets est très utile pour gérer la mise en cache de nos ressources. C’est une pratique courante pour optimiser les données devant être renvoyées par les serveurs HTTP et économiser des appels réseaux.

Avant de terminer sur la gestion des ressources, évoquons une dernière fonctionnalité essentielle : la gestion des CDN.

Un Content Delivery Network (CDN ou réseau de diffusion de contenu en français) est une plate-forme de serveurs hautement distribuée optimisée pour diffuser du contenu. Les CDN ont l’avantage d’accélérer le chargement des pages.

Pour mettre en place la gestion d’un CDN, il suffit comme pour le versionnement des ressources, de spécifier les domaines qui vont être utilisés dans le fichier de configuration. Symfony sélectionnera un domaine (si vous n’en spécifiez pas un lors de l’utilisaton de la fonction asset) à chaque génération d’un page.

# config/packages/framework.yml
framework:
    # ...
    assets:
        base_urls:
            - 'http://cdn.example.com/' # asset('/images/logo.png') ==> http://cdn.example.com/images/logo.png

Retrouvez tous les tutorials Jobeet disponibles depuis le billet d’introduction de la série. Le code source de cette application est également disponible sur Github. Vous trouverez une branche associée à l’état du projet après chaque chapitre.

Tutorial Jobeet pour Symfony 4 - Partie 4A: Le contrôleur et la vue

Fri, 29 Sep 2017 00:00:00 +0200

Nous avons jusqu’à présent entrevu le fonctionnement de Doctrine en créant une base de données et en y insérant un jeu de données afin d’avoir des données initiales, nous évitant ainsi d’avoir une application vide. Nous allons maintenant pouvoir commencer à afficher nos premières pages web.

Un projet Symfony repose sur le pattern MVC (Model View Controller ou Model Vue Contrôleur en français). Ce type d’architecture permet d’organiser le code en le séparant en trois couches :

La couche modèle contenant le traitement logique de vos données (on y retrouve les traitements métier, les accès à la base de données, …).
La vue est la modélisation de l’IHM (Interface Homme Machine). Elle représente ce qui est rendu à l’utilisateur (sous la forme d’une page Web, d’une commande d’un terminal, de données JSON/XML, …).
Le contrôleur correspond au code faisant le lien entre le modèle et la vue. Il récupère les données utilisateurs pour y appliquer les traitements et donner les résultats à la vue. Démarrons par ce dernier. Comme nous venons brièvement de le dire, le contrôleur est la couche qui va exécuter les traitements liés à notre application et transmettre les résultats à la vue pour que ces derniers puissent être affichés à l’utilisateur. Dans notre projet Web, cela va se matérialiser par des classes qui vont contenir des fonctions qui seront appelées en fonction d’une URL. Ces dernières renverront un objet de type Symfony\Component\HttpFoundation\Response qui est l’abstraction d’une réponse HTTP dans Symfony.

Ecrivons un premier contrôleur que nous allons nommer DefaultController et que nous allons placer dans le répertoire src/Controller. Ce dernier, contiendra une fonction qui permettra d’afficher un message dans le navigateur.

<?php // src/Controller/DefaultController.php

namespace App\Controller;

use Symfony\Component\HttpFoundation\Response;

class DefaultController
{
    public function index(): Response
    {
        return new Response('Accueil Jobeet - Hello');
    }
}

Pour tester ce code, nous allons devoir indiquer au framework comment accéder à ce contrôleur. Pour cela nous allons éditer le fichier config/routes.yaml. Sans rentrer dans les détails (car c’est le sujet du prochain chapitre), ce fichier permet d’indiquer à Symfony l’URL qui déclenchera l’appel de la méthode index de notre contrôleur.

Pour le moment, décommentons simplement les 3 premières lignes :

# config/routes.yaml

index:
    path: /
    defaults: { _controller: 'App\Controller\DefaultController::index' }

# Depends on sensio/framework-extra-bundle, doctrine/annotations, and doctrine/cache
#   install with composer req sensio/framework-extra-bundle annot
#controllers:
#    resource: ../src/Controller/
#    type: annotation

Nous pouvons maintenant démarrer notre serveur Web via l’exécution de la commande make serve bin/console server:run dans un terminal et se rendre à l’adresse http://localhost:8000 avec son navigateur pour visualiser le résultat.

Pour pouvoir exécuter les différents traitements de notre application, le contrôleur doit pouvoir récupérer les données saisies par les utilisateurs. Dans un environnement Web, ces informations sont transmises par le navigateur au sein d’une requête HTTP.

Symfony utilise un composant HttpFoundation, dont l’objectif est de fournir une couche objet permettant de travailler avec le protocole HTTP. Nous avons, dans les exemples précédents, déjà utilisé un objet Response issue de ce composant. Nous allons maintenant utiliser un objet Symfony\Component\HttpFoundation\Request nous permettant d’accéder à toutes les informations d’une requête HTTP.

Pour ce faire, Symfony passe automatiquement en paramètre une instance d’un objet Request aux actions de nos contrôleurs si le paramètre est présent (Symfony détecte automatiquement la variable grâce à son typage).

Complétons notre code précédent pour récupérer un paramètre name et afficher le nom de la personne à saluer.

<?php // src/Controller/DefaultController.php

namespace App\Controller;

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

class DefaultController
{
    public function index(Request $request): Response
    {
        return new Response('Accueil Jobeet - Hello '.$request->get('name', 'World'));
    }
}

Dans cet exemple, nous utilisons la méthode Request::get pour récupérer un paramètre de la requête. Ce paramètre peut être transmis via l’URL ou au travers d’une requête de type POST. S’il n’est présent dans aucun des cas, nous avons choisi ici de retourner la valeur par défaut “World”. La valeur par défaut est facultative, si rien n’est spécifié et que le paramètre n’est pas présent NULL sera renvoyé.

Intéressons-nous maintenant à la couche vue. C’est cette dernière qui renvoie et met en forme les informations qui seront affichées à l’utilisateur. Le format de retour des données dépend de plusieurs paramètres dont le contexte d’utilisation. Dans le cas d’une navigation Web classique, l’application va retourner des données au format HTML, alors que dans le cas d’une API, les données pourraient être renvoyées au format JSON, XML ou n’importe quel autre format. Dans ce cas chapitre nous allons travailler exclusivement avec des pages HTML.

Comme nous l’avons déjà évoqué auparavant, Symfony 4 laisse libre le développeur de choisir les outils qu’il souhaite utiliser. Le framework ne prend aucun parti pris. De ce fait et contrairement aux versions précédentes, Symfony n’est plus fourni avec un moteur de templating par défaut.

Les moteurs de templating simplifient le travail d’écriture HTML en améliorant la lisibilité du code, son organisation et sa maintenance. Ces derniers sont généralement fournis avec un ensemble de fonctions de haut niveau permettant entre autres d’afficher des variables PHP, de créer des macros, d’utiliser des structures de boucles et de contrôles, etc.

Dans ce tutorial, nous avons fait le choix d’utiliser Twig. Twig a été créé par l’agence SensioLabs, les créateurs du framework Symfony. Ce moteur de templating était jusqu’à maintenant celui qui était fourni par défaut avec le framework. Sa simplicité et sa puissance en font le moteur le plus populaire PHP.

Avant de pouvoir commencer à nous servir de Twig dans notre projet, nous allons devoir installer les dépendances nécessaires. Pour fonctionner dans notre projet Symfony, plusieurs composants sont requis :

Twig: le moteur de template en lui-même. Ce dernier n’est pas couplé à Symfony et peut ainsi être réutilisé dans n’importe quel projet (avec ou sans framework).
TwigBridge: permet d’intégrer des nouvelles fonctionnalités au moteur de template qui sont liées aux différents composants du framework (formulaires, internationalisation, …).
TwigBundle: l’intégration du moteur Twig dans Symfony.

Comme pour toute dépendance PHP, nous allons utiliser Composer (et Symfony Flex) pour installer Twig. Nous allons ainsi demander l’installation de symfony/twig-bundle. Ce dernier ayant besoin des deux autres composants pour fonctionner, toutes les dépendances requises au fonctionnement de Twig dans notre projet seront mises en place.

$ composer require symfony/twig-bundle

Using version ^3.3 for symfony/twig-bundle
./composer.json has been updated
Loading composer repositories with package information
Updating dependencies (including require-dev)
Package operations: 3 installs, 0 updates, 0 removals
  - Installing twig/twig (v2.4.3): Loading from cache
  - Installing symfony/twig-bridge (v3.3.9): Downloading (100%)
  - Installing symfony/twig-bundle (v3.3.9): Downloading (100%)
Writing lock file
Generating autoload files
Symfony operations: 1 recipe
  - Configuring symfony/twig-bundle (3.3): From github.com/symfony/recipes:master
Executing script make cache-warmup [OK]
Executing script assets:install --symlink --relative public [OK]

Il est également possible d’utiliser une notation raccourcie pour installer Twig au travers de la commande composer require twig. Cela est possible grace à Symfony Flex qui permet de définir des noms alternatifs à des dépendances Composer. Dans le chapitre précédent, nous aurions pu utiliser la commande composer require orm pour installer Doctrine, cette dernière commande étant un alias de la commande composer require orm/pack.

Maintenant que Twig est installé, nous allons pouvoir créer et afficher notre premier template. Pour cela, nous allons commencer par injecter le moteur de templating dans notre contrôleur. Nous pourrons ensuite, utiliser ce dernier depuis nos actions pour récupérer le rendu de nos templates.

<?php // src/Controller/DefaultController.php

namespace App\Controller;

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Twig\Environment;

class DefaultController
{
    private $twig;

    public function __construct(Environment $twig)
    {
        $this->twig = $twig;
    }

    public function index(Request $request): Response
    {
        return new Response($this->twig->render('home.html.twig', [
            'name' => $request->get('name', 'World')
        ]));
    }
}

Notez qu’il n’est pas nécessaire de faire quoi que ce soit pour injecter notre objet Twig\Environment dans le constructeur de notre contrôleur. Le composant d’injection de dépendance de Symfony utilise l’autowiring pour injecter notre dépendance automatiquement.

Au moment de l’installation de Twig, Flex a préparé un dossier template à la racine de notre projet et a automatiquement configuré Twig pour que ce dernier aille chercher nos vues dans ce répertoire. Nous allons donc y créer un fichier home.html.twig.

# templates/home.html.twig
Hello {{ name }}

Pour afficher les variables que nous avons passé à notre template Twig, il faut utiliser la syntaxe {{ variable }}. Pour afficher le contenu de notre template, nous appelons la méthode render de Twig et passons le résultat à notre objet Response pour que le résultat puisse être retourné à l’utilisateur. Pour afficher le résultat de notre vue, cette syntaxe est un peu longue. Effectivement, nous allons devoir injecter dans chacun de nos contrôleurs une instance de Twig, récupérer le contenu d’un template et créer la réponse associée. Heureusement, Symfony met à notre disposition des outils pour simplifier notre travail et surtout mutualiser ce code au travers de la classe AbstractController. Cette dernière met à disposition une méthode render qui récupérera automatiquement une instance de Twig et créera notre objet Response en un appel de méthode.

Notre contrôleur peut ainsi être réécrit de la manière suivante :

<?php  // src/Controller/DefaultController.php

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

class DefaultController extends AbstractController
{
    public function index(Request $request): Response
    {
        return $this->render('home.html.twig', [
            'name' => $request->get('name', 'World')
        ]);
    }
}

Nous connaissons à présent le fonctionnement des contrôleurs et comment ces derniers communiquent avec la vue pour afficher nos données à l’utilisateur. Nous allons maintenant pouvoir afficher les premières pages de notre projet Jobeet. Commençons par la page de listing des offres d’emploi.

Créons pour cela un contrôleur dédié à la gestion des offres et ajouter une méthode pour récupérer les offres disponibles.

<?php // src/Controller/JobController.php

namespace App\Controller;

use App\Entity\Job;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

class JobController extends AbstractController
{
    public function index(EntityManagerInterface $em)
    {
        $jobs = $em->getRepository(Job::class)->findAll();

        return $this->render('job/index.html.twig', [
            'jobs' => $jobs,
        ]);
    }
}

Nous injectons ici un objet de type EntityManagerInterface directement dans notre méthode grace à l’autowiring (Symfony va détecter et injecter l’instance de l’objet qui implémente l’interface).

L’autowiring fonctionne avec une interface uniquement s’il n’existe qu’une seule classe qui implémente l’interface en question. Si deux classes implémentent la même interface, Symfony ne sera pas capable de savoir quelle instance injecter.

L’EntityManager est l’objet Doctrine qui permet de manipuler nos entités. Dans notre code, nous demandons une instance du repository (c’est-à-dire la classe qui permet de faire les requêtes en base de données) de notre entité Job pour ensuite récupérer la liste des emplois disponibles.

Doctrine fournit un ensemble de méthodes par défaut permettant de récupérer nos objets persistés. Signalons entre autres les fonctions find, findBy, findOneBy et findAll.

Ajoutons la vue qui va afficher nos résultats :

<!-- templates/job/index.html.twig -->

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <title>Jobeet - Liste des jobs</title>
        <link rel="icon" type="image/x-icon" href="{{ asset('favicon.ico') }}" />
    </head>
    <body>
        <ul>
            {% for job in jobs %}
                <li>{{ job.position }}</li>
            {% endfor %}
        </ul>
    </body>
</html>

Pour afficher la page, il sera nécessaire de modifier le fichier de configuration config/routes.yaml en modifiant le contrôleur devant être appelé.

L’exemple ci-dessus nous permet de découvrir de nouveaux éléments du langage de Twig. Tout d’abord, les instructions d’itérations qui nous permettent de parcourir des données de type array ou plus généralement des données iterable de PHP. Il s’agit d’une boucle for permettant de parcourir une liste d’éléments.

Nous constatons également qu’il est possible de passer à notre template Twig des instances d’objets et d’accéder aux propriétés de ces derniers avec l’opérateur . (cela fonctionnement également pour accéder à des tableaux).

Bien que la propriété position de notre objet Job soit privée, Twig parvient à afficher cette dernière. Twig possède un mécanisme qui va automatiquement trouver la méthode get associé à la propriété si cette dernière n’est pas accessible directement (si elle n’est pas public). Il est toutefois possible d’appeler directement la méthode getPosition() ou n’importe quelle autre méthode depuis notre template.

Pour le moment nous avons copié la totalité de la structure HTML dans notre fichier. Pour éviter d’avoir à dupliquer de nombreuses lignes de code dans tous nos templates, nous allons mutualiser le code qui va être commun à toutes les pages.

Si vous jetez un oeil aux fichiers qui ont été ajoutés dans le dossier templates par Flex lors de l’installation de Twig, vous noterez la présence d’un fichier base.html.twig.

<!-- templates/base.html.twig -->

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <title>{% block title %}Jobeet{% endblock %}</title>
        {% block stylesheets %}{% endblock %}
    </head>
    <body>
        {% block body %}{% endblock %}
        {% block javascripts %}{% endblock %}
    </body>
</html>

Ce fichier correspond à un template qui a vocation de définir la mise en page globale de notre application. Twig fonctionne sur le principe d’héritage. Cela signifie que vous allez pouvoir définir des templates qui contiendront des éléments qui pourront ensuite être surchargés dans d’autres templates. Pour cela, Twig utilise un système de blocs (block).

Utilisons le fichier templates/base.html.twig pour définir la mise en page de Jobeet. Pour commencer, nous allons étendre ce dernier dans notre template templates/job/index.html.twig et surcharger le bloc body pour y faire apparaître notre contenu :

<!-- templates/job/index.html.twig -->
{% extends "base.html" %}

{% block body %}
    <ul>
        {% for job in jobs %}
            <li>{{ job.position }}</li>
        {% endfor %}
    </ul>
{% endblock %}

Si vous rechargez la page, le résultat devrait être identique, mais nous avons beaucoup moins de code dans notre template, qui se concentre maintenant uniquement sur une tâche bien précise : afficher notre liste d’offres d’emploi.

Pour que nous interfaces soient un plus agréables à utiliser, nous allons y ajouter un peu de style avec du CSS. Pour gagner du temps, nous allons utiliser le framework boostrap au travers de ce thème https://startbootstrap.com/template-overviews/1-col-portfolio/ .

Une fois les fichiers téléchargés, nous allons placer les différents fichiers CSS et Javascript dans le dossier public (car ces derniers doivent être desservis par le serveur HTTP). Nous les organiserons dans un dossier vendor comme vous pouvez le voir dans le dépôt Github.

Commençons ensuite par modifier notre mise en page globale :

<!-- templates/base.html.twig -->

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
        <title>{% block title %}Jobeet{% endblock %}</title>
        <link rel="stylesheet" href="/vendor/bootstrap/css/bootstrap.min.css">
        <link rel="stylesheet" href="/vendor/1-col-portfolio.css">
        {% block stylesheets %}{% endblock %}
    </head>
    <body>
        <nav class="navbar navbar-expand-lg navbar-dark bg-dark fixed-top">
            <div class="container">
                <a class="navbar-brand" href="#">Jobeet</a>
                <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarResponsive" aria-controls="navbarResponsive" aria-expanded="false" aria-label="Toggle navigation">
                    <span class="navbar-toggler-icon"></span>
                </button>
            </div>
        </nav>

        <div class="container">
            {% block body %}{% endblock %}
        </div>

        <script src="/vendor/jquery/jquery-3.2.1.slim.min.js"></script>
        <script src="/vendor/popper/popper.min.js"></script>
        <script src="/vendor/bootstrap/js/bootstrap.min.js"></script>
        {% block javascripts %}{% endblock %}
    </body>
</html>

Nous conservons les blocs Twig stylesheets et javascripts même si nous ne les utiliserons pas pour le moment. C’est dernier seront utiles à l’avenir pour inclure des fichiers CSS ou Javascript spécifiques à certaines vues.

Pour finir, mettons en forme la présentation de nos offres d’emploi :

<!-- templates/job/index.html.twig -->
{% extends "base.html.twig" %}

{% block body %}
    <h1 class="my-4">Liste des offres</h1>

    {% for job in jobs %}
        <div class="row">
            <div class="col-md-7">
                <a href="#">
                    <img class="img-fluid rounded mb-3 mb-md-0" src="/images/{{ job.logo }}" alt="{{ job.company }}">
                </a>
            </div>
            <div class="col-md-5">
                <h3>{{ job.position }}</h3>
                <p>{{ job.description }}</p>
                <p>Posted on {{ job.createdAt|date("m/d/Y") }}</p>
                <a class="btn btn-primary" href="#">See more</a>
            </div>
        </div>

        <hr>
    {% endfor %}

    <ul class="pagination justify-content-center">
        <li class="page-item disabled">
            <a class="page-link" href="#" aria-label="Previous">
                <span aria-hidden="true">&laquo;</span>
                <span class="sr-only">Previous</span>
            </a>
        </li>
        <li class="page-item">
            <a class="page-link" href="#">1</a>
        </li>
        <li class="page-item disabled">
            <a class="page-link" href="#" aria-label="Next">
                <span aria-hidden="true">&raquo;</span>
                <span class="sr-only">Next</span>
            </a>
        </li>
    </ul>
{% endblock %}

Les images liées à notre jeu de données sont disponibles directement dans les sources de ce billet.

Et voilà le rendu final de notre application Jobeet :

Retrouvez tous les tutorials Jobeet disponibles depuis le billet d’introduction de la série. Le code source de cette application est également disponible sur Github. Vous trouverez une branche associée à l’état du projet après chaque chapitre.

Tutorial Jobeet pour Symfony 4 - Partie 3B: Les données initiales

Thu, 21 Sep 2017 00:00:00 +0200

Nous avons donc créé notre base et données avec les tables qui permettront de stocker les informations que notre application va manipuler. Avant de commencer l’implémentation des fonctionnalités évoquées dans les billets précédents, nous allons commencer par insérer un jeu de données initiales (également appelées fixtures) afin de ne pas démarrer avec un projet vide.

Pour créer nos données, nous allons utiliser un bundle fourni par les équipes de Doctrine et qui propose un moyen de charger des données en base. Nous avions jusqu’à maintenant utilisé uniquement des modules officiels de Symfony. Le bundle que nous allons utiliser (DoctrineFixturesBundle) est un module non officiel de Symfony. Or, par défaut, Symfony Flex ne permet de ne travailler qu’avec les bundles officiels de Symfony.

Il est néanmoins possible d’utiliser Flex avec ces bundles, mais il sera nécessaire de le spécifier explicitement dans la configuration. Pour cela, nous allons modifier la valeur du paramètre allow-contrib présent dans notre fichier composer.json au travers de la commande suivante :

$ composer config extra.symfony.allow-contrib true

Une fois effectué, il sera possible de télécharger la dépendance. Cette dernière n’étant utilisée qu’en développement, nous allons utiliser l’option --dev de Composer afin de l’installer comme tel :

$ composer require doctrine/doctrine-fixtures-bundle --dev

Using version ^2.4 for doctrine/doctrine-fixtures-bundle
./composer.json has been updated
Loading composer repositories with package information
Updating dependencies (including require-dev)
Package operations: 2 installs, 0 updates, 0 removals
  - Installing doctrine/data-fixtures (v1.2.2): Loading from cache
  - Installing doctrine/doctrine-fixtures-bundle (v2.4.0): Loading from cache
Writing lock file
Generating autoload files
Symfony operations: 1 recipe
  - Configuring doctrine/doctrine-fixtures-bundle (2.4): From github.com/symfony/recipes-contrib:master
Executing script make cache-warmup [OK]
Executing script assets:install --symlink --relative public [OK]

L’installation de cette dépendance va créer un dossier src/DataFixtures/ORM qui contiendra nos déclarations de fixtures. Mais avant d’écrire ces dernières, vous avez peut-être remarqué, que lorsque nous avons écrit nos entités, nous avons déclaré les propriétés de nos objets comment étant private. Nous allons donc devoir commencer par écrire les méthodes get qui permettront d’accéder à nos propriétés ainsi que les méthodes set qui permettront de modifier la valeur de nos propriétés.

L’activation du paramètre allow-contrib notamment permis la création du répertoire qui accueillera nos fixtures. Même si nous n’avions pas changé cette configuration, il aurait été possible d’installer le bundle, mais nous n’aurions pas profité des mécanismes de Flex qui permettent de créer une configuration du bundle par défaut.

Si vous avez eu la curiosité de regarder la liste des commandes proposées par le bundle Doctrine, vous aurez peut-être remarqué qu’il existe une commande doctrine:generate:entities dont le rôle est justement de remplir cette tâche.

Notre projet suit la convention PSR-4 décrivant la norme sur le chargement des fichiers PHP en fonction de leur arborescence (appelée autoloading). Malheureusement, le générateur de Doctrine n’est actuellement pas compatible avec cette norme (et ce n’est pas prévu à court ou moyen terme).

Mais cela n’est pas un problème étant donné que la plupart des outils de développement (tel que PHPStorm, Netbeans, Eclipse, Sublime Text, Atom, VSCode, …) ont une fonctionnalité (ou des plugins) permettant de générer du code automatiquement et notamment nos getters et setters.

Nous allons donc générer des méthodes get pour l’ensemble des propriétés de nos entités ainsi que les méthodes set associées, à l’exception des propriétés $id (car une clé primaire ne doit pouvoir être modifié), createdAt et updateAt (car nous avons déjà ajouté les méthodes permettant de modifier ces données).

Si vous souhaitez gagner du temps, vous pouvez accéder au code source correspondant à ce billet sur Github pour copier/coller les méthodes décrites ci-dessus.

Nous pouvons maintenant commencer à écrire nos fixtures, c’est-à-dire les classes qui vont s’occuper de la création notre jeu de données initiales. Nous allons commencer par créer des catégories d’offre d’emploi en créant une classe LoadCategoryData dans le dossier src/DataFixtures/ORM :

<?php //src/DataFixtures/ORM/LoadCategoryData.php

namespace App\DataFixtures\ORM;

use App\Entity\Category;
use Doctrine\Common\DataFixtures\AbstractFixture;
use Doctrine\Common\DataFixtures\OrderedFixtureInterface;
use Doctrine\Common\Persistence\ObjectManager;

class LoadCategoryData extends AbstractFixture implements OrderedFixtureInterface
{
    public function load(ObjectManager $manager)
    {
        $design = new Category();
        $design->setName('Design');
        $manager->persist($design);

        $programming = new Category();
        $programming->setName('Programming');
        $manager->persist($programming);

        $managing = new Category();
        $managing->setName('Manager');
        $manager->persist($managing);

        $administrator = new Category();
        $administrator->setName('Administrator');
        $manager->persist($administrator);

        $manager->flush();

        $this->addReference('category-design', $design);
        $this->addReference('category-programming', $programming);
        $this->addReference('category-managing', $managing);
        $this->addReference('category-administrator', $administrator);
    }

    public function getOrder()
    {
        return 1;
    }
}

Pour charger des données, notre classe doit étendre de AbstractFixture qui contient des fonctions de base de gestion de fixtures. Nous implémentons ensuite une interface OrderedFixtureInterface permettant de spécifier un ordre d’ insertion des nos fixtures (dans le cas présent, nous ne pouvons enregistrer une offre d’emploi si nous n’avons pas auparavant créé des catégories) au travers de la méthode getOrder().

Mise à jour du 04/03/2018 : Ce chapitre a été initialement rédigé sur la version 3.4 de Symfony. Depuis, la version installée de Doctrine a évolué. La classe Doctrine\Common\DataFixtures\AbstractFixture est maintenant remplacée par Doctrine\Bundle\FixturesBundle\Fixture et l’interface Doctrine\Common\DataFixtures\OrderedFixtureInterface par Doctrine\Common\DataFixtures\DependentFixtureInterface. Le fonctionnement pour charger des fixtures dépendantes les unes des autres a évolué, et il n’est plus nécessaire de définir l’ordre de chargement de ces dernières. L’interface DependentFixtureInterface définit une méthode retournant un tableau contenant les classes dont dépend le jeu de données courant. Vous n’avez donc plus à déterminer l’ordre de chargement des fixtures, Doctrine s’en charge dorénavant pour vous.

Le chargement des données se fait au sein d’une méthode load(ObjectManager $manager). Il s’agit de la méthode appelée lorsque les données doivent être insérées. Cette méthode prend en paramètre un objet de type ObjectManager qui est l’objet Doctrine qui permet de travailler avec la base de données.

Ce dernier permet d’appeler la méthode persist pour indiquer à Doctrine que nous souhaitons persister un objet en base. Pour que la donnée soit réellement écrite en base, on utilise un appel à la méthode flush. Dans le cas où l’on fait plusieurs appels à la méthode persist (comme c’est le cas ici) et qu’ensuite on flush, les insertions en bases sont réalisés au sein d’une transaction.

Une fois les données enregistrées, nous souhaitons les rendre accessibles depuis nos autres fixtures pour par exemple pouvoir affecter une catégorie à une offre d’emploi. Pour cela, nous allons définir explicitement les objets auxquels nous souhaitons accéder en appelant la méthode addReference et en associant une clé à notre donnée.

Nous pouvons ensuite passer à la fixture suivante :

<?php  //src/DataFixtures/ORM/LoadJobData.php

namespace App\DataFixtures\ORM;

use App\Entity\Job;
use Doctrine\Common\DataFixtures\AbstractFixture;
use Doctrine\Common\DataFixtures\OrderedFixtureInterface;
use Doctrine\Common\Persistence\ObjectManager;

class LoadJobData extends AbstractFixture implements OrderedFixtureInterface
{
    public function load(ObjectManager $manager)
    {
        $categoryProgramming = $this->getReference('category-programming');
        $categoryDesign = $this->getReference('category-design');

        $jobSensioLabs = new Job();
        $jobSensioLabs->setCategory($categoryProgramming);
        $jobSensioLabs->setType('full-time');
        $jobSensioLabs->setCompany('Sensio Labs');
        $jobSensioLabs->setLogo('sensio-labs.gif');
        $jobSensioLabs->setUrl('http://www.sensiolabs.com/');
        $jobSensioLabs->setPosition('Web Developer');
        $jobSensioLabs->setLocation('Paris, France');
        $jobSensioLabs->setDescription("You've already developed websites with symfony and you want to work with Open-Source technologies. You have a minimum of 3 years experience in web development with PHP or Java and you wish to participate to development of Web 2.0 sites using the best frameworks available.");
        $jobSensioLabs->setHowToApply('Send your resume to fabien.potencier [at] sensio.com');
        $jobSensioLabs->setIsPublic(true);
        $jobSensioLabs->setIsActivated(true);
        $jobSensioLabs->setToken('job_sensio_labs');
        $jobSensioLabs->setEmail('job@example.com');
        $jobSensioLabs->setExpiresAt(new \DateTime('2012-10-10'));
        $manager->persist($jobSensioLabs);

        $jobExtremeSensio = new Job();
        $jobExtremeSensio->setCategory($categoryDesign);
        $jobExtremeSensio->setType('part-time');
        $jobExtremeSensio->setCompany('Extreme Sensio');
        $jobExtremeSensio->setLogo('extreme-sensio.gif');
        $jobExtremeSensio->setUrl('http://www.extreme-sensio.com/');
        $jobExtremeSensio->setPosition('Web Designer');
        $jobExtremeSensio->setLocation('Paris, France');
        $jobExtremeSensio->setDescription('Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in.');
        $jobExtremeSensio->setHowToApply('Send your resume to fabien.potencier [at] sensio.com');
        $jobExtremeSensio->setIsPublic(true);
        $jobExtremeSensio->setIsActivated(true);
        $jobExtremeSensio->setToken('job_extreme_sensio');
        $jobExtremeSensio->setEmail('job@example.com');
        $jobExtremeSensio->setExpiresAt(new \DateTime('2012-10-10'));
        $manager->persist($jobExtremeSensio);

        $manager->flush();
    }

    public function getOrder()
    {
        return 2;
    }
}

Notez dans le code ci-dessus l’utilisation de la méthode getReference nous permettant de récupérer une donnée qui a été créée dans la fixture précédente.

Il ne reste maintenant plus qu’à charger nos données au travers de la commande :

$ bin/console doctrine:fixtures:load
Careful, database will be purged. Do you want to continue y/N ?y
  > purging database
  > loading [1] App\DataFixtures\ORM\LoadCategoryData
  > loading [2] App\DataFixtures\ORM\LoadJobData

Et voilà !

Retrouvez tous les tutorials Jobeet disponibles depuis le billet d’introduction de la série. Le code source de cette application est également disponible sur Github. Vous trouverez une branche associée à l’état du projet après chaque chapitre.

Tutorial Jobeet pour Symfony 4 - Partie 3A: Le modèle de données

Wed, 20 Sep 2017 00:00:00 +0200

Maintenant que l’aspect fonctionnel de notre projet a été défini, nous allons pouvoir créer le modèle de données associé à notre application, c’est-à-dire les classes qui permettront d’interagir avec la base de données. Nous allons pour cela avoir recours à un ORM. Ce sera également l’occasion de voir comment ajouter et configurer un module tier dans notre projet.

D’après les scénarios que nous avons précédemment écrits, voici le schéma correspondant aux relations entre entités que l’on peut en déduire :

En plus des informations, nous avons également ajouté un champ created_at et updated_at à certaines tables afin de conserver une trace des dernières modifications des données que nous allons traiter.

Pour stocker les informations de l’application, nous allons utiliser une base de données relationnelle. Symfony étant un framework orienté-objet, nous allons donc manipuler les informations sous la forme d’objet. Les informations de notre base de données doivent ainsi être mappées avec notre modèle objet et pour cela nous allons utiliser un ORM.

Symfony 4 laisse le choix au développeur sur les outils qu’il souhaite utiliser. Contrairement aux versions précédentes, Symfony est livré “vide” et n’impose aucun choix par défaut. Pour ce tutorial, nous allons faire le choix d’utiliser l’ORM Doctrine qui est l’ORM le plus répandu dans l’écosystème PHP. Mais il serait tout à fait possible d’utiliser une simple connexion PDO ou Doctrine DBAL, ou un autre ORM tel que Propel, Eloquent, Pomm ou n’importe quel autre outil.

Avant de créer et configurer les classes de notre modèle de données, nous allons commencer par télécharger Doctrine. Pour intégrer ce dernier dans notre projet Symfony, nous devrons récupérer deux dépendances. La première, doctrine/orm est l’ORM en tant que tel. La seconde dépendance consiste à intégrer l’ORM dans notre architecture Symfony. Symfony facilite le développement et la réutilisation de module que l’on peut partager entre plusieurs projets. Ces modules (des plugins en quelque sorte) sont appelés bundles dans l’écosystème du framework. Il convient donc de télécharger la dépendance doctrine/doctrine-bundle qui va intégrer l’ORM dans notre environnement Symfony.

Afin d’éviter au développeur d’avoir à installer deux dépendances distinctes, les équipes de développement fournissent un méta-paquet Composer permettant d’installer les deux éléments d’un coup. Pour intégrer Doctrine à notre projet, il nous suffit donc de récupérer la dépendance symfony/orm-pack.

$ composer require symfony/orm-pack

Using version ^1.0 for symfony/orm-pack
./composer.json has been updated
Loading composer repositories with package information
Updating dependencies (including require-dev)
Package operations: 20 installs, 0 updates, 0 removals
  - Installing ocramius/package-versions (1.1.3): Loading from cache
  - Installing zendframework/zend-eventmanager (3.2.0): Loading from cache
  - Installing zendframework/zend-code (3.3.0): Loading from cache
  - Installing ocramius/proxy-manager (2.1.1): Loading from cache
  - Installing doctrine/lexer (v1.0.1): Loading from cache
  - Installing doctrine/inflector (v1.2.0): Loading from cache
  - Installing doctrine/collections (v1.5.0): Loading from cache
  - Installing doctrine/cache (v1.7.1): Loading from cache
  - Installing doctrine/annotations (v1.5.0): Loading from cache
  - Installing doctrine/common (v2.8.1): Loading from cache
  - Installing doctrine/dbal (v2.6.3): Loading from cache
  - Installing doctrine/migrations (v1.6.1): Loading from cache
  - Installing symfony/doctrine-bridge (v4.0.0-RC1): Loading from cache
  - Installing doctrine/doctrine-cache-bundle (1.3.2): Loading from cache
  - Installing jdorn/sql-formatter (v1.2.17): Loading from cache
  - Installing doctrine/doctrine-bundle (1.8.0): Loading from cache
  - Installing doctrine/doctrine-migrations-bundle (v1.3.1): Loading from cache
  - Installing doctrine/instantiator (1.1.0): Loading from cache
  - Installing doctrine/orm (v2.5.12): Loading from cache
Writing lock file
Generating autoload files
Symfony operations: 4 recipes (9eb5d7e36646d167c1d8407c068032b9)
  - Configuring doctrine/annotations (1.0): From github.com/symfony/recipes:master
  - Configuring doctrine/doctrine-cache-bundle (1.3.2): From auto-generated recipe
  - Configuring doctrine/doctrine-bundle (1.6): From github.com/symfony/recipes:master
  - Configuring doctrine/doctrine-migrations-bundle (1.2): From github.com/symfony/recipes:master
ocramius/package-versions:  Generating version class...
ocramius/package-versions: ...done generating version class
Executing script cache:clear [OK]
Executing script assets:install --symlink --relative public [OK]


 Next: Configuration


  * Modify your DATABASE_URL config in .env

  * Configure the driver (mysql) and
    server_version</fg> (5.7) in config/packages/doctrine.yaml

Pour utiliser un bundle dans un projet, il est nécessaire d’activer ce dernier afin qu’il soit reconnu par le framework. Cette configuration s’effectue dans le fichier config/bundles.php. Ce fichier retourne un tableau associatif où la clé des éléments correspond au namespace complet du bundle à activer et dont la valeur est également un tableau associatif indiquant les environnements pour lesquels le bundle est actif (ou non).

<?php // config/bundles.php

return [
    Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
    Symfony\Bundle\WebServerBundle\WebServerBundle::class => ['dev' => true],
    Doctrine\Bundle\DoctrineCacheBundle\DoctrineCacheBundle::class => ['all' => true],
    Doctrine\Bundle\DoctrineBundle\DoctrineBundle::class => ['all' => true],
    Doctrine\Bundle\MigrationsBundle\DoctrineMigrationsBundle::class => ['all' => true],
];

En réalité, l’activation d’un bundle se fait rarement manuellement. Effectivement, Symfony Flex, que nous avons évoqué brièvement lors de la mise en place du projet se chargera de cette action. Il sera néanmoins parfois nécessaire de corriger la configuration par défaut en activant ou désactivant le bundle pour certains environnements.

Maintenant que Doctrine est installé et activé dans notre projet, nous allons pouvoir commencer à paramétrer notre application pour qu’elle puisse accéder à une base de données. Pour cela nous allons renseigner les paramètres nécessaires à l’établissement de la connexion. Cette dernière étant propre à l’environnement d’exécution de notre code, nous allons définir les paramètres dans le fichier .env. Ce dernier a d’ailleurs été prérempli avec une configuration de base par Flex :

# .env
# ...

###> doctrine/doctrine-bundle ###
# Format described at http://docs.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/configuration.html#connecting-using-a-url
# For an SQLite database, use: "sqlite:///%kernel.project_dir%/var/data.db"
# Configure your db driver and server_version in config/packages/doctrine.yaml
DATABASE_URL=mysql://db_user:db_password@127.0.0.1:3306/db_name
###< doctrine/doctrine-bundle ###

Vous avez certainement noté la présence des fichiers .env et .env.dist. Le fichier .env est le fichier qui contient réellement la configuration de notre application. Contenant des informations pouvant être très sensibles (comme par exemple des mots de passe), il n’est pas versionné.

C’est pour cela qu’un fichier .env.dist est présent. Ce dernier qui lui est versionné sert de modèle pour que les développeurs qui vont être ammenés à travailler sur le projet puisse connaître les informations à renseigner.

L’exemple de configuration qui a été inséré par Symfony Flex permet de se connecter à une base de données MySQL. Pour les besoins de ce tutorial, ainsi que pour éviter l’installation d’un serveur, nous allons utiliser SQLite qui est un système de base de données ne nécessitant pas une architecture client-serveur. Il sera nécessaire de vérifier que le driver SQLite de PHP (php-sqlite3) soit installé et activé. Nous allons ensuite modifier la variable d’environnement DATABASE_URL comme suit :

DATABASE_URL=sqlite:///%kernel.project_dir%/var/jobeet.db

Dans cette configuration, nous faisons référence à un paramètre kernel.project_dir définit par le framework (facilement reconnaissable car il est entouré du caractère %). Ce dernier fait référence à la racine du dossier du projet et permet ainsi de définir facilement l’endroit où l’on souhaite enregistrer nos données.

Mise à jour du 23/09/2017 : En parcourant le projet sur Github, j’ai trouvé l’issue concernant ce problème ainsi que sa résolution. Tout devrait rentrer dans l’ordre lors de la publication de la branche 3.4 du projet.

Le dossier var qui a été créé lors de la mise en place de Doctrine est, par convention, un dossier qui va contenir les fichiers écrits par notre application durant son fonctionnement (tel que des logs, des fichiers de cache, …). C’est donc tout naturellement dans ce dernier que nous allons stocker le fichier qui contiendra nos données SQLite.

Nous allons maintenant pouvoir démarrer l’écriture des classes qui vont modéliser nos données. Par défaut Doctrine est configuré pour travailler avec des annotations. Personnellement, je préfère séparer le code de sa configuration, c’est pour cela quand dans ce tutorial, nous utiliserons une configuration en YAML (il est également possible d’avoir une configuration en XML). Pour cela, nous allons éditer le fichier de configuration config/packages/doctrine.yaml pour y mettre le contenu ci-dessous :

# config/packages/doctrine.yaml
parameters:
    env(DATABASE_URL): 'sqlite:///%kernel.project_dir%/var/jobeet.db'

doctrine:
    dbal:
        driver: 'pdo_sqlite'
        url: '%env(resolve:DATABASE_URL)%'
    orm:
        auto_generate_proxy_classes: '%kernel.debug%'
        naming_strategy: doctrine.orm.naming_strategy.underscore
        auto_mapping: true
        mappings:
            App:
                is_bundle: false
                type: yml # annotation ou xml
                dir: '%kernel.project_dir%/config/doctrine/mapping' # configuration du mapping
                prefix: 'App\Entity'
                alias: App

On retrouve dans cette configuration la variable %kernel.project_dir% faisant référence au dossier racine de notre projet. Lorsqu’un paramètre de configuration est définit dans le framework. De la même façon, il est possible d’accéder à une variable d’environnement via la syntaxe %env(MA_VARIABLE)% (comme dans le fichier Doctrine pour accéder à la chaine de connexion à la base de données).

Notons également la présence du paramètre env(DATABASE_URL) permettant de définir le paramètre contenant la chaîne de connexion à notre base de données dans le cas où la variable d’environnement n’existerait pas.

Si vous analysez l’arborescence des fichiers, vous constaterez qu’il existe deux fichiers de configuration Doctrine : config/packages/doctrine.yaml et config/packages/prod/doctrine.yaml.

Le premier est un fichier de configuration commun à tous les environnements. Il est ensuite possible de définir une configuration spécifique pour un environnement (défini par la variable APP_ENV du fichier .env). Pour cela, il suffit de déposer le fichier de configuration dans un sous-dossier portant le nom de l’environnement pour lequel on souhaite surcharger la configuration et le framework le prendra automatiquement en compte.

Nous n’irons pas plus loin dans la configuration de Doctrine. Si vous après ce tutorial, vous souhaitez en savoir plus, je vous conseille de consulter la documentation officielle.

Créons maintenant les classes associées à notre modèle de données. Elles vont représenter les informations de la base de données sous la forme d’objets PHP (ces derniers sont appelés des entités) que l’on va pouvoir manipuler dans notre code. Lors de l’installation de Doctrine, Flex a ajouté un dossier src/Entity dans lequel nous allons créer nos classes.

Les entités sont de simples objets PHP dont les propriétés vont correspondre aux champs de notre base de données. Commençons par la table la plus simple, la table category :

<?php // src/Entity/Category.php

namespace App\Entity;

class Category
{
    private $id;
    private $name;
}

Maintenant passons à la table job. Un emploi étant lié à une catégorie, notre table contient une clé étrangère vers la catégorie associée. Dans notre entité, cette information va se modéliser sous la forme d’une propriété dont la valeur sera une instance de l’entité associée à la table catégorie (donc un objet Category).

<?php // src/Entity/Job.php

namespace App\Entity;

class Job
{
    private $id;
    private $category; // instance de Category
    private $type;
    private $company;
    private $logo;
    private $url;
    private $position;
    private $location;
    private $description;
    private $howToApply;
    private $token;
    private $isPublic;
    private $isActivated;
    private $email;
    private $expiresAt;
    private $createdAt;
    private $updatedAt;
}

La table qui va gérer les informations d’affiliation est un peu plus complexe. Dans notre modèle, une société peut-être être affiliée à plusieurs catégories et une catégorie peut avoir des affiliations de plusieurs sociétés. Avec une base de données relationnelle, cela se traduit par la création d’une table d’association pour gérer cette information (il s’agit de la table CategoryAffiliate).

Puisque nous avons dit qu’une table de notre base de données correspondait à un objet PHP, il devrait donc être nécessaire de créer deux nouveaux objets pour gérer cette relation. Mais en réalité cette table ne sert qu’à modéliser le fait qu’un objet Affialite est rattaché à plusieurs objets Category et vice-versa. Donc d’un point de vue programmation, un objet Affiliate devrait avoir une propriété $categories qui correspond à un tableau d’objet Affiliate et l’entité Category une propriété $affiliates correspondant un tableau d’objet Affiliate. Notre ORM est tout à fait capable de gérer cette problématique. Nous allons donc créer notre objet Affiliate avec une propriété $categories que nous ferons correspondre à un tableau d’objet Category. Doctrine gérera de manière automatique et transparente notre table d’association.

S’il avait été nécessaire de gérer des informations additionnelles, telles que par exemple la date de création de l’affiliation ou l’utilisateur ayant créé l’affiliation, il aurait été nécessaire de créer une entité supplémentaire et de gérer la relation manuellement.

<?php // src/Entity/Affiliate.php

namespace App\Entity;

use Doctrine\Common\Collections\ArrayCollection;

class Affiliate
{
    private $id;
    private $categories; // tableau d'objet Category
    private $url;
    private $email;
    private $token;
    private $isActive;
    private $createdAt;

    public function __construct()
    {
        $this->categories = new ArrayCollection();
    }
}

Lors de la mise en place d’une relation où l’on va gérer un tableau d’objet, il est nécessaire d’initialiser la propriété en question avec une collection vide. Pour Doctrine, cela passe par la création d’un objet ArrayCollection comme dans l’exemple précédent.

N’oublions pas de modifier notre objet Category pour y ajouter la propriété correspondant à nos objets Affialite. Une catégorie étant également associée à plusieurs emplois, nous allons en profiter pour y ajouter la propriété correspondante.

<?php // src/Entity/Category.php

namespace App\Entity;

use Doctrine\Common\Collections\ArrayCollection;

class Category
{
    private $id;
    private $name;
    private $jobs; // tableau d'objet Job
    private $affiliates; // tableau d'objet Affiliate

    public function __construct()
    {
        $this->jobs = new ArrayCollection();
        $this->affiliates = new ArrayCollection();
    }
}

Il est maintenant temps d’indiquer à Doctrine comment l’ORM va pouvoir faire le lien entre nos entités et les tables de la base de données. Pour cela, et comme nous l’avons spécifié précédemment, nous allons placer des fichiers de configuration dans le dossier config/doctrine/mapping. Tout comme pour l’écriture des classes, nous allons créer un fichier de configuration par entité en suivant la convention NomDeLaClasse.orm.yml.

Les fichiers de configuration vont permettre d’indiquer à quelle table correspondent une entité et les différentes caractéristiques de nos propriétés (colonne de rattachement, type de données, contraintes d’intégrité, ….).

Commençons par la configuration de notre entité Category :

# config/doctrine/mapping/Category.orm.yml
App\Entity\Category:
    type: entity

    # clé(s) primaire(s)
    id:
        id:
            type: integer
            generator:
                strategy: AUTO

    # colonne(s) de la table
    fields:
        name:
            type: string
            length: 63

    # relation de type un vers plusieurs
    oneToMany:
        jobs:
            targetEntity: Job
            mappedBy: category

    # relation de type plusieurs vers plusieurs
    manyToMany:
        affiliates:
            targetEntity: Affiliate
            inversedBy: categories

Comme vous pouvez le constater, les propriétés de correspondant à des relations sont dissociés du reste des propriétés. On distingue quatre types de relation, One-To-Many (relation de type un vers plusieurs), Many-To-One (plusieurs vers un), Many-To-Many (relation de plusieurs à plusieurs) et One-To-One.

Voici la configuration de l’entité Job :

# config/doctrine/mapping/Job.orm.yml
App\Entity\Job:
    type: entity

    id:
        id:
            type: integer
            generator:
                strategy: AUTO

    fields:
        type:
            type: string
            length: 255
            nullable: true

        company:
            type: string
            length: 255

        logo:
            type: string
            length: 255
            nullable: true

        url:
            type: string
            length: 255
            nullable: true

        position:
            type: string
            length: 255

        location:
            type: string
            length: 255

        description:
            type: text

        howToApply:
            type: text

        token:
            type: string
            length: 255
            unique: true

        isPublic:
            type: boolean
            default: false

        isActivated:
            type: boolean
            default: true

        email:
            type: string
            length: 255

        expiresAt:
            type: datetime

        createdAt:
            type: datetime

        updatedAt:
            type: datetime
            nullable: true

    manyToOne:
        category:
            targetEntity: Category
            inversedBy: jobs
            joinColumn:
                name: category_id
                referencedColumnName: id

Et pour finir le mapping correspondant à l’entité Affiliate :

# config/doctrine/mapping/Affiliate.orm.yml
App\Entity\Affiliate:
    type: entity

    id:
        id:
            type: integer
            generator:
                strategy: AUTO

    fields:
        url:
            type: string
            length: 255

        email:
            type: string
            length: 255
            unique: true

        token:
            type: string
            length: 255
            unique: true

        createdAt:
            type: datetime

    manyToMany:
        categories:
            targetEntity: Category
            mappedBy: affiliates

Lorsque nous allons enregistrer un emploi ou une affiliation, nous souhaiterions connaître la date de création et/ou de modification de la donnée écrite. Les entités correspondantes possèdent une propriété createdAt et/ou updatedAt. Plutôt que de devoir gérer manuellement cette information, nous allons déléguer ce travail à Doctrine.

En effet l’ORM possède un gestionnaire d’événement sur lequel nous allons nous brancher afin d’être notifié lors de l’enregistrement et la modification d’une entité. Nous allons donc ajouter cette configuration au mapping de nos entités afin d’indiquer la méthode de l’objet qui sera appelée lors de la propagation de l’événement.

Pour l’entité Job :

# config/doctrine/mapping/Job.orm.yml
App\Entity\Job:
    # ...

    lifecycleCallbacks:
        prePersist: [ setCreatedAtValue ] # appelé lors de la création de l'entité
        preUpdate:  [ setUpdatedAtValue ] # appelé lors de la modification de l'entité

Pour l’entité Affiliate :

# config/doctrine/mapping/Affiliate.orm.yml
App\Entity\Affiliate:
    # ...

    lifecycleCallbacks:
        prePersist: [ setCreatedAtValue ]

Il ne faudra pas oublier d’ajouter les méthodes correspondantes dans les classes associées. Ces dernières sont appelées avec un paramètre de type LifecycleEventArgs contenant un certain nombre d’informations sur le contexte d’exécution de l’ORM.

// src/Entity/Job.php
// ...

use Doctrine\Common\Persistence\Event\LifecycleEventArgs;

class Job
{
    // ...

    public function setCreatedAtValue(LifecycleEventArgs $event)
    {
        $this->createdAt = new DateTime();
    }

    public function setUpdatedAtValue(LifecycleEventArgs $event)
    {
        $this->updatedAt = new DateTime();
    }
}

Pour l’entité Affiliate, nous souhaitons connaître uniquement la date de création de la donnée.

// src/Entity/Affiliate.php
// ...

use Doctrine\Common\Persistence\Event\LifecycleEventArgs;

class Affiliate
{
    // ...

    public function setCreatedAtValue(LifecycleEventArgs $event)
    {
        $this->createdAt = new DateTime();
    }
}

Signalons l’existence d’un bundle StofDoctrineExtensionBundle contenant un ensemble d’extensions Doctrine pouvant être ajoutées à nos entités et possédant entre autres, une extension Timestampable. Cette dernière permet de gérer de manière automatique les dates de création et de modification d’une entité sans avoir à ajouter manuellement les propriétés correspondantes.

Maintenant que nous avons indiqué à notre projet comment se connecter à notre base de données, créé nos entités et indiqué la configuration nécessaire à la liaison entre nos objets et le contenu de notre base, nous allons pouvoir initialiser cette dernière. Doctrine va encore nous faciliter le travail dans cette tâche car l’ORM est distribué avec des commandes qui vont nous assister dans ce travail.

Dans un terminal, nous allons exécuter les commandes suivantes :

$ bin/console doctrine:database:create # pour créer la base de données
Created database var/jobeet.db for connection named default


$ bin/console doctrine:schema:create # pour créer la structure des tables
ATTENTION: This operation should not be executed in a production environment.

Creating database schema...
Database schema created successfully!

Vous pouvez constater que la base de données a été correctement initialisée en ouvrant le fichier contenant les données SQLite qui a été créé (var/jobeet.db) avec un outil tel que DB Browser for SQLite.

Voilà qui conclut notre section d’introduction au modèle de données. Nous avons maintenant une base de données (presque) prête à être utilisée et qui n’attend plus que nos données.

Retrouvez tous les tutorials Jobeet disponibles depuis le billet d’introduction de la série. Le code source de cette application est également disponible sur Github. Vous trouverez une branche associée à l’état du projet après chaque chapitre.

Tutorial Jobeet pour Symfony 4 - Partie 2: Le projet

Tue, 19 Sep 2017 00:00:00 +0200

Nous avons précédemment créé la structure de notre projet Symfony et préparé notre environnement de développement. Nous allons très prochainement pouvoir commencer à écrire nos premières lignes de code. Mais avant cela, attardons-nous un peu sur les exigences de notre projet.

Ce billet est principalement d’une recopie des exigences fonctionnelles du tutorial initial. Je vous recommande vivement de lire ce dernier car des explications sur les nouvelles pratiques liées à Symfony 4 y sont décrites.

Jobeet est un logiciel open-source de recherche d’emploi qui ne fait qu’une seule chose, mais le fait bien. Il est facile d’utilisation, à adapter, à faire évoluer, et à intégrer à votre site internet. Il est multi langues dès le départ, et bien sûr il utilise les dernières technologies du web 2.0 pour améliorer l’expérience utilisateur. Il fournit également des feeds et une API pour interagir avec lui en programmant.

Le site web Jobeet a quatre types d’utilisateurs :

L’administrateur : il est propriétaire du site et il a le pouvoir magique
L’utilisateur : il visite le site pour chercher un emploi
L’annonceur : il soumet une offre d’emploi
L’affilié : il re-édite certains emplois sur son site

Nous allons maintenant découper le projet en scénarios d’utilisation. L’application est séparée en deux interfaces : le frontend (où les utilisateurs interagissent avec le site), et le backend (où les administrateurs gèrent le site).

Symfony recommande maintenant et générera dorénavant des applications orientées bundle-less. Si vous débutez avec Symfony, un bundle peut être considéré comme un “plugin”. Ils permettent de regrouper du code qui est regroupé par fonctionnalité et redistribuable dans n’importe quel projet Symfony.

Nous allons maintenant lister les exigences fonctionnelles de notre application. Ces dernières seront numérotés et débuteront par un F pour les aspects frontend et par un B pour les aspects backend.

F1: En tant qu’utilisateur, je vois les dernières offres actives sur la page d’accueil

Quand un utilisateur vient sur le site Jobeet, il voit une liste des emplois actifs. Les emplois sont classés par catégorie, puis par date de publication (emplois plus récents en premier). Pour chaque emploi, seul le lieu, la position, et la société sont affichés.

Pour chaque catégorie, la liste ne montre que les 10 premiers emplois et un lien permet de lister tous les emplois pour une catégorie donnée (scénario F2).

Sur la page d’accueil , l’utilisateur peut affiner la liste des travaux (scénario F3), ou par la soumission d’un nouvel emploi (scénario F5).

F2: En tant qu’utilisateur, je peux lister les emplois d’une catégorie

Quand un utilisateur clique sur un nom de catégorie ou sur le lien “more jobs” sur la page d’accueil, il voit tous les emplois pour cette catégorie triée par date.

La liste est paginée avec 20 emplois par page.

F3: En tant qu’utilisateur, je peux affiner les offres d’une catégorie

L’utilisateur peut saisir quelques mots-clés pour affiner sa recherche. Les mots-clés peuvent être des mots trouvés dans l’emplacement, la position, la catégorie, ou les champs de l’entreprise.

F4: En tant qu’utilisateur, je peux visualiser le détail d’une offre

L’utilisateur peut sélectionner un emploi dans la liste pour afficher des informations plus détaillées.

F5: En tant qu’utilisateur, je peux soumettre une offre d’emploi

Un utilisateur peut soumettre un emploi (il n’est pas nécessaire de devoir créer un compte). Un emploi est composé de plusieurs informations.

Le processus est simple, avec seulement deux étapes : d’abord, l’utilisateur remplit dans le formulaire toutes les informations nécessaires pour décrire l’emploi, puis il valide les informations en visualisant la page finale de l’emploi.

Même si l’utilisateur n’a pas de compte, un emploi peut être modifié ultérieurement, grâce à une URL spécifique (protégé par un jeton donné à l’utilisateur lorsque l’emploi est créé).

Chaque poste de travail est en ligne pendant 30 jours (ce qui est configurable par l’administrateur - voir Histoire B2). Un utilisateur peut revenir réactiver ou prolonger la validité de l’annonce pour un supplément de 30 jours, mais seulement lorsque le travail expire dans moins de 5 jours.

F6: En tant qu’utilisateur, je peux affilier ma société

Un utilisateur doit demander à devenir un affilié et être autorisés à utiliser l’API Jobeet. Pour postuler, il doit donner des informations.

Le compte d’ un affilié doit être activé par l’administrateur (scénario B3). Une fois activé, l’affilié reçoit un jeton pour une utilisation avec l’API par email.

Lors de l’application, l’affilié peut également choisir d’obtenir des emplois auprès d’un sous-ensemble des catégories disponibles.

F7: En tant qu’utilisateur, je peux exporter la liste des emplois actifs

Un affilié peut récupérer la liste des emplois en cours en appelant l’API avec le jeton de sa filiale. La liste peut être retournée en XML, JSON ou YAML.

La liste contient les informations publiques disponibles pour un emploi.

L’affilié peut également limiter le nombre d’emplois qui seront retournés, et affiner sa requête en spécifiant une catégorie.

B1: En tant qu’administrateur, je peux configurer le site

L’administrateur peut modifier les catégories disponibles sur le site.

B2: En tant qu’administrateur, je peux administrer les offres d’emploi

Un administrateur peut modifier et supprimer tous les emplois affichés.

B3: En tant qu’administrateur, je peux gérer les affiliés

L’administrateur peut créer ou modifier des affiliés. Il est responsable de l’activation d’un affilié et peut également les désactiver.

Lorsque l’administrateur active une nouvelle filiale, le système crée un jeton unique à utiliser par la filiale.

Retrouvez tous les tutorials Jobeet disponibles depuis le billet d’introduction de la série. Le code source de cette application est également disponible sur Github. Vous trouverez une branche associée à l’état du projet après chaque chapitre.

Tutorial Jobeet pour Symfony 4 - Partie 1: Démarrage du projet

Wed, 13 Sep 2017 00:00:00 +0200

Est-il encore nécessaire de présenter Symfony qui est l’un des frameworks PHP les plus populaires ? Dans cette première partie, nous allons créer la structure de notre application et voir comment s’organise un projet Symfony.

Démarrons tout d’abord avec les prérequis nécessaires à la mise en place de notre projet. Concernant la version de PHP que vous allez devoir utiliser, un PHP 7.1.3 sera au minimum nécessaire. Dans cette série de billets, nous partirons du principe que vous avez installé les extensions permettant d’accéder à une base de données telle que MySQL ou PostgreSQL (via l’extension PDO et les drivers associés). Le module XML de PHP (alias php-xml) est également requis. Pour finir, nous supposerons également, que Composer, l’outil de gestion des dépendances PHP est installé sur votre machine.

Jusqu’à la version 4 de Symfony, la création d’un nouveau projet se faisait au travers d’un outil d’installation spécifique nommé Symfony installer. Ce dernier outil est maintenant remplacé par Composer qui possède une commande create-project permettant de créer un nouveau projet PHP. Cette commande est ainsi indépendante du framework. Les équipes de Symfony ont souhaité standardiser la manière de démarrer un projet PHP sans devoir y ajouter des outils spécifiques. La création de notre projet Jobeet se fera ainsi au travers de la commande : composer create-project symfony/skeleton jobeet 4.0.0-RC1.

Composer va alors créer un dossier pour notre projet en se basant sur le modèle de projet Symfony et télécharger les dépendances associées. Dans sa nouvelle version, le framework fournit dorénavant un composant nommé Flex, une surcouche à Composer et qui permet entre autres de configurer automatiquement les dépendances que vous installez dans votre application.

Analysons la structure de notre projet vide :

jobeet
├── .env
├── .env.dist
├── composer.json
├── composer.lock
├── config
│   ├── bundles.php
│   ├── packages
│   │   ├── dev
│   │   │   └── routing.yaml
│   │   ├── framework.yaml
│   │   ├── routing.yaml
│   │   └── test
│   │       └── framework.yaml
│   ├── routes.yaml
│   └── services.yaml
├── public
│   └── index.php
├── src
│   ├── Controller
│   └── Kernel.php
└── vendor

Contrairement aux versions précédentes, le framework a changé l’arborescence de ces fichiers afin de se rapprocher d’une arborescence de fichiers que l’on pourrait retrouver sur des systèmes Unix. On retrouve ainsi les éléments ci-dessous :

config

Dossier contenant les fichiers de configuration de notre projet

public

Le répertoire contenant les fichiers désservis par les serveurs HTTP

src

Accueillera les fichiers sources PHP contenant toute la logique de notre projet

vendor

Le dossier utilisé par Composer et contenant les dépendances (décrites dans le fichier composer.json) nécessaires au fonctionnement de notre projet

.env

Fichier contenant la configuration de l'environnement d'exécution de notre code

Makefile

Décrit les tâches pouvant être exécutées par le framework

Même si nous n'avons encore aucune ligne de code ni même de configuration (en réalité Flex s'en est chargé pour nous), nous pouvons démarrer notre application Symfony. Il est possible de démarrer un serveur HTTP au travers de la commande `make serve` (si vous ne connaissez pas l'outil Make, je vous recommande vivement de vous renseigner sur ce dernier).

Même sans configuration particulière, nous pouvons démarrer notre application grâce au serveur Web embarqué dans PHP au travers de la commande php -S localhost:8000 -t public/.

Par défaut, le framework utilise le serveur Web embarqué avec PHP (ce qui peut être suffisant pour des besoins de développement). Symfony fournit également un bundle symfony/web-server-bundle (nous reviendrons plus tard sur la notion de bundle) permettant d’apporter une meilleure expérience développeur pour manipuler ce dernier.

Une fois le serveur démarré, nous pouvons nous connecter sur notre projet en ouvrant un navigateur et en tapant l’URL http://localhost:8000. Bien entendu, comme nous n’avons encore rien fait, une page d’erreur sera affichée.

Attardons-nous maintenant le contenu du fichier .env. Si vous regardez le contenu de ce dernier, vous constaterez qu’il contient un certain nombre de paramètres :

# This file is a "template" of which env vars needs to be defined in your configuration or in a .env file
# Set variables here that may be different on each deployment target of the app, e.g. development, staging, production.
# https://symfony.com/doc/current/best_practices/configuration.html#infrastructure-related-configuration

###> symfony/framework-bundle ###
APP_ENV=dev
APP_DEBUG=1
APP_SECRET=f78d2a48cbd00d92acf418a47a0a5c3e
###< symfony/framework-bundle ###

Notons tout d’abord les commentaires ###> symfony/framework-bundle ### et ###< symfony/framework-bundle ### présent dans le fichier. Ces derniers servent de balise de début et de fin à Flex pour ajouter et supprimer automatiquement la configuration de nos dépendances lors de leurs ajouts ou suppressions dans notre projet.

Viennent ensuite les différentes variables d’environnement d’exécution de notre application :

La variable APP_ENV permet de définir l’environnement courant d’exécution du projet. Généralement 3 environnements sont utilisés : prod (l’environnement où interagissent les utilisateurs finaux), dev (l’environnement utilisé pendant les développements) et test (l’environnement utilisé pour tester automatiquement notre projet).
La variable APP_DEBUG de Symfony fournit un ensemble d’outils permettant de faciliter la résolution des bugs pouvant survenir lors du développement. Par exemple, c’est cette dernière qui génère l’affichage de la pile d’appel des fonctions du framework lorsqu’une erreur se produit (comme lorsque nous avons tenté d’accéder à l’application via le navigateur).
Un des principaux avantages d’avoir recours à un framework est d’utiliser un ensemble de composants réutilisables, régulièrement mis à jour et utilisant des bonnes pratiques de développement. Cela permet au framework de guider le développeur et de minimiser les erreurs pouvant faire apparaître des failles de sécurité. La variable APP_SECRET est ainsi utilisée par certains composants en tant que clé secrète pour générer des jetons de sécurité (comme par exemple lors de la mise en place de formulaire avec les jetons CSRF).

C’est sur ce point que nous allons conclure ce premier chapitre. À ce stade, nous avons créé notre projet Symfony et rapidement fait le tour de l’organisation des fichiers de notre application. Notre environnement est maintenant prêt et nous allons prochainement pouvoir commencer à développer.

La section suivante dévoilera les fonctionnalités de notre application et détaillera les besoins fonctionnels et techniques à satisfaire.

Retrouvez tous les tutorials Jobeet disponibles depuis le billet d’introduction de la série. Le code source de cette application est également disponible sur Github. Vous trouverez une branche associée à l’état du projet après chaque chapitre.

Tutorial Jobeet pour Symfony 4 - Introduction

Tue, 12 Sep 2017 00:00:00 +0200

J’ai récemment eu l’occasion de relire des articles concernant Jobeet, un tutorial pour concevoir une application de type “job board” écrit par l’équipe du framework Symfony (la première version à l’époque) afin de se familiariser avec l’outil. Ce dernier avait par la suite été adapté pour Symfony 2.8 par Dragos HOLBAN et traduit tout récemment en français par Jonathan THUAU.

Lors de l’écriture de ce billet, la version 4 du framework est en cours de finalisation et devrait sortir dans les prochains mois (courant novembre). Cette nouvelle version apporte de nombreuses améliorations et va modifier la manière dont nous travaillons avec l’outil, notamment grâce à un nouveau composant nommé Flex.

Quand j’ai relu le tutorial, j’ai été déçu que ce dernier ne soit pas disponible pour les dernières versions disponibles du framework. J’ai donc décidé de démarrer une série de billets consacrés à l’adaption du tutorial pour Symfony 4.

Vous trouverez donc ici, au fur et à mesure de l’écriture des différents billets, les liens vers les nouveaux articles dont le sommaire se trouve ci-dessous :

Par manque de temps, et du fait de nombreux changements personnels et professionnels je n'ai pas eu l'occasion de terminer la série d'articles que j'avais initialement prévus.

Tutorial Jobeet pour Symfony 4 - Partie 7: Jouons avec la page catégorie
Tutorial Jobeet pour Symfony 4 - Partie 8: Les tests unitaires
Tutorial Jobeet pour Symfony 4 - Partie 9: Les tests fonctionnels
Tutorial Jobeet pour Symfony 4 - Partie 10: Les formulaires
Tutorial Jobeet pour Symfony 4 - Partie 11: Tester les formulaires
Tutorial Jobeet pour Symfony 4 - Partie 12: L’interface d’administration
Tutorial Jobeet pour Symfony 4 - Partie 13: La sécurité
Tutorial Jobeet pour Symfony 4 - Partie 14: Le flux de données
Tutorial Jobeet pour Symfony 4 - Partie 15: Fournir une API
Tutorial Jobeet pour Symfony 4 - Partie 16: Envoyer des emails
Tutorial Jobeet pour Symfony 4 - Partie 17: La recherche
Tutorial Jobeet pour Symfony 4 - Partie 18: L’AJAX
Tutorial Jobeet pour Symfony 4 - Partie 19: L’internationalization
Tutorial Jobeet pour Symfony 4 - Partie 20: Les bundles
Tutorial Jobeet pour Symfony 4 - Partie 21: Le cache
Tutorial Jobeet pour Symfony 4 - Partie 22: Le déploiement
Tutorial Jobeet pour Symfony 4 - Partie 23: Un autre regard sur Symfony

Depuis la création de ce tutorial, le framework n’a cessé d’évoluer et de nouveaux composants ont fait leurs apparitions. Je tenterai d’ajouter de nouveaux articles afin d’y introduire ces derniers :

Tutorial Jobeet pour Symfony 4 - Partie 24: Les assets avec Webpack Encore
Tutorial Jobeet pour Symfony 4 - Partie 25: Gerer un workflow
Tutorial Jobeet pour Symfony 4 - Partie 26: Plus loin avec l’injection de dépendance
Tutorial Jobeet pour Symfony 4 - Annexe 1: Environnement Vagrant
Tutorial Jobeet pour Symfony 4 - Annexe 2: Environnement Docker
Tutorial Jobeet pour Symfony 4 - Annexe 3: Symfony Flex

N’hésitez pas à me contacter via Twitter ou par mail pour me faire part de vos observations et remarques.

Les dépendances locales récursives dans un projet Composer

Thu, 13 Jul 2017 00:00:00 +0200

Dans un précédent billet, j’ai parlé de comment il était possible de gérer les dépendances PHP dans un projet monorepo avec Composer. Si vous avez testé la méthode décrite, vous avez peut-être rencontré des difficultés lorsqu’une dépendance de votre projet a elle-même une dépendance dans le même dépôt.

Par exemple, si je développe un site e-commerce avec un composant Cart pour la gestion du panier et que je souhaite implémenter ce dernier dans une application Symfony. Je peux alors être tenté de créer un CartBundle qui sera intégré dans l’application principale.

On aurait l’arborescence ci-dessous :

applications/
    frontend/
        composer.json # Dépendance vers CartBundle
components/
    Cart/
        composer.json # Autonome
    CartBundle/
        composer.json # Dépendance vers Cart

Le fonctionnement de Composer dans ce cas est clairement expliqué dans la documentation: les repositories ne sont pas chargés récursivement. En effet, Composer estime que ce paramètre de configuration est exceptionnel et doit être utilisé de manière temporaire.

Pour pallier ce problème, vous devrez spécifier explicitement les sous dépendances dans la configuration votre application principale.

applications/
    frontend/
        composer.json # Dépendance vers CartBundle et explicite vers Cart
components/
    Cart/
        composer.json # Autonome
    CartBundle/
        composer.json # Dépendance vers Cart

Heureusement, pour éviter d’avoir à spécifier tous les répertoires contenant nos dépendances, Composer autorise l’utlisation de “wildcard” tel que * et ?. Ainsi le fichier composer.json de notre application pourrait ressembler à :

{
  "repositories": [
    {
      "type": "path",
      "url": "../../components/*"
    }
  ],
  "require": {
      "myapp/Cart": "*",
      "myapp/CartBundle": "*"
  }
}

Gérer les dépendances Composer dans un projet monorepo

Mon, 26 Jun 2017 00:00:00 +0200

Mettre en place un monorepo (aka. un dépôt monolithique), c’est mettre en place un dépôt global regroupant toutes les applications et divers composants de votre projet. Dans ce billet, nous n’allons pas voir les avantages ou inconvénients de ce type d’organisation, certains ont fait des billets sur les avantages, les inconvénients ou des conférences à ce sujet. Nous allons plutôt voir comment mettre en place une gestion de dépendances avec Composer.

Prenons par exemple, un projet ayant l’arborescence suivante :

applications/
    api/
        composer.json
    backend/
        composer.json
    frontend/
        composer.json
    worker/
        composer.json
component/
    package1/
        composer.json
    package2/
        composer.json

La problématique va être de pouvoir gérer simplement dans les différentes applications, les dépendances présentes dans le répertoire component. La première idée qui peut venir à l’esprit pourrait être de configurer l’autoloading de composer afin de faire référence aux différents composants déclarer dans le dépôt.

{
  "autoload": {
    "psr-4": {
      "Vendor\\Package1\\": "../../component/package1/src",
      "Vendor\\Package2\\": "../../component/package2/src"
    }
  }
}

Bien que cette méthode fonctionne, elle n’est cependant pas optimale car avec cette dernière, le fichier composer.json du composant n’est pas utilisé. Or, ce dernier contient diverses informations sur la bibliothèque. Dans le cas présent, nous avons dû redéfinir la configuration de l’autoloading de la bibliothèque.

Composer définit le concept de “repositories”. Globalement, un repository correspond à une source de composant. Par défaut et sans que le développeur n’ait besoin de faire quoi que ce soit, Composer définit Packagist comme source principale.

Il est bien évidemment possible d’ajouter de nouvelles sources de repository et Composer supporte différentes sources de données telle que github, gitlab, vcs et bien d’autres encore. Mais celle qui va nous intéresser est path. Cette dernière va permettre de définir une source de composants correspondant à un chemin de notre machine.

Il est donc possible d’utiliser un composant en modifiant le composer.json d’une application de la manière suivante :

{
  "repositories": [
    {
      "type": "path",
      "url": "../../component/package1"
    },
    {
      "type": "path",
      "url": "../../component/package2"
    }
  ],
  "require": {
      "vendor/package1": "*",
      "vendor/package2": "*"
  }
}

Au travers de cette modification, il n’est plus nécessaire de redéfinir la configuration spécifiée dans le composant, puisque Composer va charger ce dernier comme n’importe quelle autre dépendance de votre projet.

En faisant des recherches sur la meilleure manière de gérer les dépendances au sein d’un monorepo, j’ai également découvert un projet expérimental se présentant sous la forme d’un plugin Composer dédié à la gestion de ce type d’organisation. Je n’ai pas expérimenté ce dernier et bien qu’il ne semble plus maintenu, il peut être intéressant d’y jeter un oeil. Son auteur a publié un article expliquant l’objectif et le fonctionnement du projet.

Des "metapackages" Composer prochainement dans Symfony

Fri, 23 Jun 2017 00:00:00 +0200

C’est en faisant un tour sur les dépôts Github de Symfony que j’ai découvert la création récente (à partir de la fin du mois de mai) de “metapackage” Composer. Pour rappel, un métapaquet est une dépendance vide dont l’objectif est de déclencher l’installation d’autres dépendances.

Après une recherche rapide sur le blog ainsi que sur la documentation, je n’ai pas trouvé la trace d’une communication officielle concernant ces nouvelles dépendances. On peut donc lister à ce jour 4 métapaquets :

annotations-pack pour la gestion des annotations
profiler-pack permettant d’avoir le Web profiler Symfony
orm-pack pour l’installation des modules Doctrine ORM
debug-pack pour obtenir les composants nécessaires au debug, à la mise en place de tests et à la gestion de logs

La création de ces dépendances sera néanmoins pratique pour installer rapidement des packs de fonctionnalités avec le nouveau mode de distribution de Symfony 4.

Edit: Suite à mon article, Kevin Dunglas a fait un tweet pour expliquer rapidement comment ces métapaquets étaient utilisés.

C'est utilisé par Flex en fait. C'est grâce à ces paquets que tu peux faire composer req api orm templating par exemple.
— Kévin Dunglas (@dunglas) 23 juin 2017

Choisissez bien les dépendances de vos projets

Thu, 11 May 2017 00:00:00 +0200

La semaine dernière, une équipe à côté de laquelle je me trouvais faisait le point sur un projet. Il y avait alors un échange concernant l’utilisation d’une dépendance qui n’était pas compatible PHP 7, la version de PHP choisie pour démarrer ce dernier. Il en a résulté que l’équipe a été obligé de développer le projet en 5.6, ce qui m’a fortement fait réagir. Bien qu’il puisse y avoir des raisons qui peuvent conduire à prendre une telle décision, mais dans le cas présent, je trouve cela aberrant.

Pourquoi ? Tout d’abord parce que la dépendance en question devait être mise en place pour intégrer Elasticsearch dans le projet. Il existe une multitude de composants permettant cela et le client officiel est très bien fait. Je peux comprendre que dans le cas présent, l’équipe souhaitait un bundle Symfony qui ait quelques fonctionnalités supplémentaires, mais vu l’envergure du projet, n’était-il possible de simplement utiliser la librairie de base ? Mais si le bundle était si important pour l’équipe, n’était-il pas possible de faire une PR pour apporter la compatibilité sur la branche 7 de PHP et d’en faire profiter la communauté ?

Mais au-delà de tout ça, essayons de se poser les bonnes questions. En effet, PHP 5.6 est en fin de vie. Cette version n’a plus de support actif et reçoit donc maintenant que des correctifs de sécurité. PHP 7.0 est sortie il y a maintenant plus de deux ans et PHP 7.1 il y a un an. Si un composant PHP n’est pas compatible PHP 7, nous sommes alors en droit de se demander si ce dernier est encore actif et/ou maintenu ? Est-ce vraiment judicieux de démarrer un nouveau projet dans ces conditions ? Est-ce un pari gagnant dans le long terme ?

Pour ma part, la réponse est clairement non, surtout pour un projet qui est amené à être créé maintenant. Il est primordial de bien choisir les dépendances que l’on ajoute à un projet et d’avoir également une vision à long terme dans les phases de conceptions et réflexions autour du projet.

Si l’on devait conclure ce billet, et si vous n’aviez qu’une seule phrase à retenir, ça serait :

Ne démarrez pas vos projets sur des versions de PHP déjà obsolètes et utilisez des dépendances connues et maintenues !

Votre équipe vous en remerciera, car comme je le tweetais cette semaine :

N'oubliez pas que lorsque vous prenez des raccourcis dans vos devs, vous finissez irrémédiablement par en payer les conséquences tôt ou tard
— Jérémy DECOOL (@jdecool) 4 mai 2017

Utiliser Chrome Headless avec Behat

Tue, 09 May 2017 00:00:00 +0200

Il sera désormais possible à partir de la version 59 de Chrome (la version bêta au moment où j’écris ces lignes) en mode “headless”, c’est-à-dire sans interface graphique. Ce mode de fonctionnement est intéressant pour les tests par exemple, car il ne sera plus obligatoire de “piloter” Chrome via son interface graphique.

Cette nouvelle fonctionnalité a provoqué un large engouement de la part de la communauté Web. À tel point que le mainteneur de PhantomJS, un navigateur headless, également basé sur Webkit a annoncé la fin du projet. Donc si comme moi, vous utilisiez ce dernier dans vos scénarios Behat, il va être nécessaire de changer de solution.

Pour cela, rien de plus simple. Voici par exemple la configuration Behat pour Selenium que j’utilisais avec PhantomJS.

# behat.yml
default:
    extensions:
        # ...
        Behat\MinkExtension:
            base_url: http://project.dev
            sessions:
                default:
                    selenium2:
                        wd_host: http://localhost:4444/wd/hub

Pour que Selenium puisse interagir avec Chrome, nous allons devoir utiliser un driver additionnel ChromeDriver. Une fois ce dernier installé, nous devrons ajouter quelques lignes de configuration supplémentaires.

# behat.yml
default:
    extensions:
        # ...
        Behat\MinkExtension:
            base_url: http://project.dev
            sessions:
                default:
                    selenium2:
                        browser: chrome
                        wd_host: http://localhost:4444/wd/hub
                        capabilities:
                            chrome:
                                switches:
                                    - "--headless"
                                    - "--disable-gpu"

Parmi les changements, nous spécifions à Selenium d’utiliser Chrome en tant que navigateur au travers de l’argument browser. Puis nous spécifions des capabilities, c’est-à-dire des options permettant de personnaliser et de configurer la session Chrome qui sera ouverte. Nous indiquons ainsi vouloir une navigateur headless. Le paramètre --disable-gpu est pour le moment obligatoire.

Et voilà, en ayant tout juste rajouté 5 lignes de configuration, vous avez remplacé l’utilisation de PhantomJS par Google Chrome en mode “headless”.

Le fichier de configuration est disponible sur Gist

Utiliser l'extension PHP Tideways dans Travis CI

Sun, 23 Apr 2017 00:00:00 +0200

Tideways est une extension PHP permettant d’ajouter le support du profiling. Le profiling est une activité qui consiste à collecter un certain nombre d’informations sur l’exécution d’un code (PHP dans notre cas). Tideways est en réalité la continuité de l’extension XHProf précédemment développé par Facebook, mais aujourd’hui abandonné au profit de HHVM. Le principal avantage de cette dernière est que l’extension est compatible avec les versions 7 de PHP.

L’extension PHP n’étant pas “standard”, il n’est pas possible de l’activer directement dans Travis CI. Il sera donc nécessaire de télécharger, compiler et activer l’extension en amont de la phase de build. Pour cela, nous allons rajouter les commandes suivantes dans notre fichier .travis.yml :

# ...
before_scripts:
  # ...
  - wget -Otideways-php.tar.gz https://github.com/tideways/php-profiler-extension/archive/v4.1.1.tar.gz
  - tar xvfz tideways-php.tar.gz -C /tmp
  - cd /tmp/php-profiler-extension-4.1.1
  - phpize
  - ./configure
  - make
  # ...

Les commandes ci-dessus téléchargent les sources de l’extension, les décompressent dans le répertoire /tmp et les compilent. Une fois ces étapes, il ne reste plus qu’à activer l’extension auprès de PHP. Cela peut être fait en ajoutant une ligne dans le fichier de configuration PHP :

echo "extension=/tmp/php-profiler-extension-4.1.1/modules/tideways.so" >> ~/.phpenv/versions/$(phpenv version-name)/etc/php.ini

Sinon il est possible si vous utilisez PHP via la ligne de commande d’activer l’extension à la volée via l’option -d :

php -dextension=/tmp/php-profiler-extension-4.1.1/modules/tideways.so vendor/bin/phpunit

Ce que je retiens du SymfonyLive 2017

Sun, 02 Apr 2017 00:00:00 +0200

J’ai eu l’occasion cette année de participer au SymfonyLive organisé par SensioLabs à Paris. Tout comme ma dernière participation en 2015, cette année encore, j’ai pu assister à des conférences de qualité autour de PHP et du framework Symfony.

Présent au #Symfony_Live pour la team @novaway avec @FloChntrl pic.twitter.com/9DUFBCQ3R3
— Jérémy DECOOL (@jdecool) 30 mars 2017

Mais plus important que les différentes conférences et présentations qui sont données tout au long de ces 2 jours, c’est l’occasion de rencontrer et de discuter avec la communauté. Cela permet de voir les tendances émergentes ainsi que celles qui sont considérées comme acquis auprès de tous. Cela va même au-delà de l’écosystème Symfony.

Ce que je retiens donc de cet événement :

Parmi les “buzzwords” actuels, difficile d’éviter de parler des microservices. Les acteurs majeurs du Web ont largement migré vers ce type d’architecture. Mais les microservices ont du mal à se frayer un chemin dans l’écosystème PHP. Bien sur ce n’est pas une réponse universelle, mais des discussions que je peux avoir avec de nombreux développeurs, l’idée qui en ressort c’est que le concept est intéressant mais qu’il ne s’adapte jamais réellement au projet sur lequel on travaille. Il faut également que ce type d’architecture à un impact organisationnel sur les équipes qui la mette en place.
S’il y a bien un autre concept dont on entend de plus en plus parler dans l’écosystème PHP, c’est le Domain Driven Design (DDD). Cette technique de conception n’a rien de nouveau puisqu’elle existe depuis de nombreuses années. Mais PHP s’étant grandement professionnalisé, les projets que nous sommes amenés à développer sont de plus en plus complexes. Dans ce contexte, le DDD nous permet de développer des applications proches du métier, avec une forte expressivité de ce dernier. Sur ce point, j’ai un peu l’impression de voir ce qui s’est passé avec la notion de tests logiciels il y a quelques années. J’ai nettement l’impression que les développeurs, même s’ils ne vont pas migrer complètement vers ce type de conception, ces derniers vont tenter d’appliquer les concepts les plus importants dans leurs projets.
Le dernier point que je retiens est la démocratisation des Platform as a service (PaaS). Les problèmes de déploiement et de gestion des ressources serveurs (aka. la “scalabilité”) est une des préoccupations principale de nos applications. Les services de PaaS permettent de se concentrer sur le développement de notre projet en proposant de gérer la partie hébergement. De ce fait, les PaaS sont de plus en plus utilisés et les offres disponibles pour ce type de service sont de plus en plus nombreuses.

Si vous êtes intéressé par l’événement, sachez qu’il existe un dépôt Github contenant la description des présentations avec les slides associées. Les présentations ayant été filmé, les vidéos arriveront prochainement.

L'extension PHP qui permet de modifier des constantes

Mon, 06 Mar 2017 00:00:00 +0100

Comme quoi après des années de pratique d’un langage, ce dernier peut toujours nous surprendre. Une constante est par définition constante, sa valeur ne change pas. Lorsque l’on en définit une en PHP via la fonction define, il est donc impossible de la changer ou de la modifier.

Je viens de découvrir une extension PECL qui change tout ça ! Elle s’appelle runkit. Cette dernière fournit un ensemble de fonction qui vous permettra entre autres, d’ajouter, modifier et supprimer des constantes de votre code (le genre de chose qu’on ne devrait jamais avoir à faire).

Sachez en tout cas que si vous avez besoin de faire une telle chose, c’est que vous avez un problème de conception. Et si malgré tout vous souhaitez quand même tester l’extension, cette dernière ne semble plus maintenue et ne sera certainement pas compatible PHP7.

Assurer la compatibilité des tests PHPUnit 6 avec les versions antérieures

Mon, 20 Feb 2017 00:00:00 +0100

PHPUnit version 6 a été tagguée le 3 février 2017. Cette nouvelle version n’est dorénavant compatible qu’avec PHP 7+. Un changement majeur introduit par cette nouvelle branche est le renommage de la classe PHPUnit_Framework_TestCase en PHPUnit\Framework\TestCase. Si comme moi, il vous arrive de tester une même branche de code avec plusieurs versions de PHP, cela pourra être un problème.

J’ai eu le cas cette semaine, où, sur une base de code toujours maintenu (mais plus pour très longtemps) sur les versions PHP 5.3+. Sans rentrer dans les détails techniques, pour simplifier l’exécution des tests, nous récupérons une version de PHPUnit avec la définition Composer suivante : phpunit/phpunit:@stable. Ce n’est certes pas l’idéal ni une excellente pratique, mais cela fonctionne bien.

Lors du passage des tests avec PHP 7, nous récupérons ainsi la version 6 de PHPUnit qui provoque alors une erreur puisque la classe PHPUnit_Framework_TestCase qui était utilisée jusque-là n’est plus disponible.

En attendant la fin du support des versions de PHP 5.x pour le code concerné, la solution de contournement utilisé a été de définir un alias de classe dans le “bootstrap” de PHPUnit de la manière suivante :

// Keep PHPUnit < 6.0 BC
if (!class_exists('PHPUnit_Framework_TestCase') && class_exists('PHPUnit\Framework\TestCase')) {
    class_alias('PHPUnit\Framework\TestCase', 'PHPUnit_Framework_TestCase');
}

De ce fait, si la classe PHPUnit_Framework_TestCase n’existe pas, c’est que nous sommes certainement en train d’éxecuter la nouvelle version de PHPUnit. Et nous définissons donc un alias vers la classe PHPUnit\Framework\TestCase si cette dernière existe.

Accèdez facilement à vos constantes Twig avec TwigConstantAccessorBundle

Wed, 28 Sep 2016 00:00:00 +0200

C’est sans surprise que la plupart des développeurs Symfony utilisent Twig comme moteur de templating, il s’agit en effet du moteur fourni par défaut avec le framework. Il arrive souvent que l’on soit amené à accéder à des constantes dans nos vues. Pour cela, Twig nous propose différentes solutions.

La solution la plus évidente est certainement l’utilisation de la fonction constant ainsi que du test correspondant.

{{ constant('Namespace\\Classname::CONSTANT_NAME') }}
{{ constant('RSS', date) }}

{% if post.status is constant('Post::PUBLISHED') %} ... {% endif %}
{% if post.status is constant('PUBLISHED', post) %} ... {% endif %}

La configuration de Symfony permet également de définir un certain nombre de variables, services et constantes pouvant être accessible directement depuis vos templates Twig.

# app/config/config.yml
twig:
    # ...
    globals:
        my_service:      "@my_service"
        my_constant_foo: foo
        my_constant_bar: bar

Une méthode moins répandue est de passer par une extension Twig. Mais attention, cette possibilité est maintenant dépréciée et sera supprimée dans la version 2 de Twig.

class Project_Twig_Extension extends Twig_Extension implements Twig_Extension_GlobalsInterface
{
    public function getGlobals()
    {
        return array(
            'text' => new Text(),
        );
    }

    // ...
}

Pour réduire tout ce travail de configuration, j’ai créé un bundle visant à simplifier l’accès aux constantes de classe dans les templates Twig. Une fois installé, il suffit de définir les classes dont vous souhaitez exposer les constantes et le bundle s’occupe entièrement de la gestion de la configuration.

# app/config/config.yml
twig_constant_accessor:
    classes:
        - AppBundle\Model\Foo
        - { class: 'AppBundle\Model\Bar' }
        - { class: 'AppBundle\Model\FooBar', alias: 'FooBarAlias' }

Avec cette configuration, vous aurez directement accès aux constantes dans vos vues Twig :

{{ Foo.MY_CONSTANT }} {# access AppBundle\Model\Foo::MY_CONSTANT #}
{{ Bar.KEY }}  {# access AppBundle\Model\Bar::KEY #}

{% if 'value' == FooBarAlias.MY_CONSTANT %}Test is OK{% endif %}
{# FooBarAlias is an alias for AppBundle\Model\FooBar #}

Pourquoi les développeurs n'aiment pas Behat ?

Mon, 11 Apr 2016 00:00:00 +0200

Depuis sa mise à disposition, Behat est un outil plutôt controversé de la part des développeurs. Il y a ceux qui l’aiment et ne peuvent s’en passer (c’est mon cas) et ceux qui bien au contraire le détestent. Pourtant Behat est un outil formidable qui permet de faire le lien entre les tests d’acceptations et l’application que l’on est en train de concevoir. Tout cela de manière automatisée. Dit autrement, il va permettre de valider qu’une demande exprimée en langage métier donne le résultat attendu. Pourtant, je rencontre très souvent des développeurs qui ne supportent pas cet outil. J’ai tenté de comprendre pourquoi.

Avant de tenter de répondre à cette question, je pense qu’il est nécessaire de comprendre comment fonctionne l’outil. Comme évoqué précédemment, un des plus grands intérêts de Behat est que l’on va exprimer le test en langue naturelle (peu importe la langue utilisée). Le format d’écriture ressemble beaucoup à l’expression d’une user-story utilisé dans la méthode SCRUM.

Voici par exemple un exemple de scénario :

# language: fr
Fonctionnalité: Avoir un compte bancaire
    Afin d'offrir aux utilisateurs la possibilité d'avoir un compte bancaire
    Etant donné que je suis inscrit
    Je dois être capable d'ajouter ou de retirer de l'argent sur mon compte

    Scénario:
        Etant donné que je suis un utilisateur connecté
        Et que j'ai un compte bancaire
        Et que le solde de mon compte est de "10" euros
        Quand j'ajoute "5" euros sur mon compte
        Alors mon solde doit être de "15" euros

Lorsque l’on écrit nos tests Behat, nous commençons par décrire la fonctionnalité de manière générale puis on décrit un ensemble de cas d’utilisation. Ces derniers vont alors définir un contexte d’exécution, une série d’événements et terminer par le résultat attendu.

Les scénarios Behat peuvent ensuite être exécutés dans un ou plusieurs environnements. Par exemple, dans le cas d’un site Web, il est tout à fait envisageable d’exécuter le scénario dans différents navigateurs pour valider que le fonctionnement de l’application est correct aussi bien sur Firefox que Chrome ou Internet Explorer.

Une fois les scénarios écrits, il faudra alors que le développeur fasse le lien entre les étapes des différents scénarios et les actions qui en résultent dans l’application. Heureusement, Behat nous aide dans cette tâche en prégénérant le squelette du code correspondant.

Avec ce que nous venons dire, ne trouvez-vous pas que Behat est un outil extrêmement intéressant ? Il nous permet :

De valider notre compréhension du besoin client
De valider que notre application réponde correctement à ce dernier
De documenter notre application et fournit un esemble de spécifications

Alors pourquoi un développeur peut ne pas aimer Behat ?

Comme l’explique son auteur. Avec Behat, un développeur ne teste pas son application, mais il s’assure que son application réponde aux besoins métiers de son client. Beaucoup d’applications répondent aux attentes des développeurs, mais peuvent ne pas couvrir les besoins métiers.

Toujours d’après son auteur, Behat permet en réalité d’apprendre au développeur comment fonctionne le métier du client.

Je pense que si beaucoup de développeurs n’aiment pas Behat c’est à cause de ce dernier point. Ecrire des bons scénarios Behat est un travail délicat. Il faut exprimer le métier du client et non pas le fonctionnement de l’application.

Un développeur aura facilement tendance à écrire ce genre de scénario :

# language: en
Scenario: Showing delivery cost for a product on the basket page
  Given there is a product:
    | name  | White Marker |
    | price | £5           |
  And I am on the "/catalogue" page
  When I click "Buy" in the "White Marker" product block
  And I go to the "/basket" page
  Then I should see a list with 1 product
  And the overall price should be shown as £9

Alors que le scénario exprimé du point de vue du client devrait ressembler à :

# language: en
Scenario: Getting the delivery cost for a single product under £10
  Given a product named "White Marker" and priced £5 was added to the catalogue
  When I add the "White Marker" product from the catalogue to the picked up basket
  Then the overall basket price should be £9

Mais adopter ce point de vue n’est pas évident pour un développeur, qui a souvent plus une vision technique que fonctionnelle de l’application. Cela demande donc un véritable effort de réflexion, en plus de devoir écrire le code correspondant aux différents scénarios.

Je reste donc persuader que si de nombreux développeurs n’aiment pas Behat, c’est essentiellement à cause de leur culture technique et qu’il est difficile pour eux de faire un volte-face pour se mettre à la place du client.

Il se peut aussi que comme j’avais tenté de l’expliquer dans un précédent billet, que les développeurs vont tenter de se lancer directement dans l’écrire de leurs scénarios Behat, sans prendre le temps de comprendre les outils qu’ils utilisent et la manière de le configurer correctement.

Ressources :

Mon environnement PhpStorm

Wed, 17 Feb 2016 00:00:00 +0100

Comme de nombreux développeurs PHP, j’utilise au quotidien l’excellent IDE développé par Jetbrains, j’ai nommé PhpStorm. Au-delà des nombreuses fonctionnalités fournies nativement par l’IDE, il est possible d’ajouter des modules complémentaires au travers des nombreux plugins disponibles.

Dans ce billet, je vais présenter les principaux modules que j’utilise.

##PHP Annotation

PHP Annotation est un module qui comme son nom l’indique très bien permet de gérer les annotations dans l’IDE. C’est notamment grâce à cette extension qu’il sera possible de naviguer dans les annotations, d’obtenir de l’autocomplétion lors de l’implémentation de ces dernières, etc.

##Symfony

Je développe essentiellement en utilisant le framework Symfony. Cette extension permet ainsi d’obtenir un support complet du framework dans l’IDE.

##Atoum

Il m’est impossible de développer sans écrire de tests (et j’espère que vous aussi). Pour écrire mes tests unitaires, j’utilise Atoum aussi personnellement que professionnellement. Ce plugin créé tout récemment permet de faciliter la navigation dans mes tests, mais également de lancer simplement ces derniers directement dans l’IDE.

##PHP composer.json

Il est aujourd’hui devenu impossible de travailler en PHP sans utiliser Composer, le gestionnaire de dépendance pour le langage. Cette extension, permet d’avoir l’autocomplétion lors de l’édition du fichier de définition des dépendances, mais permet également de consulter les versions des dépendances installées.

##PHP Inspection EA

PHP Inspection EA est l’un des derniers modules que j’ai découvert, mais il commence à devenir indispensable. Effectivement, ce dernier permet d’effectuer des analyses de codes statiques en complément de celles effectuées nativement par l’IDE. Extrêmement pratique pour améliorer son code !

Mon retour du DDD Day 2016 à Lyon

Mon, 08 Feb 2016 00:00:00 +0100

Le DDD-Day est une journée de conférence visant à sensibiliser les développeurs PHP au DDD (le Domain-Driven Design), démystifier son utilisation et les patterns qui y sont rattachés. J’ai ainsi eu l’occasion d’assister à la première édition de cette journée qui s’est déroulée le 30 janvier 2016 à Lyon.

Le #dddday c'est maintenant ! pic.twitter.com/VJOesVWTFi
— Jérémy DECOOL (@jdecool) 30 Janvier 2016

Avant de faire un retour rapide sur la journée, je tenais à remercier une nouvelle fois tous ceux grâce à qui cette journée n’aurait pu avoir lieu : l’AFUP, KnpLabs, l’atelier des médias, Amabla et Vanoix.

La journée de conférence a été filmée et sera prochainement disponible sur la chaîne Youtube de OpenTalk.

Pourquoi le DDD ne devrait rien changer à votre vie ?

Alexandre Balmes - Slides - Vidéo

Cette journée commence par une présentation du Domain-Driven Design, pourquoi et quand l’utiliser. Derrière cette présentation Alexandre nous explique les bases du DDD et tente de nous montrer que malgré quelques termes “barbares”, il n’y a rien de sorcier derrière cet acronyme. Ce n’est au fond que du bon sens et peut s’intégrer dans tout environnement projet, surtout avec les outils qui sont à notre disposition en PHP aujourd’hui.

Get Off My Domain !

Matthieu NAPOLI - Slides - Vidéo

Après l’introduction faite par Alexandre, Matthieu rentre un peu plus dans les détails techniques d’une application DDD. Il va alors nous présenter les design-patterns essentiels qui doivent être utilisés dans nos applications. C’était l’occasion de revoir les notions de : Entity, Value Object, Domain Service, Repository (au sens premier du pattern), Aggregate et de Domain Event.

Ne laissez pas les formulaires Symfony influencer votre modèle

Jérémy BARTHE - Slides - Vidéo

En France, nous sommes très nombreux à utiliser le framework PHP Symfony. D’ailleurs l’ensemble des personnes présentes développaient leurs applications en utilisant ce dernier. Partant de ce constat, Jérémy nous a fait une présentation technique sur l’utilisation des formulaires en Symfony. L’objectif de sa présentation était de nous permettre de garder nos formulaires les plus simples possible tout en gardant en tête les fondamentaux du DDD : l’utilisation des Value Object et de l’Ubiquitous Language.

Soyez spécifiques

Kévin GOMEZ - Slides - Vidéo

Kévin nous a fait une présentation sur l’expression des règles métiers dans nos applications et la manière de les rendre réutilisables. Pour réussir cette tâche, il nous présente le pattern Specification et une implémentation de ce pattern qu’il a écrit dans sa librairie RulerZ. Avec RulerZ, il est alors possible via un DSL (Domain Specific Language), une règle métier qui peut ensuite être passée de manière complètement transparente à un QueryBuilder de Doctrine ou une Query ElasticSearch.

CQRS : Quand les Représentations ne sont pas symétriques

Guillaume ROSSIGNOL - Vidéo

CQRS (Command Query Responsibility Segregation) est un pattern applicatif qui repose sur un principe simple : la séparation, au sein d’une application, des composants de traitement de lecture et d’écriture. Cette présentation nous a fait un retour d’expérience sur la “migration” d’une application legacy vers une architecture orientée DDD et CQRS.

J’ai trouvé ce retour d’expérience intéressant vis-à-vis du choix que l’équipe a effectué. Effectivement, l’essentiel des problèmes rencontrés se trouvant côté “front”, l’équipe a fait le choix de garder l’application legacy en fonctionnement (correspondant à la logique d’écriture) et de démarrer une nouvelle application qui ne sert qu’à présenter les informations enregistrées par le back-office (la partie legacy).

Tour de table

Pascal MARTIN

Pour terminer cette journée, nous avons eu le droit à une table ronde animée par Pascal qui a permis à chaque membre de répondre aux questions restées en suspens lors des présentations.

Ce fut également un moment d’échange pour permettre aux organisateurs d’avoir le ressenti de chacun sur cette première édition du DDD Day.

Encore une fois merci à toutes les personnes qui ont rendu cette journée possible : les membres de l’organisation, les conférenciers ainsi qu’à tous les participants à cette journée. Ce fut une journée riche en information, mais cela fait également plaisir de revoir les personnes qui font bouger l’écosystème PHP à Lyon.

Merci à tous !

Très bonne journée au #dddday ! Merci à tous @pockystar @vanoix @AFUP_lyon pour l'orga et à tous les speakers.
— Jérémy DECOOL (@jdecool) 30 Janvier 2016

Le problème n+1

Thu, 17 Dec 2015 00:00:00 +0100

Si vous êtes développeur et que vous travaillez régulièrement avec une base de données, vous avez très certainement déjà été confronté à des problèmes de performance liés à des relations de type parent/enfant. L’anti-pattern que l’on retrouve le plus fréquemment consiste à exécuter une requête pour obtenir la relation parente puis à récupérer les enfants un à un. C’est un cas qui se produit souvent lorsque l’on travaille avec des ORM. On parle alors du problème N+1 (“N+1 problem” en anglais).

Prenons un exemple concret : une base de données permettant de répertorier des auteurs de livres ainsi que les livres écrits par ces derniers. Nous souhaitons récupérer la liste des auteurs avec les livres qu’ils ont écrits. Le code permettant d’afficher ce résultat pourrait ressembler à cela :

// ...
$authors = $pdo->query('SELECT * FROM author')->fetch();
foreach ($author as $authors) {
    $books = $pdo->query('SELECT * FROM book WHERE author_id = '.$author['id']);
    // ...
}

Avec le code ci-dessous, on constate que les performances de l’application vont se dégrader de manière exponentielle au fur et à mesure que l’on va renseigner des auteurs et ajouter des livres. Dans le cas présent, l’on récupère 10 auteurs, 11 requêtes vont être exécutées pour récupérer l’ensemble des informations voulues (1 pour récupérer les 10 auteurs, puis 10 pour récupérer les livres de chacun des auteurs).

Cela vous paraît aberrant ? Vous ne pensez ne jamais écrire un code comme cela ? Prenons le même exemple en utilisant un ORM (Doctrine par exemple).

class Author
{
    /**
     * @Id
     * @Column(name="id", type="int")
     */
    private $id;

    /**
     * @OneToMany(targetEntity="Book", mappedBy="author")
     */
    private $books;

    // ...
}

class Book
{
    /**
     * @Id
     * @Column(name="id", type="int")
     */
    private $id;

    /**
     * @ManyToOne(targetEntity="Author")
     */
    private $author;

    // ...
}


$authors = $entityManager->getRepository('Author')->findAll();
foreach ($author as $authors) {
    $books = $author->getBooks();
    // ...
}

Vous pensez peut-être que cette solution est plus performante. Pourtant le code ci-dessus se comporte exactement de la même façon que le précédent. Par défaut Doctrine (comme de nombreux ORM) génère des classes Proxy afin de ne récupérer les relations enfant que lorsqu’elles sont demandées. Dans ce cas, Doctrine va exécuter une requête à chaque appel de la méthode getBooks pour récupérer les informations correspondantes.

La solution pour éviter cela est bien évidemment d’utiliser des jointures SQL afin de récupérer les informations des auteurs avec les livres qu’ils ont écrit dans la même requête. La modification du premier exemple conduirait à ce code :

// ...
$authors = $pdo->query('SELECT * FROM author JOIN book ON author.id = book.author_id')->fetch();

Les ORM permettent également d’écrire des requêtes en utilisant les jointures afin de récupérer l’ensemble des données voulu. On peut également configurer le mapping des relations pour effectuer une récupération agressive des données (mais cela n’est pas forcément recommandé car il se peut que la récupération des données de la relation ne soit pas toujours utile) :

// utilisation du QueryBuilder de Doctrine pour récupérer l'ensemble des données en une requête
$authors = $entityManager->createQueryBuilder()
    ->select(['a', 'b'])
    ->from('Author', 'a')
    ->join('Book', 'b')
    ->getQuery()
    ->getResult()
;

Trait ou héritage, il faut choisir

Sat, 28 Nov 2015 00:00:00 +0100

C’est avec la version 5.4.0 que les Traits sont apparus en PHP. Il s’agit d’un mécanisme de réutilisation de code, introduit dans le but de réduire certaines limites de l’héritage simple. Je constate que de plus en plus de développeurs se mettent à utiliser les Traits à tel point que ces certains n’utilise même plus l’héritage et préfère avoir recours à ce mécanisme. Que se soit avant de faire un héritage ou avant d’utiliser un trait, il convient de se poser la question de quand utiliser l’un ou l’autre ?

Revenons rapidement sur ce qu’est un héritage. L’héritage permet d’établir une relation (de type parent/enfant) entre des classes. Lorsque l’on étend une classe, la classe fille hérite alors de toutes les méthodes publiques et protégées de la classe parente. Il est également possible que la classe fille redéfinisse certaines de ces méthodes pour les adapter à ces spécificités.

Les traits quand à eux ont comme seul objectif de partager du code entre classes sans structuration hiérarchique. Il n’y a donc ici pas de relation entre les classes qui utilisent les traits. Il partage seulement un comportement.

Il faut bien avoir cette distinction lorsque vous écrivez du code. Voici par exemple, du code que j’ai pu voir récemment sur un projet :

trait RepositoryTrait
{
    public function find($id)
    { /* ... */ }

    // ...
}

class UserRepository
{
    use RepositoryTrait;

    // ...
}

class GroupRepository
{
    use RepositoryTrait;

    // ...
}

Il faut faire attention à l’utilisation des traits car ces derniers peuvent facilement casser les aspects classiques de la programmation objet. Dans ce bout de code, les classes UserRepository et GroupRepository n’implémente pas d’interface commune, elle utilise un trait. De ce fait, le principe de programmation SOLID peut facilement être rompu.

Dans ce cas-là, un héritage semble plus adapté :

abstract class Repository
{
    public function find($id)
    { /* ... */ }

    // ...
}

class UserRepository extends Repository
{
    use RepositoryTrait;

    // ...
}

class GroupRepository extends Repository
{
    use RepositoryTrait;

    // ...
}

De plus en utilisant un héritage, il est plus facile de faire du typage explicite. Il est alors possible de vérifier que la classe fournit en paramètre est bien de type Repository, ce qui n’est pas possible avec un trait. De plus il sera plus facile de respecter le principe de substitution de Liskov.

Il est préférable d’utiliser les traits pour partager du code avec des classes qui n’ont pas de lien entre elles. Prenons comme exemple :

trait TextFormater
{
    public function sanitize($text)
    {
        return strip_tags($text);
    }
}

class Mailer
{
    use TextFormater;

    public function send($subject, $text)
    {
        mail('user@mail.com', $this->sanitize($subject), $this->sanitize($text));
    }
}

class ConsoleWriter
{
    use TextFormater;

    public function write($text)
    {
        echo $this->sanitize($text), PHP_EOL;
    }
}

Dans l’exemple précédent, la classe Mailer a pour but d’envoyer un mail à un utilisateur et la classe Writer de générer un affichage à l’écran. Ces deux classes n’ont aucun rapport et pourtant elles ont toutes les deux besoins de traiter du texte fourni en paramètre. L’héritage n’a ici pas sa place et il convient donc de partager le code via l’utilisation d’un trait.

Un autre exemple concret de l’utilisation des traits est l’implémentation du pattern Singleton. Lorsque l’on souhaite utiliser ce dernier, le premier réflexe pourrait être de créer une classe Singleton et de faire hériter nos objets de cette dernière. Mais ce n’est pas toujours possible à cause de l’impossibilité de faire de l’héritage multiple. Partant du principe qu’il est préférable de favoriser un héritage “fonctionnel”, il convient dans ce cas-là, d’avoir recours aux traits pour résoudre le problème :

trait Singleton
{
    protected static $instance = null;

    public static function getInstance()
    {
        if (null === $this->instance) {
            $this->instance = new self;
        }

        return $this->instance;
    }
}

class Example extends Article
{
    use Singleton;
}

$expl = Example::getInstance();

Héritage et Trait, les deux concepts ont leur place dans nos projets, utilisons-les à bon escient et au bon moment.

Support complet de Gitlab dans Composer

Wed, 25 Nov 2015 00:00:00 +0100

Inutile de vous présenter Composer l’outil de gestion des dépendances massivement utilisé par les développeurs PHP. Voici un court billet pour vous annoncer que ce dernier intègre désormais le support complet de Gitlab.

L’issue Github datée du 26 août 2014 et demandée le support de l’API Gitlab pour la gestion des dépendances (avec notamment la gestion des droits).

C’est désormais chose faite, un an et demi après, Composer fournit maintenant un driver Gitlab.

Pour l’utiliser dans votre projet, il vous suffira de configurer votre fichier composer.json avec les éléments suivants :

{
    "repositories": [
        { "type": "gitlab", "url": "http://gitlab.mysrv.com/path/to/my_project" }
    ],
    "config": {
        "gitlab-domains": ["gitlab.mysrv.com"]
    },
    "require": {
        "vendor/my-project": "~1.0"
    }
}

Les patterns "Builder" et "Factory": même combat

Mon, 16 Nov 2015 00:00:00 +0100

Aujourd’hui, j’ai envie de vous parler des patterns “Builder” et “Factory”. S’il y en a un qui est bien connu des développeurs, on ne fait pas toujours la distinction entre ces deux patterns qui ont un objectif similaire: la création de nouveaux objets.

La factory (ou fabrique en français) est un patron de conception qui permet de créer un objet sans avoir à connaître la classe exacte de l’objet retourné. Ce dernier est alors construit en une seule étape. Exemple :

class DatabaseConnectionFactory
{
    private $dbParams;

    public function __construct(array $params)
    {
        $this->dbParams = $params;
    }

    public function create($type)
    {
        switch ($type) {
            case 'mysql':
                return new MysqlDatabaseConnection($this->dbParams);

            case 'pgsql':
                $conn = new PgsqlDatabaseConnection();
                $conn->setParams($this->dbParams);

                return $conn;

            default:
                throw new \InvalidArgumentException();
        }
    }
}

Le pattern builder quand à lui se focalise sur la construction d’objets plus complexes qui ne peuvent être créés en une seule étape. Il est parfois nécessaire que la création d’un objet nécessite plusieurs étapes. C’est alors que les objets de type builder sont utilisés. Exemple :

class WebserviceClientBuilder
{
    private $serviceUrl;

    public function __construct($url)
    {
        $this->serviceUrl = $url;
    }

    public function build()
    {
        $clientStrategyFactory = new clientStrategyFactory();
        $client = $clientStrategyFactory->create($this->serviceUrl);

        return new WebserviceClient($client);
    }
}

L’exemple ci-dessus est très simple, mais on voit bien que la création d’un client pour utiliser le web service nécessite la création de deux objets : le premier permettant de définir la stratégie à adopter pour accéder à ce dernier et le second est le client à proprement parlé.

Il existe également d’autres patrons de conception permettant de créer des objets, mais ces derniers étant moins utilisé (donc certains que je n’ai jamais pratiqués), je n’en parlerai pas. Je vous invite notamment à découvrir les patterns Object pool et Prototype.

Gérer du multithread en PHP avec pthreads

Mon, 12 Oct 2015 00:00:00 +0200

PHP est par “défaut” un langage mono-thread et ne permet donc, par définition, de ne gérer qu’un seul processus à la fois. Or il peut s’avérer extrêmement avantageux de gérer plusieurs processus afin d’effectuer un certain nombre de tâches en parallèle. Il existe heureusement une extension PECL pour faire cela : pthreads.

« pthreads est une API orientée objet qui permet le multi-threading en PHP. Il inclut tous les outils nécessaires pour créer des applications multi-threadées pour le Web ou pour la console. Les applications PHP peuvent créer, lire, écrire, exécuter et synchroniser des Threads, des Workers, et des objets Threaded. »

Tout cela de manière très simple. La seule contrainte est que l’extension se base sur les threads POSIX et nécessitera donc l’installation du projet pthreads-win32 pour pouvoir fonctionner sous Windows.

Voici un exemple très simple de l’utilisation de l’extension :

<?php
$thread = new class extends Thread {
    public function run() {
        echo "Hello World\n";
    }
};

$thread->start() && $thread->join();
?>

J’ai par ailleurs publié une image Docker permettant d’exécuter PHP 7.0 préconfiguré avec l’extension pthreads. Tout cela est disponible sur le Docker Hub .

Exporter un fichier CSV avec Symfony2

Fri, 09 Oct 2015 00:00:00 +0200

Lorsque l’on travaille sur des applications de gestion, il est fréquent de devoir exporter des fichiers de données dans divers formats. Le plus simple des formats étant le CSV.

La plupart du temps, l’export passe par la génération d’un fichier temporaire qui est ensuite envoyé à l’utilisateur au travers d’un téléchargement de fichier via le navigateur. Pourtant Symfony2 fournit des outils permettant d’éviter de manipuler directement les fichiers temporaires via les StreamedResponse et les flux PHP.

La classe StreamedResponse permet de retourner un flux de réponse au client. Le contenu de la réponse est représenté par une fonction PHP au lieu d’une chaine de caractère :

public function generateCsvAction() {
    $repository = $this->get('app.repository.user');

    $response = new StreamedResponse();
    $response->setCallback(function() use ($repository) {
        $handle = fopen('php://output', 'w+');

        fputcsv($handle, ['Firstname', 'Lastname', 'Birthday'], ';');

        $results = $repository->findActiveUsers();
        foreach ($results as $user) {
            fputcsv(
                $handle,
                [$user->getFirstname(), $user->getLastname(), $user->getBirthday()],
                ';'
             );
        }

        fclose($handle);
    });

    $response->setStatusCode(200);
    $response->headers->set('Content-Type', 'text/csv; charset=utf-8');
    $response->headers->set('Content-Disposition','attachment; filename="export-users.csv"');

    return $response;
}

Objets-Valeurs et immutabilité

Tue, 21 Jul 2015 00:00:00 +0200

J’ai déjà parlé plusieurs fois des Objets-Valeurs (Value Objects) et quand les utiliser, mais je n’ai encore jamais évoqué le concept d’immutabilité qui en est indissociable.

Un objet immutable possède un état qui ne peut pas changer au cours du temps. Pourquoi est-il aussi important qu’un objet-valeurs ne puisse changer ? Les objets-valeurs ont pour objectif de représenter une donnée à un instant T. Ce qui a de la valeur pour un tel objet est son état. De ce fait, si l’état de notre objet change, il ne peut être représenté par une même instance (contrairement à un objet de type Entité) puisque c’est l’état de notre objet qui détermine son identité.

Prenons un exemple concret. Si dans un modèle objet, nous souhaitons représenter une couleur par un Objet-Valeurs, il est logique que ce dernier soit immutable. L’état caractèristique de l’objet et la couleur qui lui est associé, si cette dernière change, elle ne peut être associé à la même instance et il devra s’agir d’un nouvel objet.

Cela veut également dire que s’il est possible d’effectuer des opérations sur notre Objet-Valeurs, le résultat provoquera la création d’un nouvel Objet-Valeurs. Reprenons l’exemple de notre objet Money :

class Money
{
  /** @var int */
  private $amount;

  /** @var string */
  private $currency;

  /**
   * @param int    $amount
   * @param string $currency
   */
  public function __construct($amount, $currency)
  {
    $this->amount   = $amount;
    $this->currency = $currency;
  }

  /**
   * @return int
   */
  public function getAmount()
  {
    return $this->amount;
  }

  /**
   * @return float
   */
  public function getFormatedAmount()
  {
    return round($this->amount / 100, 2);
  }
}

Nous souhaitons ajouter la possibilité d’additionner deux objets de types Money. Pour cela nous ajoutons le code suivant :

class Money
{
  // ...

  /**
   * @param Money $money
   * @return static
   */
  public function add(Money $money)
  {
    // check same currency

    $value = $this->amount + $money->getAmoun();

    return new static($value, $this->currency);
  }
}

Le code ci-dessus permet d’ajouter deux objets Money et l’objet qui en résulte est un nouvel objet-valeurs. Il est ainsi possible d’ajouter des comportements à ces derniers tout en conservant le principe d’immutabilité.

Ecrire des logs manipulables

Wed, 15 Jul 2015 00:00:00 +0200

La notion de logs (ou journaux en français) est primordiale en développement. Ce sont eux qui permettent de faire remonter les informations générées par l’application une application. Ces derniers peuvent se présenter sous différentes formes : fichiers, base de données, sortie écran… Mais comment est-il possible de traiter ces différents retours facilement ?

Les données recueillies par les fichiers de logs informent des diverses situations rencontrées lors de l’exécution du code. Cela peut être des cas inattendus (exceptions), des erreurs, des informations sur les actions effectuées par les utilisateurs. Ils permettent aux développeurs de retracer l’exécution d’un bout de code. Les fichiers alors générés peuvent contenir un grand nombre d’informations et les analyser peut s’avérer être une tâche longue et complexe.

Bien entendu les informations écrites dans les fichiers de logs sont dépendantes de la phase de vie du projet. Il est ainsi fort probable que pendant la phase de développement, une grande quantité d’informations soient enregistrées afin d’avoir un maximum de détails. Par contre, une fois en production, le niveau de log sera réduit à son minimum afin d’avoir les informations essentielles.

De ce fait, une analyse automatique des logs s’avère très intéressante et peut révéler de nombreuses informations. Mais comment écrire des logs qui puissent être facilement traités et analysés par une machine ?

Pour cela, je vais m’appuyer sur les PSR (Propose a Standards Recommendation) de PHP et plus particulièrement la PSR-3 qui concerne les bibliothèques de journalisation. Si vous ne connaissez pas les PSR, il s’agit de recommandations validées par le PHP FIG (PHP Framework Interoperability Group) ayant pour objectif d’améliorer l’interopérabilité entre les frameworks PHP.

Pour résumer rapidement, dans PSR-3, on retrouve 8 niveaux de log avec autant de méthodes associées. Par exemple, le niveau DEBUG est associé à la méthode public function debug($message, array $context = array()). On retrouve également une fonction générique public function log($level, $message, array $context = array());

Ce que l’on peut remarquer avec les signatures de ces fonctions, c’est qu’elle ne se limite pas à écrire un message dans un fichier. Elles permettent également de renseigner un contexte d’exécution. Il est donc intéressant lorsque l’on écrit une ligne de log, de fournir des données sur l’état de l’application au moment donné. Par exemple :

$logger->info('User deletion', [
  'userLogged'  => $userLogged->getId(),
  'userDeleted' => $userDeleted->getId(),
]);

Le code ci-dessus génère la ligne suivante :

[2015-06-28 16:11:12] myapp.INFO: User deletion {"userLogged":1234,"userDeleted":7412} []

Cet exemple n’est pas très intéressant, je me limite à fournir les identifiants des utilisateurs concernés par l’action de suppression d’un utilisateur. De plus, si l’utilisateur est physiquement supprimé de la base de données, le fait d’avoir son identifiant est inutile. Il aurait été plus logique de donner les objets à la fonction de log qui les aurait sérialisés pour l’écrire du fichier.

Il est intéressant de noter que la ligne de log générée automatiquement analysée car elle est créée selon un schéma bien défini. Elle peut ainsi être découpée en 5 :

La date d’enregistrement : 2015-06-28 16:11:12
Le niveau de log : myapp.INFO
Le message de log : User deletion
Le contexte d’exécution : {"userLogged":1234,"userDeleted":7412}
Des données additionnels (dont je ne parle pas dans ce billet) : []

Il est donc très facile d’analyser les fichiers de manière automatique. L’analyse peut permettre d’obtenir des informations sur les erreurs rencontrées le plus souvent par l’application, mais également de faire des statistiques sur certaines utilisations de l’application. Ce travail d’analyse peut être réduit à son minimum car ce genre de logs peut être envoyé et analysé par des plateformes de type ELK (Elasticsearch Logstash Kibana).

Notons au passage que cette ligne de log aurait pu être plus difficilement analysable si elle avait été écrite de la manière suivante :

$logger->info(sprintf('User "%d" delete user "%d"',
  $userLogged->getId(),
  $userDeleted->getId()
);
// => [2015-06-28 16:11:12] myapp.INFO: User "1234" delete user "7412" []

Le problème avec cette méthode est que le message de log n’est pas “unique” pour une action donnée. Effectivement, l’action ayant déclenché l’écriture de la ligne est mélangée avec son contexte d’exécution.

Si vous souhaitez en savoir plus sur l’utilisation des fichiers de logs, Grégoire PINEAU, développeur chez SensioLabs a fait une excellente présentation lors du SFLive 2015 sur le sujet.

Quand utiliser le pattern Value Object ?

Tue, 23 Jun 2015 00:00:00 +0200

Il y a quelques mois, je parlais du pattern Objets-Valeur (ou Value Object en anglais). Dans le billet présentant brièvement ce patron de conception, j’évoquais le fait qu’il est souvent méconnu des développeurs PHP. De ce fait les exemples sont assez rares et il est alors difficile de savoir quand et/ou comment l’utiliser.

Lorsque l’on évoque ce pattern, le principal exemple qui est cité est celui de l’objet Money permettant de gérer la notion d’argent (valeur + devise). Mais il existe une multitude de projet ne faisait pas appel à cette notion et de ce fait le concept reste abstrait.

Il peut être pourtant relativement simple de détecter à quel moment nous pouvons et/ou devons utiliser un Objet-Valeurs. La principale structure de données utilisées par les développeurs PHP est le tableau associatif. Dans bien de cas, ce dernier peut être remplacé par un objet de type Objet-Valeurs.

Par exemple, prenons le code suivant qui parse un fichier XML :

public function parseLine($data)
{
    // ... code permettant de traiter les données

    return [
        'name'        => trim($columns[0]->textContent),
        'frequency'   => trim($columns[1]->textContent),
        'location'    => trim($columns[2]->textContent),
        'transmitter' => trim($columns[3]->textContent),
    ];
}

Dans cet exemple, la fonction renvoie un tableau associatif contenant les informations d’une donnée lue dans un fichier XML. On pourrait dans ce cas utiliser un Value-Objet. Cela aurait de multiples avantages :

Avoir un objet où il serait possible d’avoir les données caractéristiques de l’élément (les propriétés) ainsi qu’un ensemble de comportement que nous pouvons y appliquer (les méthodes).
Cela permet de rendre le code plus lisible et compréhensible par les autres développeurs. Pas besoin d’analyser le contenu de la variable puisque cette dernière est décrite au travers d’un objet.

On pourrait ainsi réécrire le code sous la forme suivante :

public function parseLine($data)
{
    // ... code permettant de traiter les données

    return new RadioFrequency(
        trim($columns[0]->textContent),
        trim($columns[1]->textContent),
        trim($columns[2]->textContent),
        trim($columns[3]->textContent)
    );
}

Notons que si nous souhaitons faire les choses correctement, il serait nécessaire de déléguer la création de notre objet RadioFrequency à une fabrique (Factory). Bien que cela peut sembler compléxifier notre code en rajoutant une classe supplémentaire, c’est en réalité tout le contraire. Au travers de cette modification, nous respectons le principe de responsabilité unique.

Ainsi, le code final serait :

public function __construct($radioFrequencyFactory)
{
    $this->radioFrequencyFactory = $radioFrequencyFactory;
}

public function parseLine($data)
{
    // ... code permettant de traiter les données

    return $this->radioFrequencyFactory->createFromDOMNode($columns);
}

Au final, n’est-il pas plus agréable de manipuler un objet clairement identifié et ayant un comportement défini plutôt qu’un tableau où il est difficile de connaître son contenu et les actions qui peuvent y être appliquées sans effectuer une inspection xDebug ou sans dumper ce dernier ?

Manipuler un champ Select2 avec Behat

Wed, 03 Jun 2015 00:00:00 +0200

Si vous développez en PHP, vous devez très certainement connaître Behat, le framework permettant de faire du développement piloté par le comportement (BDD, Behaviour Driven Development en anglais). Personnellement, je suis toujours embêté lorsque je me retrouve à écrire des scénarios devant manipuler une interface qui utilise le composant Select2 car il n’est pas possible de manipuler ce champ au travers de l’extension Mink.

Pour cela, il est nécessaire de créer des contextes personnalisés qui ajouteront des actions permettant de manipuler la liste déroulante. Etant donnée que je n’ai rien trouvé sur le Web, je vous partage le code qui permet d’interagir avec un champ Select2 dans un scénarii Behat.

/**
 * @When /^(?:|I )fill in select2 input "(?P<field>(?:[^"]|\\")*)" with "(?P<value>(?:[^"]|\\")*)" and select "(?P<entry>(?:[^"]|\\")*)"$/
 */
public function fillInSelectInputWithAndSelect($field, $value, $entry)
{
    $page = $this->getSession()->getPage();

    $inputField = $page->find('css', $field);
    if (!$inputField) {
        throw new \Exception('No field found');
    }

    $choice = $inputField->getParent()->find('css', '.select2-selection');
    if (!$choice) {
        throw new \Exception('No select2 choice found');
    }
    $choice->press();

    $select2Input = $page->find('css', '.select2-search__field');
    if (!$select2Input) {
        throw new \Exception('No input found');
    }
    $select2Input->setValue($value);

    $this->getSession()->wait(1000);

    $chosenResults = $page->findAll('css', '.select2-results li');
    foreach ($chosenResults as $result) {
        if ($result->getText() == $entry) {
            $result->click();
            break;
        }
    }
}

Avec ma société, nous avons également décidé de publier une extension Behat installable via Composer contenant un contexte permettant la manipulation complète d’un champ Select2. Cette dernière est disponible sur Github.

Le pattern "conteneur" (Container)

Wed, 22 Apr 2015 00:00:00 +0200

Lorsque l’on développe une application, le principal défi est de donner du sens à son code afin qu’il soit facilement compréhensible et maintenable. Une des nombreuses bonnes pratiques est alors d’utiliser des objets-valeurs plutôt que de simples variables. Pour stocker et manipuler ces derniers, il est possible d’utiliser un conteneur, un patron de conception souvent utilisé en parallèle.

En programmation objet, un conteneur n’est ni plus ni moins qu’un objet ayant pour but de gérer une collection d’élément. C’est un pattern assez peu utilisé dans le monde PHP car de nombreux développeurs ont pris l’habitude d’utiliser les tableaux associatifs fournis par le langage.

Il y a pourtant de multiples avantages à utiliser un conteneur dans vos applications. On peut citer :

Éviter la duplication de code dans les classes
Respecter le principe de responsabilité unique (vos objets métiers n’ont pas à se soucier de comment parcourir ou rechercher un élément dans un tableau, une liste ou une collection)

Pour vous aider à manipuler des conteneurs dans votre code, PHP fournit quelques interfaces qui peuvent être utiles lors de la mise en place de ces derniers :

Je suis toujours étonné que ce pattern ne soit pas plus connu et utilisé des développeurs PHP. Je rencontre souvent des développeurs qui me disent que la mise en place d’un tel objet est inutile et n’apporte pas de valeur (si ce n’est de complexifier inutilement le code). Sachez que vous manipulez ce genre de classe très souvent sans vous en rendre compte. Lorsque vous utilisez l’ORM Doctrine par exemple, qui utilise un conteneur ArrayCollection pour la gestion des associations multiples des entités.

Pas de logique dans les vues de vos applications MVC

Tue, 07 Apr 2015 00:00:00 +0200

La semaine dernière je suis tombé sur un article de blog écrit par Xavier NAYRAC, intitulé “Pas de logique dans les vues Rails”. Bien que l’article donne des exemples en Ruby, les propos du billet sont valables pour tous les langages et toutes les applications de type MVC. L’article étant pertinent, je relaie l’information.

Source

Utiliser les événements Symfony2 pour un code SOLID

Mon, 06 Apr 2015 00:00:00 +0200

En tant que développeur, nous essayons d’écrire du code simple, maintenable et facilement extensible. Pour cela, nous tentons de mettre en oeuvre les principes évoqués dans l’acronyme SOLID. Le “S” correspond à la notion de “Single Responsibility” (responsabilité unique). Cela signifie que vos classes doivent avoir une et une seule responsabilité, une seule raison d’exister.

Prenons pour exemple, un service Symfony dont l’objectif est d’enregistrer les données d’un utilisateur issu d’un formulaire. Le code pourrait alors ressembler à quelque chose comme cela :

// Controller/UserController.php
public function newAction(Request $request)
{
  $user = new User();

  $form = $this->createForm('user_form', $user, [
    'action' => $this->generateUrl('app_new_user'),
    'method' => 'POST'
  ]);
  $form->add('submit', 'submit', ['label' => 'Create']);

  $form->handleRequest($request);
  if ($form->isValid()) {
    $manager = $this->get('app.user_manager');
    $manager->save($user);

    return $this->redirectToRoute('user_show', ['id' => $user->getId()]);
  }

  return [ 'form' => $form->createView() ];
}

// Manager/UserManager.php
public function save(User $user)
{
  $this->entityManager->persist($user);
  $this->entityManager->flush();
}

Ce code respecte bien le principe de responsabilité unique, chacune de nos classes n’a qu’un seul objectif. Mais imaginons maintenant que nous souhaitons envoyer un email à l’utilisateur que nous venons de créer (pour le notifier de la création de son compte et lui envoyer ses informations de connexion par exemple).

Rien de difficile, il suffit alors de modifier notre manager pour envoyer le mail lors de la création du compte :

// Manager/UserManager.php
public function save(User $user)
{
  $this->entityManager->persist($user);
  $this->entityManager->flush();

  $this->emailManager->sendNewAccountNotification($user);
}

Sauf qu’en ajoutant cette ligne, nous venons de casser le principe de responsabilité unique de notre service gérant les utilisateurs. Réfléchissez bien, si vous souhaitez réutiliser la classe UserManager dans une autre application, mais que cette dernière ne souhaite pas envoyer de notification, comment allez-vous faire ?

Il vous faudra alors supprimer tous les appels à notre EmailManager ou mettre en place des conditions permettant de ne pas exécuter cette fonction. Dans le cas présent, l’exemple est très simple et cela peut être fait facilement. Mais imaginez une application de plusieurs milliers de lignes. Cela est tout de suite plus compliqué.

Heureusement, Symfony2 nous permet d’éviter ce couplage très simplement, au travers de la gestion des événements. L’idée est très simple, une fois l’enregistrement du nouvel utilisateur effectué, nous allons émettre un signal afin d’indiquer le succès de la création. Ce signal pourra alors être capter par différentes classes afin de déclencher différentes actions (un envoi de notification dans notre exemple).

Commençons par modifier notre classe UserManager :

// Manager/UserManager.php
public function __construct(EventDispatcherInterface $dispatcher, ...)
{
  $this->dispatcher = $dispatcher;
  // ...
}

public function save(User $user)
{
  $this->entityManager->persist($user);
  $this->entityManager->flush();

  $this->dispatcher->dispatch('user.create', new UserEvent($user));
}

La classe UserEvent est tout simple un conteneur pour les informations traitées par le formulaire (ici notre utilisateur créé).

use Symfony\Component\EventDispatcher\Event;

class UserEvent extends Event
{
  private $user;

  public function __construct(User $user)
  {
    $this->user = $user;
  }

  public function getUser()
  {
      return $this->user;
  }
}

Il ne reste plus qu’à intercepter le signal et à envoyer notre email :

<?php

use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class UserNotificationListener implements EventSubscriberInterface
{
  private $emailManager;

  public function __construct(EmailManagerInterface $emailManager)
  {
    $this->emailManager = $emailManager;
  }

  public function onUserCreate(UserEvent $event)
  {
    $this->emailManager->sendNewAccountNotification($event->getUser());
  }

  public static function getSubscribedEvents()
  {
    return [
      'user.create' => 'onUserCreate',
    ];
  }
}

Sans oublier de déclarer le service qui va bien :

// Resources/config/services.yml
services:
  listener.user_mailer_notification:
    class: Listener\UserNotificationListener
    arguments:
      - @app.manager.email
    tags:
      - { name: kernel.event_subscriber }

Nous avons donc maintenant des classes qui ont bien une responsabilité unique. De ce fait, le risque d’erreur est réduit. De plus cela, les rend plus facilement testables. Il sera également plus facile de les réutiliser dans d’autres projets.

Si vous souhaitez obtenir plus d’information concernant la gestion des événements dans Symonfy2, je vous invite à lire la documentation très bien rédigé à son sujet.

Intégration continue sur RaspberryPI avec PHPCI

Wed, 01 Apr 2015 00:00:00 +0200

Je possède un RaspberryPi que j’utilise essentiellement en tant que serveur personnel. J’y entrepose entre autres quelques petits dépôts Git que je souhaite garder privée. J’y ai également quelques scripts qui me permettent d’automatiser le déploiement de quelques applications (comme ce blog par exemple).

Pour automatiser un certain nombre de tâches et pour éviter de le faire manuellement, je souhaitais utiliser un outil de type intégration continue. Mon premier choix c’est alors porté sur le bien connu Jenkins. Bien évidemment, vu la puissance de la machine (que ce soit un RPi 1 ou 2), Jenkins est lent et ne permet pas d’être utilisé de manière fluide.

En recherchant sur le Web des solutions alternatives, je suis retombé sur PHPCI, une plateforme d’intégration continue spécialement conçue pour PHP et développé en PHP.

PHPCI ne se limite pas aux projets PHP. Je l’utilise pour une variété de tâches, notamment grâce à un plugin “Shell” qui me permet d’exécuter des commandes bash sur mes projets.

La solution est simple, légère et extrêmement fluide sur mon Raspberry2. Un vrai bonheur ! Comme je le racontais sur Twitter, je regrette vraiment de ne pas m’y être penché plus tôt.

pic.twitter.com/0HiuvDcMWl
— Jérémy DECOOL (@jdecool) 15 Mars 2015

En plus, le code de l’outil est plutôt simple et pouvoir mettre les mains dans le code est un vrai bonheur. De plus, l’équipe du produit (développé par une société anglaise pour ces besoins) est très sympathique et réactive sur Github.

Bien que cela ne fasse que quelques semaines que je l’utilise, l’outil me semble efficace et me semble une réelle alternative à Jenkins. Le seul véritable inconvénient, c’est le manque de plugin qui se fera sans doute sentir pour des projets complexes.

Les objets-valeurs (Value Object)

Wed, 25 Mar 2015 00:00:00 +0100

Tout récemment, nous avons eu un gros débat sur la conception d’un projet sur lequel je travaille. Le débat portait sur l’utilisation ou non d’un objet de type Objets-Valeur (ou Value Object en anglais). Il est vrai que dans l’environnement PHP l’utilisation de ce type d’objet est plutôt rare et méconnu (il est plus courant de voir utiliser des tableaux associatifs).

Les objets de type Objets-Valeurs sont généralement des petits objets dont leur objectif est d’apporter une notion sémantique au code. Contrairement à un autre objet, on s’intéresse à son contenu (la valeur de ses attributs) plutôt qu’à sa référence. Ces derniers sont généralement immuables.

L’exemple par excellence est certainement le cas de la monnaie. Si vous souhaitez gérer une notion d’argent, la monnaie peut alors être géré au moyen d’un Objet-Valeur, qui pourrait être défini comme ci-dessous :

class Money
{
  /** @var int */
  private $amount;

  /** @var string */
  private $currency;

  /**
   * @param int    $amount
   * @param string $currency
   */
  public function __construct($amount, $currency)
  {
    $this->amount   = $amount;
    $this->currency = $currency;
  }

  /**
   * @return int
   */
  public function getAmount()
  {
    return $this->amount;
  }

  /**
   * @return float
   */
  public function getFormatedAmount()
  {
    return round($this->amount / 100, 2);
  }
}

Cette exemple correspond à une implémentation du pattern monnaie décrit par Martin Fowler.

Il est alors plus agréable et compréhensible de manipuler un objet représentant une donnée précise qu’une variable de type entier ou flottante ayant une faible sémantique.

Ce type d’objet est très utilisé dans une conception pilotée par le domaine (Domain Driven Design) où le code est fortement basé sur le domaine métier et la logique associée. Ils permettent alors d’avoir un code compréhensible et avec un minimum d’ambiguïté.

PS: si vous êtes intéressé par une implémentation d’un Objet-Valeur permettant de gérer les devises. Sebastian BERGMANN a écrit une implémentation complète en PHP.

PHP-CLI cet outil méconnu

Fri, 06 Mar 2015 00:00:00 +0100

De nombreux développeurs travaillent avec PHP pour concevoir des sites ou des applications dans des environnements Web. On commence même à voir apparaître de nombreux outils utilisant PHP en ligne de commande. Pourtant ils sont peu nombreux à connaitre les possibilités offertes par PHP-CLI.

Prenons par exemple le cas d’un développeur PHP souhaitant tester une fonction PHP afin de l’utiliser. Je ne compte plus le nombre de développeurs ayant créé un fichier test.php afin de tester du code (fichier exécuté aussi bien via un serveur Web qu’en ligne de commande).

Effectivement, il est fréquent que les développeurs ignorent que PHP-CLI fournit un shell interactif permettant d’exécuter du code PHP (et donc de tester une fonction par exemple). Pour démarrer ce dernier, il suffit d’utiliser la commande php -a.

Prenons maintenant le cas du développeur qui souhaite afficher les informations de configuration PHP. Là encore, de nombreuses personnes créeront un fichier contenant un appel à la fonction phpinfo(). PHP-CLI fournit pourtant une option permettant d’afficher ces informations au travers de l’option -i.

De même si phpinfo() est également utilisé pour connaitre les modules PHP activées sur la machine, l’option -m permet d’obtenir la liste des modules actuellement actifs.

Il est de plus en plus fréquent d’utiliser des applications PHP en ligne de commande. L’exemple le plus courant est très certainement Composer. N’avez-vous jamais lancé un composer update et obtenu en réponse un message du genre Fatal Error: Allowed Memory Size of 134217728 Bytes Exhausted ?

Dans ce cas-là, il n’est pas toujours possible de modifier temporairement la configuration décrite dans le fichier php.ini. Vous me direz qu’il est toujours possible d’utiliser un appel à la fonction ini_set. Mais cela vous obligera à modifier votre code. Pour éviter cela (car en plus de ne pas être propre, c’est parfois impossible à mettre en oeuvre), PHP-CLI vous donne la possibilité de modifier une valeur de configuration au travers de l’argument -d.

Par exemple pour exécuter Composer avec une limite mémoire à 1 Go, il est possible d’utiliser la commande suivante :

php -d memory_limit=1024M /usr/local/bin/composer update

Il est bien évidemment possible de cumuler les variables de configuration à modifier. Vous pouvez donc appelez Composer en activer dynamiquement une extension PHP :

php -d memory_limit=1024M -d extension=blackfire.so composer.php

N’hésitez donc pas à découvrir ou redécouvrir les nombreuses possibilités de PHP-CLI, cela pourra vous servir et vous faciliter la vie au quotidien.

Tests fonctionnels et gestion des dates

Wed, 11 Feb 2015 00:00:00 +0100

Je travaille actuellement sur une application de gestion de prise de rendez-vous à destination des professionnels. Afin de s’assurer du fonctionnement correct de la plateforme, cette dernière est testée au travers de nombreux scénarios Behat.

L’exécution des tests Behat est relativement classique. Avant chaque scénario, un jeu de données est chargée en base de données afin de dérouler les différentes étapes. Néanmoins cette méthode présente un inconvénient majeur puisque le jeu de données est statique.

Or lorsque l’on travaille avec des gestions de date, cela peut poser quelques problèmes. Effectivement, si on prend par exemple un scénario de prise de rendez-vous en tenant compte qu’un rendez-vous ne peut pas être pris pour une date antérieure à la date du jour, il sera nécessaire de mettre régulièrement le jeu de données à jour afin d’éviter que les données de ce dernier ne soient obsolètes. La date de la machine exécutant les tests étant la date de référence.

Pour résoudre ce problème, on peut penser à plusieurs solutions. La première est certainement de générer un jeu de données dynamique afin d’avoir des données relatives à la date du jour. Je n’aime pas trop cette solution pour diverses raisons. La première car elle nécessite du développement (et que j’ai peu de temps :)). La seconde, car on “perd” un certain contrôle sur le jeu de données et les tests vont nécessiter plus de codes. Or je souhaite garder ces tests aussi simple que possible.

La seconde solution, m’ayant traversé l’idée était de modifier la date système lors de l’exécution des tests. Il ne m’a pas fallu longtemps pour me dire que c’était une très mauvaise idée !

Dans le cas présent, afin de faire le minimum de modification sur l’existant, en introduisant le minimum de développement, j’ai eu recours à une application nommée faketime.

Cette application permet d’intercepter les appels systèmes de récupération de la date et l’heure. Faketime permet ainsi de démarrer un processus en altérant de manière virtuelle la date de la machine uniquement pour le processus désigné.

Lancer l’exécution des scénarios Behat en utilisant faketime se fait au travers d’une simple ligne de commande :

faketime '2014-10-05 12:30:00' bin/behat  # Utilisation d'une date précise
faketime 'last Friday' bin/behat          # Utilisation d'une date relative

Ne faites pas de "composer update"

Thu, 05 Feb 2015 00:00:00 +0100

Un titre provoquant certes, je devrais plutôt dire : “ne faites pas de composer update” d’un seul coup sur la totalité des dépendances de votre projet (et en plus c’est une mauvaise pratique) ! Et à plus forte raison si votre application n’est pas bien couverte par des tests automatisés.

Personnellement, j’ai eu le cas pas plus tard qu’aujourd’hui. Un développeur devait réaliser une évolution mineure sur le projet sur lequel je travaille. Ni une, ni deux, il ajoute une nouvelle dépendance à la main dans le composer.json et exécute un composer update pour l’installer.

Je passe le fait de ne pas avoir utilisé la ligne de commande adaptée pour cette opération (un composer require vendor/package), mais en plus il n’a pas pris la peine de lancer les tests (unitaires et fonctionnels) présent sur le projet.

Le résultat ? De nombreuses dépendances du projet ont été mise à jour. Certaines introduisaient des “breaking changes” (dans un changement de version mineur) et 50% du projet est devenu non opérationnel en 30 secondes !

Mocker un service Symfony2 dans un test Behat

Tue, 03 Feb 2015 00:00:00 +0100

Il arrive fréquemment que l’on soit amené à utiliser des services Web tiers dans les applications que nous concevons. Lors de l’écriture de nos tests, nous utilisons des mocks (bouchons) afin de simuler le comportement de ces derniers.

Dans le cas d’un test Behat le premier réflexe est certainement d’accéder au containeur de dépendances depuis un contexte afin de modifier ce dernier à la volée.

Malheureusement cette solution ne fonctionne pas. Effectivement le conteneur de dépendance n’est pas partagé entre notre application et les contextes utilisées par Behat. Toute modification de nos dépendances est alors sans effet.

Une solution consiste alors à utiliser une configuration du conteneur de dépendances en fonction de l’environnement Symfony utilisé et d’exécuter nos scénarios sur l’environnement correspondant.

Commençons donc par modifier la configuration du service que nous souhaitons mocker (un composant Facebook dans notre exemple) :

# src/AppBundle/Resources/config/services.yml
services:
    app.component.facebook:
        class: %app.component.facebook.class%

Définissons maintenant la classe à utiliser dans le cas “normal” :

# app/config/config.yml
parameters:
    app.component.facebook.class: Component\Facebook\Facebook

Il ne nous reste plus qu’à surcharger ce paramètre lorsque l’on utilise l’application dans son environnement de test :

# app/config/config_test.yml
parameters:
    app.component.facebook.class: AppBundle\Tests\Mock\Component\Facebook\FacebookMock

Maintenant cette configuration terminée, en configurant Behat pour qu’il utilise l’environnement de test de Symfony, les différents scénarios seront exécutés avec la version de l’application utilisant les bouchons.

La technique utilisée ici est simple, mais peut être contraignante si vous avez un certain nombre de classes à “mocker”. Sur son blog, Grégoire Pineau (consultant chez SensioLabs) donne une autre alternative pour réaliser cette tâche et surtout plus pertinente si vous travaillez sur de grosses applications.

Protégez l'accès à vos ressources

Sun, 16 Nov 2014 00:00:00 +0100

Ce weekend, je baladais sur le site d’une agence musicale qui offre à ses clients des prestations audiovisuelles. La société offre notamment un accès à un large catalogue de musique à condition d’être un professionel du domaine de l’audiovisuel. Sauf qu’en réalité, avec un peu de débrouille, l’ensemble du catalogue est librement accessible.

Effectivement, lorsque l’on navigue sur le site en question, un lecteur audio permet d’écouter les titres disponibles. En analysant les trames réseaux, il est facile d’accéder à l’adresse du fichier qui est écouté :

Rien que via cette URL on peut récupérer le morceau complet au format MP3 encodé en 128 kbps. En analysant l’adresse du fichier, il est aisé de reconnaitre le schéma adopté http://site.com/musicfiles/[format]/[id-musique].[format].

En recherchant les différents morceaux, les identifiants des musiques sont facilement récupérables car ils apparaissent dans la barre d’adresse du navigateur.

Cela aurait pu s’arrêter ici, mais en lisant les mentions légales du site, on apprend qu’il est possible de télécharger les différents morceaux en format “MP3 (320 kbps)”, “AIFF” ou “WAV” (non compressé). Et oui c’est l’ensemble du catalogue dans tous les formats disponibles (et même haute définition) qui sont librement accessibles.

Il aurait pourtant été facile de protéger l’accès aux ressources en utilisant un petit script PHP comme celui ci-dessous :

ob_clean();

header('Content-Type: audio/mp3');
header('Content-Disposition: filename="fichier.mp3"');
flush();

readfile('chemin/vers/le/fichier.mp3');

Lorsque vous concevez un site, pensez bien à la sécurité des données de ce dernier et pas seulement celles qui sont présentes en base de données.

PS: un autre élément également inquiétant, les en-têtes renvoyées par le serveur Apache et qui indique que la version de PHP utilisée est la 5.2.17. Soit une version qui n’est plus maintenue depuis le 6 janvier 2011 !

Accéder aux commandes Doctrine dans Symfony2

Fri, 24 Oct 2014 00:00:00 +0200

Vous ne le saviez peut-être pas, mais lorsque vous démarrez un projet Symfony2, Doctrine est fourni avec un certain nombre de commandes prédéfinit. Parmi ces dernières certaines peuvent être très utiles comme par exemple une commande permettant d’importer un fichier SQL en base de données.

Si vous ne le saviez pas, c’est normal, car ces commandes n’apparaissent pas par défaut dans la console de Symfony. Mais étant donné qu’elles utilisent le composant Console du framework, il est facile d’y avoir accès.

Pour cela, la solution la plus simple est de créer une commande dans son projet et de la faire hériter de la commande Doctrine à laquelle on souhaite accéder.

Par exemple, si je souhaite accéder à la commande de Doctrine DBAL permettant d’insérer un fichier SQL en base de données, je peux écrire la commande ci-dessous :

namespace JDecool\Bundle\DemoBundle\Command;

use Doctrine\DBAL\Tools\Console\Command;
use Doctrine\DBAL\Tools\Console\Helper\ConnectionHelper;
use Doctrine\ORM\Tools\Console\Helper\EntityManagerHelper;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

class ImportCommand extends Command\ImportCommand
{
    protected function execute(InputInterface $input, OutputInterface $output)
    {
        $container = $this->getApplication()->getKernel()->getContainer();

        $doctrine = $container->get('doctrine');

        $em = $doctrine->getEntityManager();
        $db = $em->getConnection();

        $helperSet = $this->getHelperSet();
        $helperSet->set(new ConnectionHelper( $db ), 'db');
        $helperSet->set(new EntityManagerHelper( $em ), 'em');

        parent::execute($input, $output);
    }
}

Si vous souhaitez connaitre l’ensemble des commandes proposées par Doctrine, la liste est disponible sur la documentation officielle du projet.

Injecter la Request dans un service Symfony2

Thu, 09 Oct 2014 00:00:00 +0200

C’est une question qui revient souvent chez les développeurs, comment injecter la Request Symfony2 dans un service ? La réponse ne semble pas si simple à trouver car dans de très nombreux cas, je constate que pour pallier le problème, c’est tout le conteneur de dépendances qui est transmet au service en question. Une très mauvaise pratique !

C’était effectivement, à “une époque”, l’unique solution car Symfony gérant plusieurs Request, le problème de l’injection est très complexe. Depuis la version 2.4 du framework, un service “request_stack” est désormais disponible.

Si vous souhaitez avoir plus d’informations sur ce service et son utilisation, je vous renvoie vers la documentation du framework expliquant comment utiliser la RequestStack.

Comment obtenir l'opcode d'un script PHP ?

Tue, 07 Oct 2014 00:00:00 +0200

Si vous suivez un peu ce qui se passe dans la sphère PHP, vous avez peut-être vu passer une explication d’Igor WIEDLER concernant l’utilisation de l’instruction goto dans une librairie qu’il a écrit. Pour justifier son choix, Igor s’est appuyé sur l’opcode résultant de l’interprétation de son code. Je me suis alors demandé comment est-il possible de générer l’opcode résultant d’un script PHP.

Avant toute chose, je vais rappeler rapidement ce qu’est l’opcode. Lorsqu’un script PHP est exécuté, la machine virtuelle PHP va transformer le script lu en un langage intermédiaire qui représente des opérations de base. Ces instructions de bas niveau sont généralement appelé “opcode”.

Il y a plusieurs raisons qui peuvent pousser un développeur à visualiser l’opcode d’un fichier PHP. Tout d’abord par curiosité intellectuelle afin de comprendre comment fonctionne le langage. Il faut également savoir que par défaut, la machine virtuelle PHP n’optimise pas le code source qui est lu. Dans le cas, où il n’y a ni mécanisme d’optimisation, ni cache d’opcode, il peut être intéressant de connaitre l’opcode généré afin de faire quelques optimisations de son code.

Le moyen qui est certainement le plus simple pour visualiser l’opcode d’un code PHP est de se rendre sur le site 3v4l qui permet de tester du code sur plusieurs versions de PHP, mais il fournit également l’opcode résultant aussi bien pour le ZendEngine (la machine virtuelle PHP) que pour HHVM (la machine virtuelle de Facebook compatible PHP).

La solution précédente est simple, mais vous oblige à posséder une connexion Internet et à copier/coller vos différents scripts sur le site. Une autre solution consiste alors à installer une extension PHP qui nous permettra de visualiser la représentation interne des scripts exécutés.

L’extension en question s’appelle Vulcan Logic Disassembler. Cette dernière s’installe facilement au travers la commande pecl ou en récupérant son code source et en le compilant.

$ pecl install vld-beta

Une fois l’extension installée, vous pourrez visualiser l’opcode d’un script via la commande :

$ php -dextension=vld.so -dvld.active=1 mon-script.php

Finding entry points
Branch analysis from position: 0
Return found
filename:       /in/t0fJ6
function name:  (null)
number of ops:  2
compiled vars:  none
line     # *  op                           fetch          ext  return  operands
---------------------------------------------------------------------------------
   3     0  >   ECHO                                                     'Hello+World'
         1    > RETURN                                                   1

Si vous vous intéressez au fonctionnement interne de PHP, je ne peux que vous conseillez de lire ce livre collaboratif expliquant et décrivant le fonctionne interne de PHP.

Vous pourrez également en apprendre un peu plus avec le livre développer une extension PHP de Pascal MARTIN, qui tient également un blog où chaque mois, il résume ce qui se passe sur @internals, la mailing-list des développeurs de PHP.

L’issue Github dont il est question dans l’article
Un article de Pascal MARTIN sur une utilisation avancée de Vulcan Logic Disassembler.

Un adapteur générique pour appeler les fonctions natives de PHP

Wed, 01 Oct 2014 00:00:00 +0200

L’adaptateur (adapter en anglais) est l’un des design patterns les plus connus et utilisés en programmation. “Il permet de convertir l’interface d’une classe en une autre interface que le client attend. L’adaptateur fait fonctionner ensemble des classes qui n’auraient pas pu fonctionner sans lui, à cause d’une incompatibilité d’interfaces” (définition Wikipedia).

Il ne s’agit ni plus ni moins que d’un proxy qui va se charger de faire des appels d’une classe à un autre en transformant les données dans le format attendu. Les adaptateurs sont très utiles pour l’écriture de tests unitaires car ils permettent au travers de l’injection de dépendances d’être remplacé par un mock. C’est un cas d’utilisation très pratique lorsque l’on souhaite tester des blocs de code faisant appel à des fonctions natives de PHP.

Par exemple, si l’on souhaite lire un fichier de configuration, nous pourrions écrire le code suivant :

public function getUserConfiguration($user, $key)
{
    $configurationFile = file_get_contents($user->getConfigurationFile());

    $configuration = $this->parse($configurationFile);
    return $configuration[$key];
}

Le code ci-dessus pose problème, car il est impossible de contrôler l’exécution de la méthode file_get_contents. Si le test échoue, cela ne sera pas forcément lié au code qui a été écrit, mais peut-être au système de fichiers qui est indisponible au moment du test.

On peut alors écrire le test en utilisant un adaptateur :

public function getUserConfiguration($user, $key)
{
    $configurationFile = $this->fileAdapter->getFileContent($user->getConfigurationFile());

    $configuration = $this->parse($configurationFile);
    return $configuration[$key];
}

De cette manière, le code devient facilement testable, puisqu’il suffira d’utiliser un mock de la classe fileAdapter implémentant la méthode getFileContent.

C’est d’ailleurs en jetant un oeil dans le code source d’Atoum, un framework de tests unitaires (que je recommande vivement) que j’ai découvert un adaptateur générique permettant de tester naturellement les fonctions natives de PHP (également présenté dans un très bon article de Julien BIANCHI).

Voici le code de l’adaptateur :

// disponible à l'URL suivante => https://github.com/atoum/atoum/blob/master/classes/adapter.php
class adapter
{
    public function __call($functionName, $arguments)
    {
        return $this->invoke($functionName, $arguments);
    }

    public function invoke($functionName, array $arguments = array())
    {
        return call_user_func_array($functionName, $arguments);
    }
}

Cette classe est très astucieuse et fait appel “aux méthodes magiques” de PHP afin de rediriger les appels de l’adaptateur vers les fonctions natives du langage. De cette manière, plus besoin de créer une multitude de classes adaptateurs pour garantir que l’ensemble de notre code soit testable unitairement.

Attention toutefois à ne pas en abuser, les adaptateurs comme tout principe de programmation doivent être utilisé de manière judicieuse.

Des problèmes avec PHPStorm sous Linux ? Vérifier votre JRE

Mon, 29 Sep 2014 00:00:00 +0200

J’utilise depuis peu un nouvel environnement de développement basé sur une distribution Linux (Ubuntu 14.04). Ce fut l’occasion de réinstaller un stack LAMP complète avec l’IDE par excellence, j’ai nommé PHPStorm.

A priori aucun problème et tout se déroule correctement. C’est lors de l’utilisation de PHPStorm que je me suis aperçu de nombreux petits soucis (essentiellement graphique) mais très dérangeant pour un usage au quotidien.

Par exemple, la fenêtre d’auto-complétion qui ne se positionne pas au niveau du curseur, mais dans le coin en haut à droite de l’écran :

J’ai pourtant suivi la procédure d’installation de Jetbrains en installant une version officiel du JDK d’Oracle :

$ java -version

java version "1.8.0_20"
Java(TM) SE Runtime Environment (build 1.8.0_20-b26)
Java HotSpot(TM) 64-Bit Server VM (build 25.20-b23, mixed mode)

Et pourtant c’est en remettant une version OpenJDK installée de base sur l’OS que l’ensemble de mes problèmes ont disparus.

$ java -version

java version "1.7.0_65"
OpenJDK Runtime Environment (IcedTea 2.5.2) (7u65-2.5.2-3~14.04)
OpenJDK 64-Bit Server VM (build 24.65-b04, mixed mode)

J’ai alors immédiatement tenté l’installation du JDK 7 d’Oracle. Et là, aucun problème non plus. C’est donc bien la version 8 de Java qui est en défaut.

Donc si vous utilisez PHPStorm sous une Ubuntu (mais peut-être que le problème est présent sur les autres OS), pensez bien à vérifier le JDK installé sur votre machine.

Monitorez vos applications Symfony2 !

Tue, 23 Sep 2014 00:00:00 +0200

Vous venez de terminer votre application Symfony2 et de la déployer en production. Tous vos tests (unitaires et fonctionnels) sont au vert. Pourtant qu’est-ce qui vous assure que tout fonctionne correctement sur votre serveur ? Afin d’obtenir des informations sur ce qui se passe, il est nécessaire de mettre en place une solution de monitoring au sein de votre projet Symfony2.

Pour cela, je ne peux que vous conseiller d’utiliser le bundle SoclozMonitoringBundle qui vous permettra de monitorer (simplement et rapidement) le code Symfony sur vos serveurs de production afin de :

vous envoyer des emails lors du lancement d’exception
profiler le code PHP et d’envoyer les informations à statsd (un système de statistique)
logguer les informations de profiling
ajouter des en-têtes HTTP en cas de bugs

La mise en place (ainsi que la configuration) de ce bundle est extrêmement simple et rapide. Il vous faudra bien sûr, commencer par déclarer la dépendance dans votre fichier composer.json :

{
    "require": {
        ...,
        "socloz/monitoring-bundle": "dev-master"
    }
}

Et activer le bundle dans le kernel de Symfony :

class AppKernel extends Kernel
{
    public function registerBundles()
    {
        // ...

        if ($this->getEnvironment() == 'prod') {
            $bundles[] = new Socloz\MonitoringBundle\SoclozMonitoringBundle();
        }

        // ...

        return $bundles;
    }
}

Une fois ces deux opérations effectués, il ne vous reste plus qu’à configurer le bundle. Par exemple, l’exemple ci-dessous enverra un mail à l’adresse monitoring@mon-serveur.com lorsqu’une exception sera levée par l’application sauf pour les exceptions NotFoundHttpException et AccessDeniedHttpException :

socloz_monitoring:
    exceptions:
        enable: true
        ignore:
            - 'Symfony\Component\HttpKernel\Exception\NotFoundHttpException'
            - 'Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException'
    profiler:
        enable: false
    mailer:
        enable: true
        from: system@mon-serveur.com
        to: monitoring@mon-serveur.com
    statsd:
        enable: false

Un bundle indispensable pour garder le contrôle et améliorer la qualité de vos projets.

Protéger un champ de formulaire Symfony2 avec un droit

Tue, 09 Sep 2014 00:00:00 +0200

Il arrive fréquemment que l’on souhaite restreindre l’accès à certains champs de nos formulaires avec un (ou plusieurs) droit(s) utilisateur. Pour cela, une majorité de développeurs passera un paramètre dans le tableau d’options reçu par la fonction buildForm obligeant alors à modifier le code du formulaire pour traiter l’information reçue. Nous allons voir une alternative beaucoup plus élégante.

Pour cela nous allons créer une extension de type de formulaire qui se chargera de la vérification des droits et affichera ou non auprès de l’ utilisateur de notre application.

Prenons pour exemple un formulaire permettant de créer un billet de blog :

<?php

namespace JDecool\Bundle\ForumBundle\Form;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolverInterface;

class ThreadType extends AbstractType
{
     /**
     * @param FormBuilderInterface $builder
     * @param array $options
     */
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('title')
            ->add('content', 'textarea')
            ->add('solved', 'checkbox', [
                'required'   => false,
            ])
        ;
    }

    /**
     * @param OptionsResolverInterface $resolver
     */
    public function setDefaultOptions(OptionsResolverInterface $resolver)
    {
        $resolver->setDefaults(array(
            'data_class' => 'JDecool\Bundle\ForumBundle\Entity\Thread'
        ));
    }

    /**
     * @return string
     */
    public function getName()
    {
        return 'forum_thread';
    }
}

Maintenant que notre formulaire est défini, nous allons restreindre l’affichage du champ solved uniquement au utilisateurs ayant le rôle ROLE_ADMIN. Pour cela nous allons simplement ajouter une nouvelle propriété au champ correspondant.

public function buildForm(FormBuilderInterface $builder, array $options)
{
    $builder
        ->add('title')
        ->add('content', 'textarea')
        ->add('solved', 'checkbox', [
            'required'   => false,
            'is_granted' => 'ROLE_ADMIN',
        ])
    ;
}

Pour que ce paramètre soit interprété, nous allons créer notre extension de type formulaire en lui injectant le SecurityContext Symfony afin de vérifier les droits de l’utilisateur connecté.

<?php

namespace JDecool\Bundle\ForumBundle\Form\Extension;

use Symfony\Component\Form\AbstractTypeExtension;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\Form\FormEvent;
use Symfony\Component\Form\FormEvents;
use Symfony\Component\OptionsResolver\OptionsResolverInterface;
use Symfony\Component\Security\Core\SecurityContextInterface;

class SecurityTypeExtension extends AbstractTypeExtension
{
    /**
     * The security context
     * @var SecurityContextInterface
     */
    private $securityContext;

    /**
     * Object constructor
     */
    public function __construct(SecurityContextInterface $securityContext)
    {
        $this->securityContext = $securityContext;
    }

    /**
     * {@inheritdoc}
     */
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $grant = $options['is_granted'];
        if (null === $grant || $this->securityContext->isGranted($grant)) {
            return;
        }

        $builder->addEventListener(FormEvents::PRE_SET_DATA, function (FormEvent $event) {
            $form = $event->getForm();
            if ($form->isRoot()) {
                return;
            }

            $form->getParent()->remove($form->getName());
        });
    }

    /**
     * {@inheritdoc}
     */
    public function setDefaultOptions(OptionsResolverInterface $resolver)
    {
        $resolver->setDefaults(array('is_granted' => null));
    }

    /**
     * {@inheritdoc}
     */
    public function getExtendedType()
    {
        return 'form';
    }

}

Il ne reste plus qu’à enregistrer notre extension en tant que service :

services:
    jdecool_forum_bundle.security_type_extension:
        class: JDecool\Bundle\ForumBundle\Form\Extension\SecurityTypeExtension
        arguments:
            - @security.context
        tags:
            - { name: form.type_extension, alias: form }

Et voilà, il est maintenant possible de restreindre n’importe quel champ de formulaire avec un droit utilisateur sans avoir besoin de donner en paramètre l’utilisateur connecté ou à manipuler ce dernier dans notre classe de formulaire.

Mise à jour du 10/09/2014: Suite à de nombreuses réactions sur Twitter, je tiens à rendre à Ceasar ce qui appartient à Ceasar. Je ne suis pas l’auteur de ce code. Ce code a été trouvé dans un projet sur lequel je travaillais et que j’ai souhaité partager. Après des discussions, l’auteur est Alexandre SALOME, consultant chez SensioLabs qui avait donné cette astuce lors d’une présentation à un sfPot à Paris.

Utiliser une branche Github avec Composer

Fri, 05 Sep 2014 00:00:00 +0200

Lorsque l’on travaille sur un projet avec de multiples dépendances, il arrive que l’on soit amené à faire évoluer l’une d’entre elles pour les besoins de notre développement. Nous devons alors spécifier à Composer sur qu’elle branche il doit travailler.

Pour cela, nous allons prendre pour exemple une dépendance récupérée depuis un dépôt Github (le fonctionnement est similaire pour tout autre dépôt, via un Satis par exemple).

Il faut donc tout d’abord spécifier à Composer sur quel dépôt il va devoir travailler. Cette configuration se fait au travers d’une section “repositories” à ajouter dans le fichier composer.json.

{
	// ...

    "repositories": [
        {
            "type": "git",
            "url": "https://github.com/jdecool/my-lib"
        }
    ],

    // ...
}

Une fois le dépôt spécifié, il ne reste plus qu’à indiquer la branche de travail de votre dépendance.

{
	// ...

	"require": {
        // ...
        "vendor/my-lib": "dev-my-branch"
    },

    // ...
}

Vous pouvez maintenant effectuer un composer update vendor/my-lib pour mettre à jour la dépendance avec la branche du dépôt que vous venez de configurer.

Protégez vos actions Symfony2

Tue, 02 Sep 2014 00:00:00 +0200

Il est parfois excessif de créer un formulaire pour effectuer certaines actions au sein d’une application. Il est alors d’usage d’utiliser un lien HTML permettant d’effectuer ces opérations (c’est par exemple souvent le cas pour supprimer un élément dans une liste). Il est alors important de sécuriser ses actions.

Pour cela, imaginons une liste d’élément s’affichant de la manière suivante :

<table>
  <tr>
    <td>Mon élement 1</td>
    <td><a href="/element/1/delete">Supprimer</a></td>
  </tr>

  <tr>
    <td>Mon élement 2</td>
    <td><a href="/element/2/delete">Supprimer</a></td>
  </tr>
</table>

Bien sûr il ne s’agit là que d’un exemple, et dans une application réelle, il faudrait que l’action de suppression soit effectuée au travers d’une méthode POST ou DELETE.

En supposant qu’il y ait déjà une restriction en fonction des droits de l’ utilisateur connecté, nous allons donc protéger cette action d’une attaque de type CSRF. Pour cela nous allons voir comment générer un jeton qui permettra d’identifier la requête qui sera effectuée.

Nous allons donc commencer par créer le jeton dans l’action qui affiche la liste et ajouter la vérification du token dans l’action de suppression :

// src/JDecool/MyBundle/Controller/DemoController.php

public function listAction(Request $request)
{
	// ...
	$token = $this->get('form.csrf_provider')->generateCsrfToken('element_list');

	return $this->render('MyBundle::list.html.twig', [
		// ...
		'token' => $token,
	]);
}

public function deleteAction(Request $request, $id)
{
	if (!$this->get('form.csrf_provider')->isCsrfTokenValid('element_list', $token)) {
		$this->redirect('message_list');
	}

	// ...
}

Une fois ce code ajouté, il ne restera plus qu’à passer le jeton lors de la génération du lien de l’action.

Notez également que le jeton généré ici restera valide pour l’ensemble de la durée de la session de l’utilisateur et qu’il pourra être réutilisé. Le jeton est également généré à l’aide du paramètre secretprésent dans le fichier app/config/parameters.yml d’où l’importance de modifier ce dernier.

C’est une méthode simple et rapide qui vise à protéger votre application, et pourtant peu de développeurs l’utilise.

Visualiser le code coverage des tests Atoum dans PHPStorm

Tue, 19 Aug 2014 00:00:00 +0200

Lorsque je parle d’Atoum auprès de personnes qui ne l’utilisent pas, un des éléments qui revient très souvent (pour les utilisateurs de PHPStorm tout du moins), est l’impossibilité de visualiser la couverture du code par les tests directement dans l’IDE. Or à partir de maintenant, cela sera un argument qui ne tient plus.

Effectivement, il est désormais possible de visualiser le code coverage des tests Atoum directement dans PHPStorm grâce au plugin PHPUnit code coverage qui est désormais compatible avec les fichiers de type “clover” générés par Atoum.

Pour installer le plugin dans l’IDE, il faut aller dans les préférences de l’outil, puis dans la section “Plugin”. Cliquez sur le bouton “Browse repositories…” pour parcourir l’ensemble des plugins disponibles, et recherchez “PHPUnit code coverage” pour l’installer (il sera nécessaire de redémarrer PHPStorm).

Pour pouvoir utiliser le plugin, nous allons maintenant devoir configurer Atoum pour que ce dernier nous génère un rapport de type “clover”. Ce rapport se présente sous la forme d’un fichier XML décrivant tous les fichiers qui ont été parcouru par nos tests et indique quelles lignes ont été executé ou non. Le plugin lit ce fichier pour retranscrire son contenu dans l’IDE.

Pour générer ce rapport, il faut ajouter les lignes ci-dessous dans votre fichier .atoum.php:

$cloverWriter = new atoum\writers\file(__DIR__.'/build/atoum.clover.xml');
$cloverReport = new atoum\reports\asynchronous\clover();
$cloverReport->addWriter($cloverWriter);
$runner->addReport($cloverReport);

Une fois cela effectué, il ne vous reste plus qu’à configurer le plugin en lui indiquant où trouver le fichier généré. Il faut alors retourner dans les préférences de PHPStorm et ouvrir la section “PHPUnit code coverage”:

La configuration terminée, vous pourrez alors visualiser les blocs de votre code couvert par les tests et ceux qui ne le sont pas.

Plugin PHPUnit code coverage

Des dépôts Composer privés avec Satis

Tue, 12 Aug 2014 00:00:00 +0200

Composer est certainement l’un des outils PHP les plus connus et utilisé à l’heure actuelle. Il permet en effet de gérer très facilement les dépendances d’un projet PHP. Cependant, (trop) peu de développeurs connaissent ou utilisent Satis, l’outil de création de dépôts Composer.

Pourtant Satis est un outil très pratique et permet de mettre en place une gestion de dépôts privés. On peut également l’utiliser afin de mirrorer nos dépendances Composer provenant de Github, ce qui pourrait permettre de continuer à travailler même si Github venait à ne plus être disponible.

Si peu de personnes utilisent Satis, c’est peut-être à cause de sa mise en place qui peut sembler (au premier abord du moins) complexe. Pourtant, nous allons voir qu’il n’y a rien de compliqué et que la configuration de Satis ressemble étrangement à celle de Composer.

Nous allons donc commencer par installer Satis. Bien entendu, nous allons utiliser Composer pour cela. L’installation de Satis se fait en une ligne de commande: php composer.phar create-project composer/satis --stability=dev --keep-vcs.

Une fois installé, il faut configurer Satis en lui indiquant comment accéder à nos dépôts. Voici un exemple de fichier de configuration:

{
    "name": "Satis",
    "homepage": "https://satis.local.dev",
    "archive": {
        "directory": "dist",
        "absolute-directory" : "/home/satis/dist",
        "format": "zip",
        "skip-dev": true
    },
    "repositories": [
        { "type": "composer", "url": "https://packagist.org" },
        { "type": "git", "url": "git://git.local.dev/my-bundle" },
    ],
    "require": {
        "symfony/symfony": "2.5.*",
        "doctrine/orm": "*",
        "private/my-bundle": "*"
    },
    "require-all": true
}

Je ne vais pas détailler ici l’ensemble des éléments de la configuration de Satis, je vous invite à lire la documentation de Composer pour cela. J’attire cependant votre attention sur la section require qui, comme dans un fichier composer.json, indique les dépendances que vous souhaitez mettre à disposition. Dans l’exemple ci-dessus, la configuration crée un miroir des dépôts symfony/symfony et doctrine/orm ainsi qu’un dépôt privé permettant d’exposer le composant private/my-bundle provenant d’un dépôt Git.

Pour démarrer la création du dépôt Satis, il suffit d’exécuter la commande:

php /path/to/satis/bin/satis build /path/to/satis.conf /path/to/packages-repository

Il ne reste plus qu’à donner un accès au dépôt que l’on vient de créer en configurant un serveur Web:
php -S 0.0.0.0:4680 -t /path/to/packages-repository

Votre dépôt Satis est maintenant configuré et vous pouvez l’utiliser dans l’ensemble de vos projets PHP via Composer. Il faudra, au préalable, préciser l’adresse de votre dépôt Satis dans le fichier composer.json en ajoutant une section repositories:

"repositories": [
    {
        "type": "composer",
        "url": "http://your-mirror-server:4680"
    }
],

Documentation de Satis

Dépôt Github

Tester rapidement un site mobile avec Behat

Wed, 06 Aug 2014 00:00:00 +0200

J’utilise Behat au quotidien pour écrire mes tests fonctionnels. J’ai récemment eu besoin de mettre en place des tests pour un site mobile conjointement aux tests existant sur le projet. N’ayant que peu de temps alloué sur le projet, j’ai dû mettre en place des derniers très rapidement.

Pour cela, la solution qui me semblait la plus évidente était de modifier le user-agent du navigateur utilisé en le remplaçant par celui d’un appareil mobile. Or j’utilise Behat avec le driver Selenium2 qui n’autorise pas cette modification.

Les navigateurs modernes sont capables de gérer différentes configurations au travers d’un gestionnaire de profils. Une autre solution consiste alors à utiliser ces derniers en créant un profil qui aurait le user-agent voulu. Mes tests étant exécutés par Firefox, il suffit de démarrer ce dernier avec l’option -p pour ouvrir le gestionnaire de profil.

Une fois le nouveau profil créé, nous allons accéder à l’interface de configuration de Firefox en saisissant about:config dans la barre d’adresse. Il ne reste plus qu’à ajouter une nouvelle clé de configuration (si elle n’existe pas) nommée general.useragent.override en lui donnant la valeur désirée (dans mon cas un iPhone 4S utilisant Safari Mozilla/5.0 (iPhone; U; CPU iPhone OS 4_0 like Mac OS X; en-us) AppleWebKit/532.9 (KHTML, like Gecko) Version/4.0.5 Mobile/8A293 Safari/6531.22.7).

Il ne reste plus qu’à créer une archive ZIP contenant le profil que l’on vient d’ajouter. Ces derniers se trouvent dans les dossiers suivants :

Mac : /Users/<loginUtilisateur>/Library/Application\ Support/Firefox/Profiles/<identifiant.NomDuProfil>
Linux : ~/.mozilla/firefox/<identifiant.NomDuProfil>
Windows : C:\Users\<loginUtilisateur>\AppData\Roaming\Mozilla\Firefox\Profiles\<identifiant.NomDuProfil>

Maintenant il ne nous reste plus qu’à configurer un nouveau profil Behat pour l’exécution de nos tests avec ce nouvel environnement. Voici une configuration type que j’utilise dans mes projets Symfony2 :

mobile:
    paths:
        features: features/mobile
        bootstrap: %behat.paths.features%/bootstrap
    extensions:
        Behat\Symfony2Extension\Extension:
            mink_driver: true
            kernel:
                env: test
                debug: true
        Behat\MinkExtension\Extension:
            base_url: http://localhost:8000/app_test.php
            browser_name: firefox
            goutte: ~
            selenium2:
                capabilities:
                    firefox:
                        profile: '/chemin/vers/le/profil/firefox-mobile.zip'

Vous pouvez maintenant lancer vos tests avec un navigateur mobile en exécutant behat : bin/behat --profile mobile.

Cette installation rapide est surtout destinée à pouvoir écrire des tests fonctionnels rapidement et peut convenir pour des projets de faibles envergures. De plus elle ne fonctionne que pour des sites Web devant fonctionner sur mobile. Pour des tests plus pérennes ou pour des projets plus conséquents il conviendra d’utiliser des outils spécialisés dans les tests mobiles tels que SauceLabs, Appium, Selendroid, ios-driver.

Présentation "Introduction PHPUnit et Atoum"

Thu, 31 Jul 2014 00:00:00 +0200

Il y a quelques jours, j’ai eu l’occasion de parler des tests unitaires en PHP lors d’une présentation chez mon employeur actuel (Novaway). L’objectif était d’introduire les concepts fondamentaux liés aux tests unitaires et de présenter rapidement les 2 principaux frameworks de tests PHP : PHPUnit et Atoum.

J’ai réalisé les slides de la manière la plus objective possible en essayant de ne pas tenir compte de mon opinion concernant chacun des frameworks de manière à être le plus neutre possible.

Les slides sont disponibles sur Github et vous pouvez accéder à la présentation en ligne. Les slides ne sont plus disponibles sur Github, mais sont dorénavant consultable sur ce site.

Atoum et la gestion du error_reporting

Mon, 21 Jul 2014 00:00:00 +0200

J’utilise depuis quelques années maintenant Atoum pour écrire les tests unitaires sur mes différents projets (Open Source et professionnels). Pourtant cela ne m’empêche pas d’avoir encore quelques surprises lors de l’écriture de mes tests.

Ce weekend, en écrivant des tests sur une librairie PHP “legacy”, et en profitant pour y faire un peu de refactoring, mes tests Atoum me généraient une erreur PHP (E_STRICT) que je ne parvenais pas à reproduire via une application test.

La seule explication de ce phénomène est qu’Atoum surchage la configuration error_reporting de votre environnement PHP.

Après une rapide réflexion, cela n’est en soi pas une mauvaise idée, car cela vous permet de vous assurer que votre code ne contient réellement aucune erreur et cela indépendamment de la configuration qui sera utilisée sur la machine qui utilisera votre code (comme l’explique Frédéric HARDY lors d’un échange de tweet).