Créer ses propres plug-ins

Introduction au développement de plug-ins dans Matomo

Comme évoqué à plusieurs reprises dans cet ouvrage, un plug-in fait référence à plusieurs choses dans Matomo, c’est aussi bien un ensemble de nouvelles fonctionnalités qu’un simple widget (en français, on parle de gadget), un thème ou une extension des API.

Les possibilités offertes par le développement de plug-ins sont extrêmement vastes ; retenez également qu’il existe plusieurs moyens en informatique d’arriver à une solution. Ainsi, les exemples évoqués dans cet ouvrage ne représentent qu’une manière de faire.

L’intérêt de la création de plug-ins pour Matomo est assez simple, cela permet de créer quelque chose qui n’existe pas par défaut dans le logiciel. Cela peut être aussi bien pour rattraper un éventuel retard que la solution aurait vis-à-vis de concurrents que pour combler un besoin personnel. Le chapitre relatif aux plug-ins communautaires en est un très bon exemple ; de nombreux plug-ins n’ont en effet aucun intérêt direct pour votre organisation.

La création de plug-ins pose la problématique de la sécurité ; ainsi, à l’exception des personnes souhaitant développer des plug-ins pour un besoin intellectuel, seuls des développeurs aguerris peuvent être amenés à en créer.

Au niveau des prérequis, il faut connaître le langage de programmation PHP ou, à défaut, savoir lire des lignes de code pour pouvoir copier-coller des plug-ins existants et modifier le code en conséquence, notamment pour la création de simples widgets.

Si vous souhaitez apprendre le PHP, il y a de nombreuses ressources disponibles : les cours d’openclassrooms permettent...

La mise en place de l’environnement de développement

Un environnement de développement consiste à créer un bac à sable sur votre ordinateur sur lequel sera installée une instance de Matomo spécifique pour la création de plug-ins. Cela permettra de cloisonner vos projets et d’éviter de rendre votre Matomo instable ; une simple erreur de frappe dans votre code pouvant techniquement mettre hors circuit votre site Matomo.

Pour mettre en place cet environnement de travail, nous vous recommandons de suivre la documentation officielle de Matomo : https://developer.matomo.org/guides/getting-started-part-1

Afin de préparer votre projet de création de plug-ins, Matomo recommande les outils suivants :

Le cahier des charges

Développer un plug-in, c’est comme développer un logiciel à l’intérieur d’un logiciel, ce n’est pas anodin. Cela va nécessiter beaucoup d’investissement. Il est donc important de bien documenter vos attentes, en général, cela prend la forme d’un cahier des charges réalisé sur un logiciel de traitement de texte.

Certains boudent cette étape et préfèrent se lancer sans aucune planification. En réalité, même avec un cahier des charges, le développement d’un plug-in est très hasardeux, donc n’imaginez même pas vous lancer sans.

À titre indicatif, voici ce que celui-ci peut contenir dans les grandes lignes :

Réalisation concrète d’un plug-in

Nous avons désormais notre environnement de développement qui est mis en place ainsi qu’une idée de notre plug-in, nous pouvons démarrer sa création. C’est assez simple.

./console generate:plugin --name="Endpoint" 

Endpoint correspondant au nom que nous souhaitons donner à notre plug-in, il va de soi que vous devez modifier cette valeur.

Une fois la ligne exécutée, la commande vous demandera une description ; il s’agira de celle qui sera affichée pour présenter votre plug-in :

À ce stade, votre plug-in vient d’être créé ; vous pouvez le voir directement dans le répertoire plug-ins, il est composé des fichiers suivants :

./console...

Référencer un plug-in sur la place de marché

Notre plug-in est désormais finalisé, nous pouvons donc le référencer sur la place de marché.

Première chose à savoir, le nom du plug-in ne doit pas comporter les mots suivants : "Matomo", "Piwik", "Analytics", "Core" ou "Plugin".

Ensuite, il faut compléter deux fichiers déjà présents dans le répertoire :

Concrètement, le fichier README.md va ressembler à :

et le fichier...

Créer un widget simple pour Matomo

Dans Matomo, les widgets permettent d’ajouter des informations au tableau de bord. C’est une manière assez simple d’appréhender la notion de développement de plug-ins.

Nous allons partir sur la création d’un plug-in présentant l’administrateur système (la personne chargée de l’instance Matomo dans l’organisation) car, très souvent, les utilisateurs de Matomo rencontrent des problèmes, mais ne savent pas forcément à qui s’adresser.

./console generate:plugin --name="SysAdminMessage" 

sudo ./console plugin:activate SysAdminMessage 

Une fois cela fait, il faut créer un widget pour ce plug-in.

./console generate:widget 

À partir de là, un fichier du nom de plug-ins/SysAdminMessage/Widgets.php vient d’être créé. Vous pouvez commencer à le modifier et/ou voir à quoi celui-ci ressemble dans votre interface :

Comme vous pouvez le constater ici, notre besoin va simplement consister à modifier l’information afficher par défaut, “My Widget Text” par un message personnel.

Le résultat final sera :

Vous pouvez désormais, en tant que super utilisateur, partager ce tableau de bord avec l’ensemble des utilisateurs de manière à ce qu’ils puissent tous voir ce message. Vous pouvez...

Gérer la configuration de Matomo avec un plug-in

La majeure partie des plug-ins communautaires incluent des fonctionnalités permettant d’agir sur la configuration de Matomo. Nous avons donc jugé bon de présenter un passage de ce livre dédié à la création d’un plug-in pour la configuration de Matomo.

Le contexte de la création de ce plug-in est le suivant : l’un de nos clients souhaite obtenir l’intégralité des pages consultées par les visiteurs via un rapport envoyé par e-mail. Or, par défaut, Matomo restreint l’export à 23 lignes dans son fichier de configuration et notre client n’avait pas accès au serveur :

L’objectif de ce plug-in est donc de créer un back-office dans lequel le super utilisateur peut indiquer le nombre de lignes qu’il souhaite avoir dans le rapport.

Sans partir forcément dans l’élaboration d’un cahier des charges détaillé, voici ce que nous aimerions obtenir :

Voici comment créer ce plug-in.

./console generate:plugin --name="EmailReportExtended" 

./console plugin:activate EmailReportExtended 

./console generate:settings 

À la question vous demandant pour quel menu vous souhaitez créer ces paramètres, répondez System et indiquez le nom de votre plug-in.

Une fois cette association effectuée, vous pourrez déjà constater dans l’administration le look and feel de votre plug-in :

Comme vous pouvez le remarquer ici, au niveau de l’interface graphique, cela ne semble pas au premier abord très compliqué à faire ; il suffirait simplement...

La création d’un thème dans Matomo

À l’image des widgets, la création d’un thème peut sembler au premier abord comme quelque chose d’insurmontable pour une personne n’ayant pas de connaissances en développement informatique. 

Une fois de plus, c’est avant tout une bonne documentation au départ qui va vous permettre d’y voir plus clair.

Un thème étant principalement composé de couleurs, il faut trouver une palette de couleurs harmonieuses. Nous avons pour cela utilisé le site suivant : https://artsexperiments.withgoogle.com avec pour ensemble de couleurs :

Une fois ces couleurs déterminées, il faut également choisir une police de caractère. Dans notre cas de figure, nous allons partir sur la police Calibri, l’idée étant de montrer la différence avec la police de caractères par défaut de Matomo.

./console generate:theme 

sudo ./console plugin:activate nomdevotretheme 

Matomo offre davantage de possibilités pour la création de plug-ins. Nous vous conseillons pour ce faire de vous référer à la documentation officielle pour les développeurs : https://developer.matomo.org/develop...