Plugins
Les plugins doivent fournir un fichier composer.json situé dans la racine du plugin afin d’être reconnus par Elgg.
Contenu
elgg-plugin.php
elgg-plugin.php est un fichier statique de configuration du plugin. Il est lu par Elgg pour configurer différents services, et doit retourner un tableau s’il est présent. Il ne doit pas être inclus par les plugins et n’est pas destiné à être exécuté. A l’exception des constantes magiques comme __DIR__, sa valeur de retour ne doit pas changer. Les sections actuellement prises en charge sont :
plugin- définit les informations et les dépendances du plugin
bootstrap- définit une classe utilisée pour initialiser le plugin
entities- définit les types et les classes d’entités du plugin, et les enregistre éventuellement pour la recherche
actions- élimine la nécessité d’appelerelgg_register_action()
routes- élimine la nécessité d’appelerelgg_register_route()
settings- élimine la nécessité de définir des valeurs par défaut sur chaque appel àelgg_get_plugin_setting()
user_settings- élimine la nécessité de définir des valeurs par défaut sur chaque appel àelgg_get_plugin_user_setting()
views- permet aux plugins de créer des alias des actifs vers un chemin d’accès dans le système de vue de Elgg
widgets- élimine la nécessité d’appelerelgg_register_widget_type()
events- élimine la nécessité d’appelerelgg_register_event_handler()
cli_commands- un tableau de classesElgg/Cli/Commandpour étendre les fonctionnalités deelgg-cli
view_extensions- élimine la nécessité d’appelerelgg_extend_view()ouelgg_unextend_view()
thème- un tableau de variables pour les thèmes
group_tools- un tableau d’options des outils de groupe disponibles
view_options- un tableau de vues avec des options supplémentaires
notifications- un tableau d’événements de notification
web_services- un tableau de webservices exposés (utilisés par le plugin Web Services)
return [
'plugin' => [
'name' => 'Plugin Name', // readable plugin name
'activate_on_install' => true, // only used on a fresh install
'version' => '1.3.1', // version of the plugin
'dependencies' => [
// optional list op plugin dependencies
'blog' => [],
'activity' => [
'position' => 'after',
'must_be_active' => false,
],
'file' => [
'position' => 'before',
'version' => '>2', // composer notation of required version constraint
],
],
],
// Bootstrap must implement \Elgg\PluginBootstrapInterface
'bootstrap' => MyPluginBootstrap::class,
'entities' => [
[
// Register a new object subtype and tell Elgg to use a specific class to instantiate it
'type' => 'object',
'subtype' => 'my_object_subtype',
'class' => MyObjectClass::class,
'capabilities' => [
// Register this subtype for search
'searchable' => true,
'likable' => true,
],
],
],
'actions' => [
// Registers an action
// By default, action is registered with 'logged_in' access
// By default, Elgg will look for file in plugin's actions/ directory: actions/my_plugin/action.php
'my_plugin/action/default' => [],
'my_plugin/action/custom_access' => [
'access' => 'public', // supports 'public', 'logged_in', 'logged_out', 'admin'
],
// you can use action controllers instead of action files by setting the controller parameters
// controller must be a callable that receives \Elgg\Request as the first and only argument
// in example below, MyActionController::__invoke(\Elgg\Request $request) will be called
'my_plugin/action/controller' => [
'controller' => MyActionController::class,
],
],
'routes' => [
// routes can be associated with resource views or controllers
'collection:object:my_object_subtype:all' => [
'path' => '/my_stuff/all',
'resource' => 'my_stuff/all', // view file is in resources/my_stuff/all
],
// similar to actions, routes can be associated with a callable controller that receives an instance of \Elgg\Request
'collection:object:my_object_subtype:json' => [
'path' => '/my_stuff/json',
'controller' => JsonDumpController::class,
],
// route definitions support other parameters, such as 'middleware', 'requirements', 'defaults'
// see elgg_register_route() for all options
],
'widgets' => [
// register a new widget
// corresponds to a view in widgets/my_stuff/content
'my_stuff' => [
'description' => elgg_echo('widgets:my_stuff'),
'context' => ['profile', 'dashboard'],
],
],
'settings' => [
'plugin_setting_name' => 'plugin_setting_value',
],
'user_settings' => [
'user_setting_name' => 'user_setting_value',
],
'views' => [
'default' => [
'cool_lib/' => __DIR__ . '/vendors/cool_lib/dist/',
],
],
'events' => [
'delete' => [
'object' => [
'file_handle_object_delete' => [
'priority' => 999,
],
],
],
'create' => [
'relationship' => [
'_elgg_send_friend_notification' => [],
],
],
'log' => [
'systemlog' => [
'Elgg\SystemLog\Logger::log' => ['unregister' => true],
],
],
'register' => [
'menu:owner_block' => [
'blog_owner_block_menu' => [
'priority' => 700,
],
],
],
'usersettings:save' => [
'user' => [
'_elgg_save_notification_user_settings' => ['unregister' => true],
],
],
],
'cli_commands' => [
\My\Plugin\CliCommand::class,
'\My\Plugin\OtherCliCommand',
],
'view_extensions' => [
'page/components/list' => [
'list/extension' => [
'priority' => 600,
],
],
'forms/usersettings/save' => [
'core/settings/account/password' => [
'unextend' => true,
],
],
],
'theme' => [
'body-background-color' => '#000',
],
'group_tools' => [
'activity' => [], // just use default behaviour
'blog' => [
'default_on' => false,
],
'forum' => [
'unregister' => true, // unregisters the group tool option
],
],
'view_options' => [
'likes/popup' => [
'ajax' => true, // registers the view available via ajax
],
'likes/popup' => [
'ajax' => false, // unregisters the view available via ajax
],
'manifest.json' => [
'simplecache' => true, // register view as usable in the simplecache
],
],
'notifications' => [
'object' => [
'blog' => [
'publish' => true, // registers the event to be notified
],
'thewire' => [
'create' => false, // unregisters the event to be notified
],
'page' => [
'create' => MyPluginPageCreateEventHandler::class, // a custom event handler, needs to be an extension of a NotificationEventHandler
],
],
],
'web_services' => [
'test.echo' => [
'GET' => [ // the HTTP call method (GET|POST)
'callback' => 'my_echo', // required
'description' => 'A testing method which echos back a string', // optional, the description of the API method, a magic translation key is tried if not provided 'web_services:api_methods:<method>:<http call method>:description'
'params' => [ // optional, input parameters for the API method
'string' => [
'type' => 'string', // type of the parameter (int|integer|bool|string|float|array)
'default' => 'some value', // default value if not provided in the request
'required' => true|false, // required in the request
],
],
'require_api_auth' => false, // optional, requires API authentication (default: false)
'require_user_auth' => false, // optional, requires User authentication (default: false)
'associative' => false, // optional, provide the input params as an array to the callback function (default: false)
],
],
],
];
Classe d’initialisation - Bootstrap
À partir de Elgg 3.0, la manière recommandée pour initialiser votre plugin est d’utiliser une classe bootstrap. Cette classe doit implémenter l’interface \Elgg\PluginBootstrapInterface. Vous pouvez inscrire votre classe bootstrap dans elgg-plugin.php.
L’interface d’initialisation - bootstrap - définit plusieurs fonctions à implémenter qui sont appelées lors de différents événements dans le processus de démarrage du système.
Voir aussi
Pour plus d’informations sur les différentes fonctions définies dans \Elgg\PluginBootstrapInterface veuillez lire Initialisation - bootstrap - d’un plugin
elgg-services.php
Les plugins peuvent attacher leurs services au conteneur public DI de Elgg en fournissant des définitions PHP-DI dans elgg-services.php, situé à la racine du répertoire du plugin.
Ce fichier doit renvoyer un tableau de définitions PHP-DI. Les services seront disponibles via elgg().
return [
PluginService::class => \DI\object()->constructor(\DI\get(DependencyService::class)),
];
Les plugins peuvent ensuite utiliser l’API PHP-DI pour s’auto-câbler et appeler le service :
$service = elgg()->get(PluginService::class);
Voyez la documentation PHP-DI pour une liste complète des possibilités de définition et d’invocation.
composer.json
Depuis que Elgg prend en charge l’installation en tant que dépendance Composer , le fait que vos plugins prennent également en charge Composer facilite l’installation par des administrateurs de site. Afin de rendre votre plugin compatible avec Composer, vous devez au moins avoir un fichier composer.json dans la racine de votre plugin.
Voici un exemple de fichier composer.json :
{
"name": "company/example_plugin",
"description": "Some description of the plugin",
"type": "elgg-plugin",
"keywords": ["elgg", "plugin"],
"license": "GPL-2.0-only",
"support": {
"source": "URL to your code repository",
"issues": "URL to your issue tracker"
},
"conflict": {
"elgg/elgg": "<3.0"
}
}
Apprenez-en plus sur le format de composer.json sur le site de Composer.
Les parties importantes du fichier composer.json sont :
name: le nom de votre plugin, utilisez le même que le nom de dossier de votre plugin pour assurer une installation correctetype: indique à Composer où installer votre plugin, laissez TOUJOURS ceci surelgg-plugin
À titre de suggestion, incluez une règle conflict avec toute version d’Elgg inférieure à votre version minimale requise, cela aidera à empêcher l’installation accidentelle de votre plugin sur une version d’Elgg incompatible.
Après avoir ajouté un fichier composer.json à votre projet de plugin, vous devez enregistrer votre projet sur Packagist afin que d’autres personnes puissent installer votre plugin.
Tests
Il est recommandé de créer des tests PHPUnit pour votre plugin. Tous les tests devraient être situés dans tests/phpunit/unit pour les tests unitaires et tests/phpunit/integration pour les tests d’intégration.
Les tests unitaires devraient étendre la classe Elgg\UnitTestCase. Les tests d’intégration devraient étendre Elgg\Plugins\IntegrationTestCase.
Il existe un ensemble de tests d’intégration de plugins globaux qui s’exécutent sur tous les plugins actifs. Ces tests sont :
Elgg\Plugins\ActionRegistrationIntegrationTesttestera toutes les actions enregistrées du plugin sans fournir de donnéesElgg\Plugins\ComposerIntegrationTestva tester sicomposer.jsonest considéré comme valideElgg\Plugins\StaticConfigIntegrationTesttestera les sections deelgg-plugin.phpet vérifiera que le format est correctElgg\Plugins\TranslationsIntegrationTesttestera tous les fichiers de langue pour le format et l’encodage correctsElgg\Plugins\ViewStackIntegrationTesttestera toutes les vues du plugin s’il y a des erreurs d’analyse PHP
Voir aussi