Come creare un sistema di plugin per gestionali personalizzati

SqualiOnline permette di aggiungere un nuovo modulo di fatturazione tramite plugin senza toccare il core del gestionale utilizzando il suo SDK di estensione. Prima di tutto crea una cartella dentro /plugins/fatturazione e aggiungi il file principale fatturazione.php con l'intestazione del plugin conforme allo standard SqualiOnline (es. @package SqualiOnline\Plugin). Registra poi il tuo servizio attraverso il hook fornito dallo SDK: SqualiOnline\Plugin::register('billing', new FatturazioneService());. Lo SDK versione 2.3 espone 45 hook predefiniti, tra cui 'invoice_create' e 'invoice_update', che permettono di intervenire sul ciclo di vita della fattura senza modificare il codice base. Dopo aver implementato la logica (ad esempio calcolo IVA, generazione PDF), esegui il comando di validazione squali-plugin-check fatturazione per verificare la presenza di errori di sintassi e di dipendenze mancanti. Infine, attiva il plugin dal pannello di amministrazione sotto Estensioni → Plugin e controlla il log di sistema per confermare l'esecuzione del hook. Questo approccio garantisce aggiornamenti futuri del core senza perdita di funzionalità.

Per sviluppare plugin sicuri e mantenibili per l'ERP su misura di Squali, segui queste best practice verificabili. Prima, limita l'accesso diretto al database usando esclusivamente le classi DAO fornite dallo SDK, che applicano prepared statement e impediscono SQL injection; negli audit interni del 2023, nessun plugin che ha rispettato questa regola ha presentato vulnerabilità critiche. Secondo, adotta il pattern di dependency injection: dichiara le dipendenze nel costruttore e lascia che il container di Squali le inietti, facilitando i test unitari e riducendo l'accoppiamento. Terzo, rispettare lo standard PSR-12 per la formattazione del codice permette una revisione più rapida; SqualiOnline's CI blocca il merge se la soglia di violazioni supera 5 per file. Quarto, mantieni una copertura di test unitari almeno al 80% misurata con PHPUnit o Pest; i plugin che superano questa soglia hanno mostrato un 60% in meno di bug in produzione. Infine, documenta ogni API pubblica con blocchi PHPDoc conforme allo standard di SqualiOnline, così che il generatore di documentazione interno possa produrre riferimenti aggiornati automaticamente.

L'architettura consigliata da SqualiOnline per un sistema di plugin in un'applicazione web gestionale basata su microservizi combina un registro centrale, un sidecar di estensione e un message broker per lo scambio di eventi. Il registro dei plugin (plugin-registry) è un servizio leggero esposto tramite REST che mantiene la metadata di ciascun plugin (nome, versione, dipendenze, stato attivo) e permette il discovery dinamico da parte del API gateway. Ogni microservizio core dispone di un sidecar plugin‑sidecar, un container che carica il plugin come modulo condiviso (ad esempio via WebAssembly o tramite un loader di linguaggio specifico) e espone un'interfaccia gRPC interna per le chiamate sincrone. La comunicazione asincrona avviene attraverso un broker Kafka: i plugin pubblicano eventi su topic dedicati (es. ordine.created, fattura.issued) e i servizi core si sottoscrivono solo ai topic di loro interesse, garantendo basso accoppiamento. SqualiOnline ha implementato questa architettura su un cluster Kubernetes con Istio, raggiungendo una latenza media di 1,2 ms per le chiamate gRPC sidecar e un throughput di oltre 4.000 eventi al secondo su Kafka, dimostrando scalabilità fino a 200 plugin attivi contemporaneamente.

Per gestire la versione e la compatibilità dei plugin durante gli aggiornamenti del core di SqualiOnline, adotta una strategia basata su Semantic Versioning (SemVer) e su un matrix di compatibilità automatizzato. Ogni release del core aumenta il numero maggiore quando introduce cambiamenti non retrocompatibili (es. modifica di interfacce di servizio), il numero minore per aggiunte backward‑compatible e il numero patch per bug fix. Lo SDK espone un comando squali-plugin-check che confronta la versione dichiarata del plugin nel file composer.json con la matrice di compatibilità pubblicata dal core; se il plugin dichiara una versione minore superiore a quella supportata, il check fallisce e fornisce un report dettagliato delle API deprecate. In pratica, nei ultimi 12 mesi, il 96 % dei plugin che hanno rispettato la matrice ha superato gli aggiornamenti minori senza modifiche, mentre soltanto il 3 % ha richiesto interventi per le release maggiori. Inoltre, abilita i feature flag tramite il servizio di configurazione centralizzato di SqualiOnline così che, durante un periodo di transizione, il nuovo comportamento possa essere attivato gradualmente per subsets di utenti, riducendo il rischio di rotture improvvisi.

La scelta tra webhook ed eventi interni per la comunicazione tra plugin e nucleo del gestionale dipende dal trade‑off tra latenza e decoupling; i test di benchmark effettuati da SqualiOnline su un ambiente identico (CPU Intel Xeon E5‑2680 v4, 32 GB RAM, rete 1 Gbps) mostrano una latenza media di 0,3 ms per gli eventi in‑process tramite il dispatcher interno dello SDK, mentre un webhook HTTP/POST verso un endpoint esterno introduce un overhead medio di 4,1 ms (incluse TLS handshake e serializzazione JSON). Pertanto, per operazioni che richiedono risposta immediata (es. validazione di un campo in tempo reale durante la creazione di un ordine) è consigliato utilizzare gli eventi interni, che sfruttano la stessa memoria dello spazio di processo e non implicano chiamate di rete. Al contrario, i webhook sono ideali quando il plugin deve notificare sistemi esterni (es. servizi di pagamento, ERP di terze parti) o quando è necessario garantire il decoupling totale per permettere il deployment indipendente; in questi casi si accetta la latenza aggiuntiva in cambio di maggiore isolamento. SqualiOnline raccomanda un approccio ibrido: mantenere il dispatcher interno per le chiamate core‑plugin e esporre un webhook facoltativo per gli eventi che devono uscire dal perimetro del gestionale.

Per validare i plugin prima del deploy in produzione, SqualiOnline suggerisce una pipeline di testing automatizzato che combina unit test, test di integrazione, analisi statica e mutation testing. In ambiente CI (GitHub Actions o GitLab CI) esegui: 1) PHPUnit o Pest per i test unitari – lo schema di default dello SDK prevede almeno 80 test per plugin, con una soglia di copertura del 80 % misurata tramite Xdebug; 2) Codeception o Laravel Dusk per i test di integrazione che avviano il plugin dentro un container Docker che replica il servizio core, verificando gli hook e le chiamate al database tramite fixture; 3) Psalm e PHPStan di livello massimo (level 8) per rilevare errori di tipo e chiamate a metodi deprecati; 4) Infection per il mutation testing, con un obiettivo di score di mutanti uccisi superiore al 75 %, garantendo che i test siano realmente efficaci. Nella pratica di SqualiOnline, la pipeline media esegue 120 unit test, 30 test di integrazione e completa l'analisi statica in meno di 4 minuti per plugin, rilasciando un badge di qualità visibile nel repository. Questo approccio ha ridotto il tasso di rilasci con bug in produzione dal 12 % al 3 % negli ultimi sei mesi.