Overview

Artifact ID: db7d4455bf7b700ed7746bf59d5c32a48164c160
Page Name:Plugins
Date: 2014-01-15 19:38:18
Original User: bohwaz
Parent: 5e599419b8909d0058e9a8a014b1787070255d1c (diff)
Next 1a87c44eb2b6f8d608685f257c0ec7c09a220e93
Content

Les plugins dans Garradin

  • Chaque plugin est une archive PHAR de PHP (voir structure archive plus bas)
  • Les plugins étendent ou complètent les fonctionnalités de Garradin, mais ne les remplacent pas et ne peuvent pas modifier la base de données directement
  • Toute modification de données doit s'effectuer via les objets et méthodes de Garradin pour éviter tout problème d'incohérence de données
  • Les plugins peuvent modifier le comportement de Garradin via des signaux/hooks (à venir)

Exemples de plugins possibles

  • Export dans un format spécifique
  • Création PDF de cartes d'adhérent
  • Gestion de stock
  • Point de vente (caisse)
  • Import depuis un format spécifique
  • Envoi de mails au format HTML

Structure archive PHAR

  • icon.png : icône taille 16x16
  • infos.ini : informations sur le plugin
  • index.php : affiché quand on clique sur le plugin
  • install.php (optionnel) : appelé lors de l'installation du plugin
  • upgrade.php (optionnel) : appelé lors de la mise à jour du plugin, qu'elle soit une mise à jour vers une version supérieure ou inférieure (downgrade)
  • uninstall.php (optionnel) : appelé lors de la suppression du plugin
  • signals.php (optionnel) : appelé quand un signal enregistré est activé

Contenu de infos.ini

nom="Nom du plugin"
description="Description courte du plugin"
auteur="Nom de l'auteur"
url="URL du site du plugin"
version="Numéro de version"
menu=0 ; ou 1 pour qu'une sous-entrée apparaisse dans le menu des plugins

Ces informations sont enregistrées dans la base de données de l'association

Méthodes de l'objet \Garradin\Plugin

  • __construct()
  • setConfig(string $key, string $value) : enregistre la configuration du plugin, si $value est null alors cette clé est effacée de la configuration
  • getConfig(string $key) : récupère la valeur de la clé $key pour la configuration du plugin
  • getInfos() : renvoie les informations enregistrées sur le plugin

Plugins officiels

Garradin offre deux possibilités d'installer des plugins :

  • simplement en copiant un fichier PHAR dans le répertoire 'plugins' de Garradin
  • en passant par un "répertoire" officiel, sorte d'appstore des plugins Garradin

Ce répertoire permet de télécharger et installer les plugins en un clic depuis l'interface de Garradin. Par la suite les plugins sont mis à jour automatiquement depuis ce répertoire quand une mise à jour est disponible.

Pour intégrer le répertoire des plugins officiels disponibles directement depuis Garradin le plugin doit :

  • être sous licence libre (compatible FOSS : GPL, AGPL, BSD, etc.)
  • respecter les règles présentées ci-dessous

Son code doit être lisible et clair, peu importe la convention de codage utilisé.

Règles de base à respecter par les plugins

Sur l'installation des plugins :

  • L'intégrité d'un plugin est vérifié en comparant son empreinte SHA-1 à celle contenue dans la liste fournie par le site de Garradin dans la liste des plugins officiels
  • Si le plugin figure dans la liste mais son intégrité n'est pas correcte il ne sera pas possible d'installer le plugin
  • Si le plugin ne figure pas dans la liste un message d'alerte et de demande de confirmation sera affiché avant installation (plugin non-officiel)

Sur les interactions avec la base de données :

  • Un plugin peut créer une nouvelle table dans la base de données de Garradin à l'installation, mais il doit alors la supprimer à la désinstallation
  • Un plugin ne peut pas créer de table en dehors de l'installation
  • Un plugin peut lire les données des tables de Garradin
  • Un plugin n'a pas le droit de modifier directement les tables de Garradin, seulement sa table propre
  • Un plugin peut lire, modifier et supprimer les données de la base Garradin via les méthodes de Garradin

Sur les fichiers :

  • Un plugin ne peut pas créer, éditer ou supprimer de fichier autre que temporaire
  • Pour créer et gérer des fichiers un plugin doit utiliser la gestion de documents de Garradin

Sur la communication à l'extérieur :

  • Un plugin ne devrait pas contacter un serveur distant sauf besoin spécifique.
  • Un plugin ne doit pas contacter un serveur distant à des fins statistiques.
  • Un plugin ne doit pas transmettre des informations sur la base de données ou son contenu, sauf cas spécifique.
  • Le plugin doit intégrer toutes ses dépendances, hormis celles qui sont déjà incluses avec Garradin.