Création d'un bundle PHP / Symfony

Introduction

Symfony est un framework basé sur le langage PHP, si vous utilisez ce framework, vous avez pu entrevoir la notion de bundles qui est à la base du fonctionnement de Symfony. Un bundle est l'équivalent d'un plugin et pourrait être vu comme une boîte à outils qui répond à un périmètre fonctionnel défini.

Dans cet article, nous allons détailler les étapes afin que vous puissiez créer un bundle et l'installer via composer. Afin d'illustrer nos explications, nous avons réalisé un bundle "Hello world" disponible sur notre Github.

Arborescence

Voici la liste des dossiers qui peuvent composer un bundle Symfony :

   assets/ : Contient les fichiers sources JavaScript, TypeScript, CSS et aussi les images ou autres fichiers qui ne sont pas liés au dossier public.

   config/ : Contient la configuration du bundle (routing, définition de services...).

   public/ : Contient les fichiers compilés (CSS, JavaScript) et les images copiées dans ce dossier.

   src/ : Contient les classes utiles pour la logique du bundle.

   templates/ : Contient les templates.

   tests/ : Contient les tests (unitaires, fonctionnels).

   translations/ : Contient les fichiers de traductions.

Tous ces dossiers ne sont pas indispensables, dans notre cas nous utiliserons seulement le dossier src/, voici à quoi va ressembler notre bundle :

IDCI/
├─ HelloWorldBundle/
│ ├─ src/
│ │ ├─ HelloWorldBundle.php
│ ├─ composer.json

Fichiers de base

composer.json

{
  "name": "idci/hello-world-bundle",
  "description": "Your bundle's description",
  "type": "symfony-bundle",
  "license": "CECILL-C",
  "keywords": ["tutorial", "Symfony", "Bundle", "composer", "packagist"],
  "authors": [
    {
      "name": "Joris VINIERE",
      "email": "joris.viniere@idci-consulting.fr"
    }
  ],
  "require": {
      "php": "^7.1 || ^8.0",
      "symfony/framework-bundle": "^6.1"
  },
  "autoload": {
    "psr-4": {
      "IDCI\\Bundle\\HelloWorldBundle\\": "src/"
    },
    "exclude-from-classmap": [
      "/Tests/"
    ]
  }
}

Voir l'exemple

Quelques informations sur les clés du fichier composer.json :

   name : Le nom du bundle.

   description : La description du bundle.

   type : Type du bundle qui peut différer selon la logique d'installation voulue.

   authors : Liste des auteurs du bundle.

   require : Liste des dépendances du bundle. Ici vous pouvez associer un nom de paquet à une version pour mentionner la dépendance.

   autoload : Mapping du chargement automatique des classes. Ici nous utilisons 2 clés :

      psr-4 : PSR-4 est une norme de chargement automatique qui permet de renseigner la structure des fichiers, la façon d'écrire les namespaces. Dans notre exemple le dossier src/ sera associé au namespace IDCI\Bundle\HelloWorldBundle\

      exclude-from-classmap : Permet d'exclure des fichiers ou dossiers du chargement automatique. Dans notre cas, l'ensemble des fichiers contenus dans le dossier Tests/ seront exclus du chargement automatique.

HelloWorldBundle.php

L'étape suivante est de créer la classe de votre bundle, il est important de noter que le nom de votre classe doit se terminer par "Bundle" comme visible dans notre exemple :

// src/HelloWorldBundle.php
<?php

namespace IDCI\Bundle\HelloWorldBundle;

use Symfony\Component\HttpKernel\Bundle\AbstractBundle;

class HelloWorldBundle extends AbstractBundle
{
}

Voir l'exemple

Notre classe hérite de la classe abstraite AbstractBundle. Pour rappel, une classe abstraite a pour caractéristique première qu'on ne peut pas l'instancier. Le fait d'hériter de la classe AbstractBundle permet de bénéficier des fonctionnalités de base fournies par cette classe.

Voilà ! Avec ceci, vous avez la base fonctionnelle d'un bundle Symfony.

Installation du bundle

Maintenant que nous avons terminé la création des fichiers de base du bundle, nous allons pouvoir l'installer dans nos applications. Il existe 2 façons pour inclure un bundle Symfony.

Bundle privé

Si le bundle n'est pas disponible sur Packagist, il faut préciser la source du repository en ajoutant une entrée dans la clé repositories du fichier composer.json de votre application. Ici, la clé type doit mentionner VCS (Version Control System) et la clé url doit contenir l'adresse de votre repository.

{
  "type": "project",
  "license": "proprietary",
  "minimum-stability": "dev",
  "prefer-stable": true,
  "require": {
    "php": ">=8.1",
    "symfony/framework-bundle": "6.4.*",
  },
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/IDCI-Consulting/HelloWorldBundle"
    }
  ],
  "autoload": {
    "psr-4": {
      "App\\": "src/"
    }
  }
}

Ensuite, il faut également ajouter une entrée dans la clé require.

{
  "type": "project",
  "license": "proprietary",
  "minimum-stability": "dev",
  "prefer-stable": true,
  "require": {
    "php": ">=8.1",
    "symfony/framework-bundle": "6.4.*",
    "idci/hello-world-bundle": "*"
  },
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/IDCI-Consulting/HelloWorldBundle"
    }
  ],
  "autoload": {
    "psr-4": {
      "App\\": "src/"
    }
  }
}

Enfin, lancez la commande composer install pour télécharger et installer les dépendances avec la version spécifiée dans le fichier composer.json.

Il est également possible de remplacer l'entrée dans require par la commande suivante :

composer require idci/hello-world-bundle

Si vous souhaitez vous assurer que le bundle a bien été installé, vous pouvez vérifier sa présence dans le dossier vendor/ de votre application.

Bundle public

Enregistrer un bundle sur Packagist

Pour déclarer publiquement un bundle, il faut disposer d'un compte sur la plateforme Packagist (Dépôt de paquets PHP). Une fois connecté, il faut se rendre dans l'onglet "Submit" et renseigner le lien de votre repository.

Installer un bundle via Packagist

Maintenant que le bundle est référencé sur Packagist, vous pouvez l'installer grâce à la commande composer require comme ci-dessous :

composer require idci/hello-world-bundle

Terminé ! Nous avons pu voir à travers cet article les différentes étapes de création et d'installation d'un Bundle Symfony en utilisant Composer et optionnellement Packagist.