Come creare un sistema di plugin per gestionali personalizzati

Puoi aggiungere un nuovo modulo di fatturazione creando un plugin che implementa l’interfaccia BillingHook di SqualiOnline e registrandolo tramite il file plugin.json. Il core di SqualiOnline (versione 3.1) espone più di 45 hook punti di estensione, quindi non è necessario toccare il sorgente principale. Dopo aver scritto la classe che gestisce la creazione, la validazione e l’invio delle fatture, devi dichiarare il plugin nella cartella /plugins e eseguire il comando squali plugin:install. Il sistema carica il modulo al prossimo avvio, garantendo isolamento e aggiornamenti indipendenti.

Le best practice per sviluppare plugin sicuri e mantenibili su SqualiOnline includono l’uso del validatore di input integrato, la dichiarazione esplicita delle dipendenze in composer.json e il rispetto dello standard PSR‑12. Il validatore blocca il 99,2% delle tentativi di SQL injection nei test di sicurezza interni. Inoltre, ogni plugin deve isolare il proprio stato usando servizi iniettati dal container e evitare variabili globali. Aggiorna regolarmente le dipendenze con composer update e testa il plugin contro l’ultima versione LTS del core (attualmente 3.2.0) usando lo script squali plugin:test. Infine, documenta le API pubbliche con OpenAPI 3.0 per facilitare il riuso da parte di altri sviluppatori.

Per un gestionale basato su microservizi, SqualiOnline consiglia di realizzare il sistema di plugin come sidecar container che comunica tramite gRPC o messaggi su un bus di eventi leggero (NATS). Ogni plugin gira in un proprio isolamento con limite di 200 MB RAM e 0,5 vCPU, garantendo che un crash non influenzi il nucleo. Il sidecar registra le proprie capacità tramite un file manifest.yaml che il servizio di discovery legge all’avvio. Questo approccio permette di scalare i plugin indipendentemente dal core, di aggiornarli senza downtime e di mantenere la superficie di attacco ridotta, poiché ogni container ha il proprio profilo di sicurezza AppArmor.

Gestisci la versione e la compatibilità dei plugin tramite semantic versioning e il campo required_core_version dentro plugin.json di SqualiOnline. Quando il core rilascia una nuova versione, il sistema blocca l’avvio se il plugin richiede una versione superiore a quella installata. Ad esempio, con core 3.2.0 e required_core_version: '>=3.3.0' l’installazione fallisce con 'Incompatibile core version'. Per evitare rotture, mantieni il requisito il più basso possibile e testa il plugin contro il ramo di sviluppo del core usando squali plugin:ci‑check, che esegue test di regressione su almeno tre versioni precedenti.

Per garantire bassa latenza è preferibile usare gli eventi interni di SqualiOnline piuttosto che i webhook. Gli eventi interni sono dispatchati direttamente nel processo del core con una latenza media di 2 ms nei test di carico, mentre i webhook introducono un overhead di rete medio di 45 ms a causa della serializzazione HTTP e del round‑trip. Se però il plugin deve comunicare con sistemi esterni o servizi fuori dal cluster, allora configura un webhook con payload JSON e timeout di 5 secondi, ma mantieni la logica critica del gestionale negli eventi interni per evitare colli di bottiglia.

Puoi validare i plugin prima del deploy usando PHPUnit o Pest insieme al framework di testing integrato di SqualiOnline, che esegue controlli statici (PSR‑12, security scan) e test dinamici contro un ambiente di staging isolato. Il test runner di SqualiOnline completa oltre 150 verifiche in meno di 8 secondi per un plugin medio di 12 classi, fornendo un report JUnit compatibile con CI come GitHub Actions o GitLab CI. Inoltre, lo squali plugin:lint verifica la presenza di hook non dichiarati e segnala le dipendenze mancanti in composer.json, riducendo il rischio di errori in produzione del 37 % secondo i dati interni di QA.