Au-delà du préfixage : un guide du développeur WordPress sur les espaces de noms PHP

Publié: 2019-11-12

Préfixez tout.

C'est un adage aussi vieux que le logiciel WordPress lui-même. Le préfixage est une norme pour les développeurs WordPress depuis si longtemps qu'il est difficile d'imaginer faire quelque chose de différent. Mais, le temps est venu pour quelque chose de nouveau. Eh bien, c'est en retard depuis longtemps, mais WordPress est un peu en retard par rapport aux pratiques standard dans le monde PHP plus large.

Le préfixage consiste à créer une version conviviale du nom de votre projet et à la coller devant les fonctions, les classes et d'autres éléments dans l'espace de noms global. Par exemple, vous nommeriez une fonction tavern_get_post() au lieu de get_post() pour éviter les conflits de noms de fonction, ce qui entraînerait une erreur fatale.

Le préfixage est une forme d '«espace de noms», qui est juste une façon élégante de dire que les noms dans cet espace appartiennent à un projet spécifique. Cependant, le préfixage (et le suffixage, ce qui est moins courant) est un hack d'une époque où aucune solution n'existait pour le langage PHP.

PHP 5.3 a introduit une méthode officielle d'espacement de noms, donc la norme existe depuis des années. Étant donné que WordPress 5.2 a fait passer l'exigence minimale de PHP à 5.6, il est temps pour les développeurs d'abandonner leurs anciennes habitudes et de rattraper le reste du monde PHP.

Espace de noms (presque) tout

L'espace de noms PHP ne couvre que les éléments suivants.

Des classes
Interfaces
Traits
Les fonctions
Constantes déclarées avec le mot-clé const mais pas define()

En ce qui concerne les descripteurs de script, les noms de taille d'image, les options de base de données et d'autres éléments de l'espace de noms global, vous devez toujours les préfixer. Ce sont des identifiants et en dehors du champ d'application de l'espacement de noms PHP.

Comment créer des espaces de noms

Les espaces de noms sont simples à déclarer. En haut de tout fichier PHP pour lequel vous souhaitez utiliser un espace de noms particulier, déclarez-le comme indiqué dans l'extrait de code suivant.

 <?php

taverne d'espace de noms ;

Cette ligne de code déclare que tout ce qui se trouve dans ce fichier particulier a l'espace de noms Tavern .

Jetez un œil à une fonction simple sous cet espace de noms pour générer un Hello, World! message.

 <?php

taverne d'espace de noms ;

fonction bonjour() {
    _e( 'Hello, World!', 'example-textdomain' );
}

Si vous respectiez les anciennes règles de préfixation, hello() aurait été nommé tavern_hello() . Cependant, ce n'est pas le cas avec les espaces de noms. La fonction hello() est encapsulée dans l'espace de noms Tavern et n'entrera pas en conflit avec d'autres fonctions nommées hello() .

Les classes et les interfaces fonctionnent de la même manière que les fonctions. Avec un nom de classe Article , le fichier de classe peut ressembler à ce qui suit.

 <?php

taverne d'espace de noms ;

article de classe {
    // ...
}

Remarque : Il ne doit jamais y avoir qu'une seule classe ou interface par fichier. Ceci est particulièrement important si vous envisagez d'utiliser un chargeur automatique.

Comment nommer les espaces de noms

Les développeurs aiment se disputer sur la façon de nommer les choses, et il n'y a pas de solution unique. La règle la plus importante est d'être unique pour éviter les conflits avec le code d'autres projets. L'un des meilleurs moyens d'y parvenir consiste à utiliser un espace de noms de Vendor de niveau supérieur avec un sous-espace de noms Package .

Supposons que l'espace de noms du fournisseur soit Tavern et que le projet en question soit un thème WordPress nommé News . L'espace de noms du projet peut ressembler à ce qui suit.

 <?php

espace de noms Tavern\News ;

Cela peut être un peu verbeux pour certains développeurs. Si le nom de votre projet est déjà assez unique, tel que "Awesomesauce", vous pouvez simplement utiliser ce qui suit.

 <?php

espace de noms Awesomesauce ;

Vous voudrez trouver une sorte de convention standard, à tout le moins, pour vous-même. Finalement, vous voudrez vous lancer dans des choses comme le chargement automatique, donc avoir un système que vous suivez dans tous vos projets vous aidera. N'hésitez pas à consulter la norme PHP-FIG Autoloader.

Importation de classes et de fonctions dans un espace de noms différent

Lorsque vous devez utiliser une classe ou une fonction à partir d'un espace de noms différent de l'espace de noms actuel, vous devez l'importer. Cela se fait via le mot-clé use en PHP.

L'instruction use doit venir après la déclaration d' namespace de noms. Il doit également faire référence au nom de classe complet. Le code suivant importe la classe Tavern\Helpers\Post dans un fichier avec un espace de noms différent.

 <?php

espace de noms Tavern\Template ;

utilisez Tavern\Helpers\Post ;

Une fois importé, vous pouvez utiliser directement la classe Post en toute sécurité, comme indiqué dans l'extrait suivant.

 $post = nouveau message();

Depuis PHP 5.6, vous pouvez également importer des fonctions et des constantes à partir d'autres espaces de noms en utilisant respectivement la use function use et les mots-clés use const . Le bloc de code suivant montre comment importer à la fois une fonction et une constante.

 <?php

espace de noms Tavern\Template ;

utilisez la fonction Tavern\Helpers\func_name ;
utilisez const Tavern\Helpers\CONSTANT_NAME ;

Aliasing de classes et de fonctions

Finalement, vous rencontrerez une situation où vous devrez importer une classe ou une fonction qui porte le même nom qu'une classe ou une fonction dans l'espace de noms actuel. Vous pensez peut-être que c'est le problème que les espaces de noms étaient censés résoudre. Heureusement, PHP fournit une méthode pour créer un alias lors de l'importation.

Supposons que vous ayez une classe nommée Tavern\User et que vous deviez implémenter l'interface Tavern\Contracts\User . Lors de l'importation de l'interface, vous devrez créer un alias comme indiqué ci-dessous.

 <?php

taverne d'espace de noms ;

utilisez Tavern\Contracts\User comme UserContract ;

classe L'utilisateur implémente UserContract {
    // ...
}

Le as UserContract ajouté à la fin de l'instruction use crée un alias pour l'interface User . Vous pouvez utiliser en toute sécurité le nouveau nom UserContract sans erreur.

Les classes, les interfaces, les fonctions et les constantes suivent toutes la même méthode pour créer un alias.

Organisation de la structure des dossiers en fonction des espaces de noms

C'est une pratique courante dans le monde PHP au sens large que les espaces de noms et la structure de fichiers et de dossiers du projet correspondent. Cela permet aux autres développeurs de localiser facilement le code dans votre projet. Cela simplifie également la création de chargeurs automatiques pour charger des classes à la demande.

En règle générale, tout le code PHP doit être placé dans un dossier /src , /inc ou un dossier portant un nom similaire dans votre projet. Un exemple de structure de fichier et de dossier de plug-in pourrait ressembler à ce qui suit.

 /nom-du-plugin
    /src
        /Coeur
            /Activer.php
            /Setup.php
        /Voir
            /Post.php
            /Page.php

Si vous suivez la même structure avec des espaces de noms, les fichiers .php ci-dessus contiendront les classes suivantes.

Tavern\Core\Activate
Tavern\Core\Setup
Tavern\View\Post
Tavern\View\Page

Notez que les noms de fichiers et de dossiers sont sensibles à la casse et doivent correspondre exactement à l'espace de noms et au nom de la classe.

Bien sûr, vous êtes libre de suivre toute convention que vous souhaitez. Cependant, la recommandation précédente est une bonne pratique et simplifiera l'organisation de vos projets à long terme.

Avantages de l'utilisation des espaces de noms

L'avantage le plus évident est d'éviter les conflits entre les classes et les fonctions portant le même nom. Vous devez utiliser de vrais espaces de noms pour la même raison que vous avez utilisé des préfixes.

Les espaces de noms permettent d'éviter les noms de classe longs. Taper des noms longs tout au long d'un grand projet est au mieux une pratique fastidieuse.

Changez plus facilement d'implémentation en important. Une fois que vous maîtrisez l'importation de classes et d'interfaces à partir d'autres espaces de noms, vous pouvez changer d'implémentation d'une interface avec une seule ligne de code.

Le chargement automatique des classes est beaucoup plus facile si vous suivez la norme PSR-4 : Autoloader, qui nécessite au moins un espace de noms de niveau supérieur.

Pour les développeurs de l'espace professionnel, vous acquerrez une compétence commercialisable au-delà de l'écosystème WordPress. Vous aurez du mal à trouver du travail de développement PHP si vous ne savez pas comment utiliser les espaces de noms. Ce n'est pas un concept difficile à saisir, mais il peut y avoir une courbe d'apprentissage pour certains dans la pratique.