Vos propres annotations personnalisées - plus que des commentaires!

Annotations personnalisées PHP: flexibilité et évolutivité du code améliorées

Cet article explique comment créer et utiliser des annotations personnalisées dans les applications Symfony 3. Les annotations sont les métadonnées / configuration du bloc de documents que nous voyons ci-dessus les classes, les méthodes et les propriétés. et l'accès aux méthodes. Cet article expliquera comment personnaliser les annotations et lire les informations de classe ou de méthode sans charger la classe. @Route() @ORM()

Points clés:

Les annotations personnalisées PHP peuvent être utilisées pour ajouter des métadonnées au code, affectant le comportement du code, ce qui le rend plus flexible et plus facile à s'adapter. Ils peuvent être utilisés pour définir les informations de routage, spécifier les règles de vérification ou configurer l'injection de dépendance.

• La création d'une annotation personnalisée PHP nécessite de définir une nouvelle classe pour représenter l'annotation. Cette classe doit avoir des propriétés correspondant à la valeur que vous souhaitez définir dans l'annotation.
• Doctrine prend en charge les annotations personnalisées. Vous pouvez définir vos propres annotations et les utiliser dans des entités de doctrine. Le lecteur d'annotation de la doctrine analyse ces annotations et peut ensuite les utiliser pour affecter le comportement d'une entité.
• Une limitation de l'utilisation d'annotations personnalisées PHP est qu'elles ne sont pas soutenues nativement par la langue elle-même. Cela signifie que vous devez utiliser des bibliothèques ou des outils qui fournissent un support d'annotation, tel que la doctrine ou le php-di.
• Les annotations personnalisées PHP ont une variété d'utilisations, notamment la définition des informations de routage dans une application Web, la spécification des règles de vérification pour l'entrée de formulaire ou la configuration de l'injection de dépendance. Ils peuvent également être utilisés pour ajouter de la documentation à votre code.

Avertissement:

L'annotation n'a rien à voir avec Symfony, c'est un concept développé dans le cadre du projet de doctrine pour résoudre le problème de la cartographie des informations ORM aux méthodes de classe. Cet article construira un petit bundle réutilisable appelé WorkerBundle (à des fins de démonstration uniquement, pas vraiment embalable). Nous développerons un petit concept qui vous permet de définir divers types de travailleurs qui "s'exécutent" à différentes vitesses, qui peuvent ensuite être utilisés par toute personne dans l'application. Les opérations réelles des travailleurs dépassent le cadre de cet article, car nous sommes soucieux de mettre en place le système qui les gère (et de les découvrir par annotations).

Vous pouvez afficher

ce référentiel

et configurer le bundle dans votre application Symfony locale comme décrit.

travailleur

Le travailleur implémentera une interface qui nécessite une méthode:

. Dans le nouveau WorkerBundle, créons un répertoire

pour le garder bien rangé et ajouter une interface: ::work() Workers/

<?php
namespace WorkerBundle\Workers;

interface WorkerInterface
{
    /**
     * 执行工作
     *
     * @return NULL
     */
    public function work();
}

annotations

Chaque travailleur doit implémenter l'interface ci-dessus. Très clair. Mais au-delà de cela, nous avons également besoin qu'ils aient une annotation au-dessus de la classe afin de les trouver et de lire des métadonnées à leur sujet.

Doctrine Maps Document Block Annotations à une classe dont les propriétés représentent des clés à l'intérieur de l'annotation elle-même. Créons nos propres annotations et faisons-le.

Chaque instance WorkerInterface aura l'annotation suivante dans son bloc de documents:

<?php
namespace WorkerBundle\Workers;

interface WorkerInterface
{
    /**
     * 执行工作
     *
     * @return NULL
     */
    public function work();
}

Nous resterons simples, avec seulement deux propriétés: nom unique (chaîne) et vitesse de travail (intégrale). Pour que la bibliothèque d'annotation de Doctrine reconnaisse cette annotation, nous devons créer une classe correspondante, qui, comme prévu, a des annotations en soi.

Nous mettons cette classe dans le dossier d'annotation de l'espace de noms du bundle et nous avons simplement nommé un travailleur:

/**
 * @Worker(
 *     name = "唯一的Worker名称",
 *     speed = 10
 * )
 */

Comme vous pouvez le voir, nous avons deux propriétés et quelques méthodes de Getter simples. Plus important encore, nous avons deux annotations en haut: @Annotation (dire à la doctrine une telle classe pour représenter une annotation) et @Target("CLASS") (dire qu'il doit être utilisé au-dessus de la classe entière plutôt qu'au-dessus de la méthode ou de la propriété). C'est tout, la classe WorkerInterface peut désormais utiliser cette annotation en s'assurant que la classe correspondante est importée à l'aide de l'instruction use en haut du fichier:

<?php
namespace WorkerBundle\Annotation;

use Doctrine\Common\Annotations\Annotation;

/**
 * @Annotation
 * @Target("CLASS")
 */
class Worker
{
    /**
     * @Required
     *
     * @var string
     */
    public $name;

    /**
     * @Required
     *
     * @var int
     */
    public $speed;

    /**
     * @return string
     */
    public function getName()
    {
        return $this->name;
    }

    /**
     * @return int
     */
    public function getSpeed()
    {
        return $this->speed;
    }
}

manager

Ensuite, nous avons besoin d'un gestionnaire que notre application peut utiliser pour obtenir une liste de tous les travailleurs disponibles et les créer. Dans le même espace de noms que WorkerInterface, nous pouvons utiliser cette classe de gestionnaire simple:

use WorkerBundle\Annotation\Worker;

Discoverer

La partie clé de notre démonstration d'annotation fait en fait partie du processus de découverte. Pourquoi? Parce que nous utilisons des annotations de travailleurs pour déterminer si la classe correspondante doit être traitée comme un travailleur. Dans ce processus, nous utilisons des métadonnées avant d'instancier l'objet. Jetons un coup d'œil à notre cours de travail de travail de travail:

<?php
namespace WorkerBundle\Workers;

class WorkerManager
{
    // ... (代码与原文相同) ...
}

connecter

Maintenant que nous avons les principaux composants, il est temps de tout connecter. Tout d'abord, nous avons besoin de la définition du service, donc dans le dossier Resource / Config du bundle, nous pouvons avoir ce fichier Services.yml:

<?php
namespace WorkerBundle\Workers;

// ... (代码与原文相同) ...
}

Pour que notre définition de service soit ramassée au centre par le conteneur, nous devons écrire une petite classe d'extension. Ainsi, dans le dossier de dépendance de la bundle, créez une classe appelée WorkErextension. L'emplacement et le nom sont importants pour que Symfony le ramasse automatiquement.

services:
    worker_manager:
        class: WorkerBundle\Workers\WorkerManager
        arguments: ["@worker_discovery"]
    worker_discovery:
        class: WorkerBundle\Workers\WorkerDiscovery
        arguments: ["%worker_namespace%", "%worker_directory%", "%kernel.root_dir%", "@annotation_reader"]

Enfin, nous devons enregistrer notre bundle. Dans notre appkernel:

<?php
namespace WorkerBundle\DependencyInjection;

// ... (代码与原文相同) ...
}

c'est tout.

Laissez-nous travailler!

Maintenant, nous sommes prêts à travailler. Configurons où notre travailleur se trouve dans le fichier central paramètres.yml:

public function registerBundles()
{
    return array(
        // ...
        new WorkerBundle\WorkerBundle(),
        // ...
    );
}

Ces paramètres sont passés du conteneur à la classe WorkerDiscovery, comme décrit ci-dessus.

L'emplacement dépend de vous, mais mettons maintenant notre travailleur dans le pack Appbundle principal de l'application. Notre premier travailleur pourrait ressembler à ceci:

<?php
namespace WorkerBundle\Workers;

interface WorkerInterface
{
    /**
     * 执行工作
     *
     * @return NULL
     */
    public function work();
}

Notre annotation est là, la déclaration use est en place, donc rien ne peut empêcher une logique métier de la trouver et de l'instanciation. Supposons que dans une méthode de contrôleur:

/**
 * @Worker(
 *     name = "唯一的Worker名称",
 *     speed = 10
 * )
 */

ou

<?php
namespace WorkerBundle\Annotation;

use Doctrine\Common\Annotations\Annotation;

/**
 * @Annotation
 * @Target("CLASS")
 */
class Worker
{
    /**
     * @Required
     *
     * @var string
     */
    public $name;

    /**
     * @Required
     *
     * @var int
     */
    public $speed;

    /**
     * @return string
     */
    public function getName()
    {
        return $this->name;
    }

    /**
     * @return int
     */
    public function getSpeed()
    {
        return $this->speed;
    }
}

Conclusion

Nous pouvons désormais utiliser des annotations pour exprimer des métadonnées sur les classes (ou méthodes et propriétés). Dans ce tutoriel, nous créons un petit package qui permet aux applications (ou à d'autres paquets externes) de déclarer un travailleur capable d'effectuer un travail en définissant des métadonnées à leur sujet. Ces métadonnées les rendent non seulement faciles à découvrir, mais fournissent également des informations sur leur utilisation.

utilisez-vous des annotations personnalisées dans vos projets? Si oui, comment les avez-vous implémentés? Peut-être qu'il y a une troisième méthode? Faites-le nous savoir!

---

(intéressé à en savoir plus sur Symfony, la doctrine, les annotations et divers contenu PHP de niveau d'entreprise? Rejoignez-nous pour un atelier pratique de trois jours, WebSummeramp - la seule conférence entièrement manuelle, et prendra également soin de vous de toute personne que vous voulez apporter!)

(La partie FAQ du texte d'origine a été omise car son contenu est très dupliqué avec du contenu traduit et réécrit.)

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!