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()
hooks
- élimine la nécessité d’appelerelgg_register_plugin_hook_handler()
cli_commands
- un tableau de classesElgg/Cli/Command
pour é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
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,
// Register this subtype for search
'searchable' => 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', '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/',
],
],
'hooks' => [
'register' => [
'menu:owner_block' => [
'blog_owner_block_menu' => [
'priority' => 700,
],
],
],
'likes:is_likable' => [
'object:blog' => [
'Elgg\Values::getTrue' => [],
],
],
'usersettings:save' => [
'user' => [
'_elgg_save_notification_user_settings' => ['unregister' => true],
],
],
],
'events' => [
'delete' => [
'object' => [
'file_handle_object_delete' => [
'priority' => 999,
],
],
],
'create' => [
'relationship' => [
'_elgg_send_friend_notification' => [],
],
],
'log' => [
'systemlog' => [
'Elgg\SystemLog\Logger::log' => ['unregister' => true],
],
],
],
'cli_commands' => [
\My\Plugin\CliCommand::class,
'\My\Plugin\OtherCliCommand',
],
'view_extensions' => [
'elgg.js' => [
'bookmarks.js' => [],
],
'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
],
],
],
];
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"
},
"require": {
"composer/installers": "^1.0.8"
},
"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
require
: l’exigencecomposer/installers
vise à s’assurer que Composer sait où installer votre plugin
À titre de suggestion, incluez une règle de conflict
avec n’importe quelle version de Elgg inférieure à votre version minimale requise, cela aidera à éviter l’installation accidentelle de votre plugin sur une version de 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.
Un exemple simple d’ajout de test est le test ViewStackTest
, qui va vérifier que les vues de votre plugin sont enregistrées correctement et n’ont pas d’erreurs de syntaxe. Pour ajouter ce test, créez un fichier ViewStackTest.php
dans le dossier tests/phpunit/unit/<YourNameSpace>/<YourPluginName>/
avec le contenu suivant :
namespace <YourNameSpace>\<YourPluginName>;
/**
* @group ViewsService
*/
class ViewStackTest extends \Elgg\Plugins\ViewStackTest {
}
Note
Si vous souhaitez voir un meilleur exemple, regardez dans l’un des plugins du noyau de Elgg.
Voir aussi