[phpBB 3.1.x] Créer une extension simple

Toutes les documentations phpBB seront ici.
Verrouillé
Avatar du membre
Dakin Quelia
Webmaster
Webmaster
Messages : 565
Enregistré le : ven. 27 nov. 2009 05:47
Localisation : Belgique
Contact :

[phpBB 3.1.x] Créer une extension simple

Message par Dakin Quelia »

» Créer une extension simple
A l'aide de cette documentation, vous allez pouvoir créer votre première Extension sur phpBB 3.1.x.

Note(s) :
  • Certains termes anglophones ne peuvent être changés.
  • Il suffira d'adapter les « votrepseudo » et « nomextension » lorsque vous créerez votre propre extension. Ceci est un exemple.
  • Votre extension doit être en anglais (langue par défaut) et peut être dans la langue votre choix.
  • Les clés de langue du template sont francisées pour cet exemple.
  • Faites bien attention aux espaces dans les fichiers YAML. N'indentez surtout pas (ne pas faire des tabulations) !!
Avant de commencer à créer votre propre extension, je vous recommande d'activer la recompilation des éléments du style. Pour ce faire, rendez-vous dans le panneau d'administration puis dans « Paramètres de charge » et cochez « oui » à « Recompiler les différents éléments du style ». Ceci vous sera utile pour afficher le rendu de votre extension.

Recommandation: tous vos tests de développement doivent être effectués sur un forum test en local.

» Création de l'arborescence

Tout d'abord, il faut définir l'arborescence même de l'extension. Choisissez un endroit où créer votre dossier puis créez un dossier nommé « votrepseudo ». Je vous recommande d'éviter les majuscules. Veuillez noter également qu'il est déconseillé de mettre un tiret. A l'intérieur de ce dossier, il faut créer un nouveau dossier nommé « nomextension ». C'est dans ce dossier que nous allons placer les futurs fichiers qui seront nécessaires à notre extension.

Attention : les tirets et autres caractères spéciaux ne sont pas autorisés.

Chque Extension devrait avoir une structure similaire à ceci (cela peut varier) :
01.png

Veuillez noter que j'ai volontairement ajouté certains dossiers pour que vous puissiez avoir un exemple concret d'une extension mais ils ne seront pas obligatoirement nécessaires. Cela dépendra du fonctionnement de votre extension. Il est possible également que d'autres dossiers hormis ceux-là viennent s'ajouter.

Maintenant, passons à l'étape suivante.

» Création d'un fichier composer.json

Pour commencer, il faut savoir que le fichier « composer.json » va donner certaines informations sur votre extension (le nom de l'auteur, la version de l'extension, la description etc).

Code : Tout sélectionner

{
    "name": "votrepseudo/nomextension",
    "type": "phpbb-extension",
    "description": "Description de votre extension",
    "homepage": "http://www.votresite.fr",
    "version": "0.0.1",
    "time": "2014-01-11",
    "license": "GPL-2.0",
    "authors": [
        {
            "name": "Votre Pseudo",
            "homepage": "http://www.votresite.fr",
            "role": "Votre rôle"
        }
    ],
    "require": {
        "php": ">=5.3.3"
    },
    "extra": {
        "display-name": "Nom de l'Extension",
        "soft-require": {
            "phpbb/phpbb": "3.1.*@dev"
        }
    }
}
Notez bien la structure et les espaces (et non de l'indentation). Vous remarquerez que dans le nom du dossier et de l'extension, il n'y a aucun tiret ou autres caractères. De plus, au niveau de la date, il faut garder le format tel quel. Si l'extension est créée le 11/03/2015, cela donnerait : 2015-03-11.

J'ai volontairement francisé l'exemple mais si vous souhaitez que votre extension soit validée sur phpBB.com, il faudra bien évidemment traduire tout cela en anglais. Il est important que la langue par défaut de l'extension soit en anglais

Ces informations seront disponibles lorsque vous activerez l'extension sur votre forum de développement. Pour voir ce que cela peut donner, rendez-vous dans le panneau d'administration de votre forum puis dans l'onglet « Personnaliser ». Cliquez sur « Gérer les extensions » sous « Gestion des extensions ». Vous allez voir les extensions actives et désactivées. Nous allons, dans notre exemple, cliquer sur « Détails » en face de l'extension nommée « Nom de l'Extension ». Voici un aperçu de ce que cela donne :
02.png

Vous avez ainsi déjà fait la première étape (la plus facile !!). Passons à la partie configuration.

» Création de la partie configuration

Cette étape de création des fichiers de configuration n'est pas très difficile mais nous allons voir tout ça avec un exemple. Tout d'abord, créez un fichier « services.yml » dans le dossier « config ». Dans notre cas, nous allons créer une extension simple donc le contenu du fichier ne serait pas très compliqué. Voici le code à mettre dans ce fichier :

Code : Tout sélectionner

services:		
    votrepseudo.nomextension.controller:
        class: votrepseudo\nomextension\controller\main_controller
        arguments:
            - @config
            - @request
            - @pagination
            - @dbal.conn
            - @auth
            - @template
            - @user
            - @controller.helper
            - %core.root_path%
            - %core.php_ext%
    
	votrepseudo.nomextension.listener:
        class: votrepseudo\nomextension\event\listener
        tags:
            - { name: event.listener }
Attention: la syntaxe du langage YAML n'utilise que des espaces et non des tabulations. Veuillez noter également l'ordre des arguments. Ceci est l'ordre à respecter dans l'appel des arguments de la fonction __construct() dans le contrôleur. Il est donc impératif de vérifier que l'ordre soit similaire (voir le fichier « controller.php » ci-dessous).

Si vous vous amusez à décortiquer des extensions réalisées par d'autres personnes, vous verrez des fichiers plus complexes. Ici, l'exemple est simple. Maintenant que notre fichier est créé, passons à l'étape suivante.

» Création de l'évènement

Dans le code donné précédemment, vous avez dû remarquer que nous appelions un évènement qui s'appelle « listener ». C'est donc ce fichier que nous allons créer. Pour ce faire, créons un fichier « listener.php » dans le dossier « event ». Dans notre exemple, nous allons simplement charger le fichier de langue relatif à notre extension.

Voici le code de notre fichier.

Code : Tout sélectionner

<?php
/**
*
* @package phpBB Extension - Nom Extension
* @copyright (c) 2015 Votre Pseudo
* @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License v2
*
*/

namespace votrepseudo\nomextension\event;

use Symfony\Component\EventDispatcher\EventSubscriberInterface;

/**
* Event listener
*/
class listener implements EventSubscriberInterface
{
/**
* Assign functions defined in this class to event listeners in the core
*
* @return array
* @static
* @access public
*/
    static public function getSubscribedEvents()
    {
        return array(
            'core.user_setup'                        => 'load_language_on_setup',
        );
    }
    
    public function load_language_on_setup($event)
    {
        $lang_set_ext = $event['lang_set_ext'];
        $lang_set_ext[] = array(
            'ext_name' => 'votrepseudo/nomextension',
            'lang_set' => 'common',
        );
        $event['lang_set_ext'] = $lang_set_ext;
    }
} 
Attention: le nom de la classe dans le fichier doit correspondre au nom du fichier.

Vous pouvez dans les commentaires ajouter votre pseudo et votre site web !

A ce stade, il ne se passe encore rien excepté le chargement du fichier de langue. De ce fait, allons à l'étape suivante.

» Création du contrôleur

Nous allons créer le fameux contrôleur qui va afficher notre page. Pour ce faire, commençons par créer un fichier « main_controller.php » (vous pouvez l'appeler différemment mais notez que vous devrez adapter le fichier « services.yml » en conséquence) dans le dossier « controller » de votre extension.

Code : Tout sélectionner

<?php
/**
*
* @package phpBB Extension - Nom Extension
* @copyright (c) 2015 Votre Pseudo
* @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License v2
*
*/

namespace votrepseudo\nomextension\controller;

use Symfony\Component\HttpFoundation\Response;

class main_controller
{
    protected $config;
    protected $db;
    protected $auth;
    protected $template;
    protected $user;
    protected $helper;
    protected $phpbb_root_path;
    protected $php_ext;

    public function __construct(\phpbb\config\config $config, \phpbb\request\request_interface $request, \phpbb\pagination $pagination, \phpbb\db\driver\driver_interface $db, \phpbb\auth\auth $auth, \phpbb\template\template $template, \phpbb\user $user, \phpbb\controller\helper $helper, $phpbb_root_path, $php_ext, $table_prefix)
    {
        $this->config = $config;
        $this->request = $request;
        $this->pagination = $pagination;
        $this->db = $db;
        $this->auth = $auth;
        $this->template = $template;
        $this->user = $user;
        $this->helper = $helper;
        $this->phpbb_root_path = $phpbb_root_path;
        $this->php_ext = $php_ext;
        $this->table_prefix = $table_prefix;
    }

    public function main()
    {
        // Output the page
        $this->template->assign_vars(array(
            'TITRE_PAGE'    => $this->user->lang('TITRE_PAGE'),
            'VOTRETEXTE'    => $this->user->lang('VOTRE_TEXTE'),
        ));

        page_header($this->user->lang('TITRE_PAGE'));
        $this->template->set_filenames(array(
            'body' => 'nomextension.html')
        );

        page_footer();
        return new Response($this->template->return_display('body'), 200);
    }
}
Attention : le nom de la classe doit correspondre au nom du fichier.

Voilà, nous avons mis en place notre contrôleur mais il faut définir les clés de langue utilisées dans notre code. Pour cela, rendons-nous à la prochaine étape de notre documentation.

» Création du fichier de langue

Pour ce faire, créons un fichier nommé « common.php » (nommé ainsi dans le listener) dans le dossier « language/fr/ » de votre extension. Il ne faut pas oublier d'encoder le fichier en UTF-8 sans BOM. Voici le contenu du fichier :

Code : Tout sélectionner

<?php
/**
*
* @package phpBB Extension - Nom Extension
* @copyright (c) 2015 Votre pseudo
* @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License v2
*
*/

if (!defined('IN_PHPBB'))
{
    exit;
}

if (empty($lang) || !is_array($lang))
{
    $lang = array();
}

$lang = array_merge($lang, array(
    'TITRE_PAGE'    => 'Mon titre',
    'VOTRE_TEXTE'   => 'Mon propre texte blabla'
));
Veuillez noter que nous n'ajoutons pas de « L_ » dans les clés de langue. Cet indicateur est utilisé dans les fichiers templates pour indiquer que c'est une clé de langue tout simplement.

» Création du template

La création d'un template n'est pas compliquée mais nécessite, néanmoins, quelques connaissances en HTML. C'est ici que nous allons définir l'affichage de notre extension.

Cette étape dépend, évidemment, du fonctionnement de votre extension. Toute extension n'inclut pas nécessairement un fichier template.

Dans notre cas, créons un fichier template que nous allons nommer « nomextension.html » (en anglais, la mention « _body » est un repère pour s'organiser mais pas indispensable) dans le dossier « styles/prosilver/template/ » de votre extension avec le contenu suivant:

Code : Tout sélectionner

<!-- INCLUDE overall_header.html -->
<h2>{L_TITRE_PAGE}</h2>
<p>{L_VOTRE_TEXTE}</p>
<!-- INCLUDE overall_footer.html -->
Voilà, il ne suffit plus qu'à personnaliser votre page avec le contenu que vous souhaitez.

Passons à la création d'une route !

» Créer une route (url)

Pour notre exemple, nous allons créer une route (essentiellement utile si nous créons une page avec du contenu et/ou des actions à effectuer). Pour ce faire, créons le fichier « routing.yml » dans le dossier « config » avec le code suivant :

Code : Tout sélectionner

votrepseudo_nomextension_controller:
    pattern: /mapage
    defaults: { _controller: votrepseudo.nomextension.controller:main }
Rien de bien compliqué. Vous pouvez nommer le « pattern » comme vous souhaitez mais notez bien qu'il faut conserver la barre oblique devant le nom. Il sera visible dans l'url (voir ci-dessous).

» Mot de la fin

Il ne reste plus qu'à vider le cache. Une fois effectué, il ne vous reste plus qu'à voir le résultat dans votre navigateur : http://localhost/phpBB31/mapage en supposant que phpBB31 est le nom du forum test.

Pour le nom de l'url, cela dépend de ce que vous avez choisi dans le point précédent.

» Support technique

Cette dernière partie concerne simplement le support relatif à cette documentation. Toute question relative à la création d'une extension doit être posée soit sur la communauté phpbb-fr.com (francophone) soit sur la communauté phpBB.com (anglophone). Donc n'hésitez pas à poser vos questions si nécessaires.
_________________
Voici un fichier zip de l'exemple de cette documentation.
demo.zip.zip
(12.52 Kio) Téléchargé 942 fois

Verrouillé

Qui est en ligne

Utilisateurs parcourant ce forum : Aucun utilisateur enregistré et 18 invités