Ajouter un Service à Elgg

Le guide sur les services présente des informations générales sur l’utilisation des services Elgg.

Pour ajouter un nouvel objet de service à Elgg :

  1. Annotez votre classe comme @internal s’il s’agit d’un service interne.

  2. Ouvrez la classe Elgg\Di\InternalContainer et/ou Elgg\Di\PublicContainer.

  3. Ajoutez une annotation @property-read au début de votre service. Cela permet aux IDE et aux analyseurs de code statique de comprendre le type de la propriété lors de l’utilisation de _elgg_services() ou elgg().

  4. Enregistrez votre service dans engine\internal_services.php ou engine\public_services.php en utilisant le câblage automatique - autowiring- ou avec une usine - factory.

Injectez vos dépendances

Elgg utilise PHP-DI pour l’enregistrement et la résolution des services. Les dépendances peuvent être câblées automatiquement (en fonction de l’argument typé du constructeur, les services peuvent être injectés) ou un service peut être construit dans une usine.

Note

Pour plus d’informations sur PHP-DI, visitez leur site Web.

Faire qu’un service fasse partie de l’API publique

Si votre service est conçu pour être utilisé par des développeurs de plugins :

  1. Faites une interface Elgg\Services\<Name> qui ne contient que ces méthodes nécessaires dans l’API publique.

  2. Faites que la classe de votre service implémente cette interface.

  3. Pour les méthodes qui sont dans l’interface, déplacez la documentation dans l’interface. Vous pouvez simplement utiliser {@inheritdoc} dans les PHPDocs des méthodes de votre classe.

  4. Documentez votre service dans docs/guides/services.rst (ce fichier)

  5. Ouvrez le test PHPUnit Elgg\ApplicationTest et ajoutez la clef de votre service au tableau $names dans testServices().

  6. Ouvrez la classe Elgg\Application.

  7. Ajoutez une déclaration @property-read pour documenter votre service, mais utilisez votre interface pour le type, et pas le nom de la classe de votre service.

Désormais votre service sera disponible via l’accès à la propriété sur l’instance Elgg\Application :

// using the public foo service
$three = elgg()->foo->add(1, 2);

Note

Pour des exemples, voyez le service config, qui comprend l’interface Elgg\Services\Config et la classe d’implémentation effective Elgg\Config.

Cycle de vie d’un Service et Fabriques - « Factories »

Par défaut, les services enregistrés sur le fournisseur de service sont partagés - « shared », ce qui signifie que le fournisseur de service va conserver l’instance créée pour le reste de la requête, et servir la même instance à tous ceux qui demandent la propriété.

Si vous avez besoin que les développeurs puissent construire des objets qui soient pré-câblés aux services Elgg, vous pouvez avoir besoin d’ajouter une méthode de fabrique publique à Elgg\Application. Voici un exemple qui retourne une nouvelle instance en utilisant les services internes de Elgg :

public function createFoo($bar) {
    $logger = $this->services->logger;
    $db = $this->services->db;
    return new Elgg\Foo($bar, $logger, $db);
}