Changelog

All notable changes to this project will be documented in this file.

[12.13.1] - 2026-10-19 - Chiusura e Riconnessione dell'Adapter MySQL e Validazione dell'ID Generato

Patch che corregge AdapterMysql::close(), mai funzionante, e la riconnessione dopo la chiusura, e che rifiuta gli ID non validi restituiti dal database dopo un inserimento invece di assegnarli all'entità.

🐛 Bug Fix

Orm/Adapters/AdapterMysql::close() — errore a ogni chiusura

close() eseguiva unset(self::$connection), ma PHP non consente l'unset di una proprietà statica: con una connessione aperta il metodo sollevava sempre Error: Attempt to unset static property e la connessione non veniva chiusa. Ora close() azzera la connessione.

Orm/BaseClasses/BaseAdapter::ensureConnected() — nessuna riconnessione dopo close()

La connessione è statica e condivisa da tutti gli adapter, mentre isConnected è una proprietà di ogni singola istanza. Dopo una chiusura isConnected restava true, sia per l'adapter che aveva chiuso sia per gli altri, e ensureConnected() non riapriva la connessione: le query successive restituivano null e le esecuzioni false senza sollevare errori. ensureConnected() verifica ora anche che la connessione condivisa sia aperta, e close() azzera isConnected. Un adapter si riconnette quindi alla prima operazione successiva a una chiusura, anche se la chiusura è stata eseguita da un altro adapter.

Orm/Adapters/AdapterMysql::getLastErrorCode() — TypeError prima della prima operazione

PDO::errorCode() restituisce null se sulla connessione non è ancora stata eseguita alcuna operazione, e il metodo, dichiarato string, sollevava un TypeError. Il caso non si presenta con le connessioni aperte da connect(), che esegue subito SET names, ma con una connessione impostata tramite setConnection(). Il metodo restituisce ora '' in questo caso, e '-1' come stringa in assenza di connessione al posto dell'intero -1, prima convertito implicitamente.

Orm/Adapters/AdapterMysql::lastInsertIdToDelegateAdapter() — ID non validi assegnati all'entità

DataMapper::insert() esclude la chiave primaria dall'INSERT e assegna all'entità l'ID restituito da lastInsertId(), che non veniva verificato:

Il metodo solleva ora un'AdapterException se l'ID non è un intero positivo o se non c'è connessione, come già avviene quando l'INSERT stesso fallisce.

File modificati:

✅ Backward Compatibility

[12.13.0] - 2026-10-19 - Indirizzo IP Configurabile nel Token di Sessione e Letture Senza Effetti Collaterali in Session

Minor release dedicata a Session. L'indirizzo IP può essere escluso dal token anti-dirottamento, per le applicazioni dietro un reverse proxy o con utenti che cambiano rete durante la navigazione, e la lettura di chiavi annidate inesistenti non scrive più nella sessione.

✨ Nuove Funzionalità

Core/HelperClasses/Session — indirizzo IP nel token anti-dirottamento configurabile

Il token anti-dirottamento, verificato da Session::isValidSession(), è l'impronta di User-Agent e indirizzo IP del client. L'indirizzo IP non sempre identifica il client: i dispositivi mobili che cambiano rete e i client dual-stack che passano da IPv4 a IPv6 cambiano indirizzo durante la navigazione, e isValidSession() restituisce false per un utente legittimo; dietro un reverse proxy, un load balancer o una CDN REMOTE_ADDR è invece l'indirizzo del proxy, uguale per tutti gli utenti, e non aggiunge protezione. Con la nuova costante SESSION_TOKEN_INCLUDES_REMOTE_ADDRESS impostata a false l'impronta usa il solo User-Agent. Il default true mantiene il comportamento precedente.

🐛 Bug Fix

Core/HelperClasses/Session::hasItem(), getItem() e unsetItem() — chiavi annidate inesistenti create in sessione

Con una chiave annidata, come cart[items][0], i tre metodi passavano $_SESSION['cart'] per riferimento ai rispettivi metodi ricorsivi, e PHP crea gli elementi inesistenti passati per riferimento: un semplice controllo come Session::hasItem('cart[items][0]') su una sessione vuota restituiva false ma lasciava in sessione ['cart' => ['items' => null]], e un successivo Session::hasItem('cart') restituiva true. I metodi ricorsivi di hasItem() e getItem() ricevono ora i valori per copia e trattano come assente un livello mancante; quello di unsetItem() scende solo nei livelli esistenti.

♻️ Pulizia Codice

Core/HelperClasses/Session — rimossa la proprietà $sessionProperties

La proprietà privata $sessionProperties non veniva mai inizializzata né letta.

📖 Documentazione

docs/configuration-reference.md — nuova costante

Documentata SESSION_TOKEN_INCLUDES_REMOTE_ADDRESS.

docs/security.md — token anti-dirottamento

La sezione sulla sessione precisa che il framework non chiama isValidSession() e quando escludere l'indirizzo IP dall'impronta.

File modificati:

✅ Backward Compatibility

[12.12.0] - 2026-10-18 - Riscrittura della Query String nel Dispatcher e Cache delle Risorse Statiche

Minor release che rivede la riscrittura della query string nel percorso eseguita dal dispatcher. Le richieste diverse da GET e HEAD non vengono più reindirizzate, i parametri di tracciamento restano nella query string, gli array annidati e i valori vuoti sopravvivono alla riscrittura e gli slash multipli in coda non causano più errori. Il rilascio rimuove inoltre gli header di cache pubblica applicati a tutte le risposte e introduce una cache configurabile per le sole risorse statiche.

✨ Nuove Funzionalità

Core/HelperClasses/Dispatcher — parametri preservati nella query string

Per le richieste GET e HEAD il dispatcher riscrive la query string nel percorso con un redirect (/blog?page=2 diventa /blog/page/2/). I parametri elencati nella nuova costante PRESERVED_QUERY_STRING_PARAMETERS restano invece nella query string del redirect (/blog?page=2&utm_source=x diventa /blog/page/2/?utm_source=x), e una richiesta che contiene solo questi parametri non viene reindirizzata. Prima la riscrittura li spostava nel percorso: gli strumenti di analytics e di tracciamento delle conversioni, che li leggono dalla query string lato client, non li ricevevano più, e lo stesso contenuto risultava raggiungibile da un URL diverso per ogni campagna. La lista predefinita comprende i parametri utm_* e gli identificativi di click di Google, Meta, Microsoft e Mailchimp. I parametri restano disponibili in $request->query e come argomenti delle action, con il nome convertito in camelCase (utmSource).

Core/HelperClasses/Dispatcher/ResourceMaker — cache delle risorse statiche configurabile

Le risorse statiche servite dal framework (CSS, JavaScript, immagini, file scaricabili) ricevono ora Cache-Control: public, max-age=… ed Expires con la durata della nuova costante RESOURCE_CACHE_MAX_AGE, e l'header Pragma impostato da session_start() viene rimosso. L'header Expires usava inoltre il formato dei cookie (d-M-Y), non valido per questo header e trattato dai browser come una data già scaduta: ora usa il formato HTTP.

🛡️ Sicurezza

Public/index.php — Cache-Control: public su tutte le risposte

index.php impostava Pragma: cache e Cache-control: public su ogni richiesta, dopo Session::start(), sostituendo gli header anti-cache inviati da session_start(). Un reverse proxy o una CDN potevano quindi mettere in cache e servire ad altri utenti pagine generate con i dati della sessione. Gli header sono stati rimossi: le pagine generate dai controller mantengono gli header anti-cache della sessione, e la cache pubblica è applicata solo alle risorse statiche.

🐛 Bug Fix

Core/HelperClasses/Dispatcher::run() — corpo delle richieste POST perso con la query string

Il redirect della riscrittura veniva eseguito con qualunque metodo: una POST verso un URL con query string (un webhook come /api/webhook?provider=stripe o un form con action contenente parametri) veniva trasformata dal client in una GET e il corpo della richiesta andava perso. La riscrittura è ora eseguita solo per GET e HEAD; per gli altri metodi ActionArgumentsParser legge i parametri direttamente dalla query string e li unisce a quelli del percorso, che hanno la precedenza.

Core/Services/RouterService::reloadWithParsedQueryString() — errore fatale con parametri array

Un parametro array come ?tag[]=php&tag[]=orm veniva passato a urlencode(), che solleva un TypeError. Le liste semplici sono ora riscritte ripetendo la chiave (tag/php/tag/orm/), come già accettato dal parser; gli array associativi e annidati, come ?filter[status]=active&filter[tags][]=php, usano la notazione con parentesi codificata (filter%5Bstatus%5D/active/filter%5Btags%5D%5B%5D/php/), che ActionArgumentsParser ricostruisce con parse_str(). Prima le chiavi degli array associativi venivano perse.

Core/Services/RouterService::reloadWithParsedQueryString() — query string sulla root

Una richiesta alla root con query string, come /?page=2, veniva riscritta in /page/2/ e page veniva interpretato come nome del controller. La root viene ora riscritta nel percorso predefinito (/<DEFAULT_PATH>/<DEFAULT_ACTION>/page/2/).

Core/HelperClasses/Dispatcher/RouteResolver::parsePath() — valore vuoto in coda perso

Un parametro vuoto in fondo alla query string (?page=2&q=) produce un percorso che termina con q//. parsePath() rimuoveva con rtrim() tutti gli slash finali, q restava senza valore e veniva scartato. Viene ora rimosso un solo slash e q riceve il valore ''. injectDefaultController() è stato allineato: non usa più array_pop() per togliere l'action di default iniettata, che con un elemento vuoto in coda avrebbe rimosso quest'ultimo al posto dell'action, e gli argomenti passati ai CallableController sono ripuliti dagli elementi vuoti in coda come in precedenza.

Core/HelperClasses/Dispatcher/ActionArgumentsParser — TypeError con slash multipli in coda

Con più elementi vuoti in coda, come in /home/index///, cleanArrayShift() esauriva gli argomenti e restituiva null da un metodo con tipo di ritorno string, causando un errore 500. Il parser scarta ora gli elementi vuoti prima di ogni coppia chiave/valore e si ferma quando non ne resta una completa.

📖 Documentazione

docs/configuration-reference.md — nuove costanti

Documentate RESOURCE_CACHE_MAX_AGE e PRESERVED_QUERY_STRING_PARAMETERS.

🔧 Manutenzione

.htaccess — rimossa la regola su fbclid

La regola rimuoveva con un redirect 301 l'intera query string di ogni richiesta contenente fbclid, compresi gli altri parametri (?page=2&fbclid=… perdeva page), e impediva al tracciamento di Meta di ricevere l'identificativo di click. fbclid è ora gestito dalla lista dei parametri preservati. InstallationManager copia il .htaccess del framework nei nuovi progetti; nei progetti già installati la regola va rimossa a mano.

File modificati:

✅ Backward Compatibility

[12.11.0] - 2026-10-18 - Vettore d'Inizializzazione per Ogni Proprietà Cifrata

Minor release che rivede la cifratura delle proprietà delle entità. Ogni proprietà cifrata può ora avere un proprio vettore d'inizializzazione, rigenerato a ogni salvataggio, al posto di quello condiviso da tutte le proprietà cifrate della riga, che viene deprecato. Il rilascio corregge inoltre il riuso del vettore condiviso negli update, la perdita dei valori cifrati '' e '0' in lettura e adotta random_bytes() per la generazione dei vettori.

✨ Nuove Funzionalità

Orm/BaseClasses/BaseEntity — vettore d'inizializzazione per proprietà

Una proprietà cifrata usa come vettore d'inizializzazione la proprietà con lo stesso nome seguito dal suffisso InitializationVector (per esempio privateKeyInitializationVector, colonna private_key_initialization_vector), se l'entità la dichiara. A ogni salvataggio della proprietà l'ORM genera un nuovo vettore e lo scrive insieme al valore cifrato: proprietà diverse e versioni successive della stessa proprietà non condividono mai il vettore, e un'entità caricata solo in parte può essere salvata senza rendere illeggibili le proprietà cifrate non caricate.

In lettura il valore viene decifrato con il vettore proprio o, se questo è NULL o assente, con quello condiviso: le righe scritte prima dell'adozione del vettore proprio restano leggibili e vengono ricifrate al primo salvataggio.

🛡️ Sicurezza

Orm/HelperClasses/DataMapper::parseSingleProperty() — vettore d'inizializzazione riusato negli update

Il vettore condiviso veniva generato solo se l'entità non ne aveva già uno: a ogni update le proprietà cifrate venivano ricifrate con lo stesso vettore e la stessa chiave. Con AES-256-CBC questo rivela quando due versioni di un campo iniziano con gli stessi 16 byte; con modalità a flusso come CTR esporrebbe il contenuto. Il vettore viene ora rigenerato a ogni salvataggio. Fa eccezione il vettore condiviso di un'entità caricata solo in parte: se una delle proprietà cifrate che lo usano non è inizializzata, non verrebbe ricifrata e diventerebbe illeggibile, quindi il vettore caricato viene mantenuto, come nelle versioni precedenti. Con il vettore condiviso il rischio resta inoltre tra proprietà diverse della stessa riga, che lo condividono per costruzione: per eliminarlo va adottato il vettore per proprietà, che non ha eccezioni perché ogni vettore viene scritto insieme alla sua proprietà. L'eccezione sarà rimossa nella 13.0.0 insieme al vettore condiviso.

Core/HelperClasses/Encryptor::createInitializationVector() — random_bytes() al posto di openssl_random_pseudo_bytes()

I vettori d'inizializzazione sono ora generati con random_bytes(), il generatore crittograficamente sicuro standard di PHP, che non dipende dall'estensione OpenSSL e solleva un'eccezione se non può produrre byte sicuri. openssl_random_pseudo_bytes() era già sicura dalla PHP 7.4 in poi: si tratta di un rafforzamento, non della correzione di vettori deboli.

🐛 Bug Fix

Orm/BaseClasses/BaseResultSet::convertToBaseEntity() — valori cifrati '' e '0' letti come testo cifrato

Il risultato di Encryptor::decryptString() era scelto con l'operatore ?:, che scarta tutti i valori falsy e non solo il false restituito in caso di errore: una proprietà cifrata con valore '' o '0' veniva idratata con il testo cifrato. Il valore decifrato viene ora scartato solo se è false.

File modificati:

⚠️ Deprecazioni

✅ Backward Compatibility

[12.10.2] - 2026-10-18 - Autoload dei Tipi Nativi e Cache di Reflection nei Punti Rimanenti dell'ORM

Patch che completa la 12.10.0 e la 12.10.1, estendendo il controllo sui tipi nativi e la cache dei metadati di reflection ai punti dell'ORM che non eseguono il controllo per ogni riga, ma per ogni classe di entità o per ogni query.

🚀 Performance

Orm/BaseClasses/BaseEntity, Orm/BaseClasses/BaseAdapter, Orm/ExtendedClasses/DependentModel, Orm/HelperClasses/Cache — autoload dei nomi dei tipi nativi

Come nei punti corretti dalla 12.10.1, questi controlli passavano il nome del tipo di ogni proprietà a is_subclass_of(), e per le proprietà di tipo nativo l'autoloader veniva invocato con nomi come int o string, eseguendo un file_exists() che fallisce sempre. I controlli verificano ora che il tipo non sia nativo prima di confrontarlo con una classe:

Un tipo nativo non può essere un'entità, quindi il risultato dei controlli non cambia.

Orm/HelperClasses/Cache — reflection delle entità ricreata

La costruzione della cache delle foreign key istanziava una \ReflectionClass per ogni entità dei moduli. Usa ora BaseEntity::getFinalClassReflectionProperties(), introdotto nella 12.10.0, filtrando le proprietà protected come prima: le proprietà lette restano le stesse e i metadati sono condivisi con il resto dell'ORM.

File modificati:

✅ Backward Compatibility

[12.10.1] - 2026-10-18 - Autoload Superfluo sui Tipi Nativi delle Proprietà delle Entità

Patch che elimina il principale costo a runtime dell'ORM: per ogni proprietà di tipo nativo (int, string, float, bool) l'idratazione, l'assegnazione, toArray() e il salvataggio di un'entità invocavano l'autoloader con il nome del tipo, e ogni invocazione cercava su disco un file inesistente.

🚀 Performance

Orm/BaseClasses/BaseEntity e Orm/HelperClasses/DataMapper — autoload dei nomi dei tipi nativi

Per capire se una proprietà fosse una foreign key o un tipo custom, l'ORM passava il nome del suo tipo a is_subclass_of() e is_a(..., true). Quando ricevono una stringa, le due funzioni caricano la classe se non è già definita: per i tipi nativi l'autoloader veniva quindi invocato con nomi come int o string. Con l'autoloader del framework ogni invocazione crea un Autoloader ed esegue un file_exists() che fallisce sempre, un esito che PHP non conserva nella sua cache. Per un'entità con 10 colonne scalari, idratata e poi letta, modificata e convertita con toArray(), l'autoloader veniva invocato circa 23 volte per riga.

I controlli verificano ora che il tipo non sia nativo prima di confrontarlo con una classe:

Un tipo nativo non può essere né un'entità né un tipo custom, quindi il risultato dei controlli non cambia.

Misurato con l'autoloader del framework su un'entità con 10 colonne scalari (idratazione, due letture, un'assegnazione e toArray() per riga), il tempo per riga passa da ~570–710 µs a ~37 µs. Il guadagno effettivo dipende dal costo di file_exists() sul filesystem in uso ed è massimo su Windows e su filesystem sincronizzati o di rete.

File modificati:

✅ Backward Compatibility

[12.10.0] - 2026-10-17 - Cache dei Metadati di Reflection delle Entità

Minor release che riduce il costo a runtime dell'ORM: gli oggetti \ReflectionClass e \ReflectionProperty delle entità, finora ricreati a ogni istanziazione, lettura, scrittura, salvataggio e idratazione, sono ora costruiti una sola volta per classe e riutilizzati per tutta la durata della richiesta. La cache è esposta da tre nuovi metodi statici pubblici di BaseEntity, usati da tutte le componenti dell'ORM che leggevano la struttura delle entità.

✨ Nuove Funzionalità

Orm/BaseClasses/BaseEntity — getReflectionClass(), getReflectionProperty() e getFinalClassReflectionProperties()

I tre metodi accettano il nome di una classe di entità o un'istanza (string|BaseEntity) e restituiscono metadati memorizzati in cache statiche indicizzate per classe:

Chiamate successive per la stessa classe restituiscono le stesse istanze, in qualunque ordine i tre metodi vengano invocati.

🚀 Performance

Orm/BaseClasses/BaseEntity — reflection ricreata a ogni istanziazione e a ogni accesso alle proprietà

Il costruttore istanziava una \ReflectionClass e scorreva tutte le proprietà per individuare le foreign key; __get() e __set() (tramite checkFinalClassProperty(), forceForeignKeyPropertySet() e switchSettingType()) creavano una nuova \ReflectionProperty a ogni accesso; toArray() ripeteva la scansione completa delle proprietà. L'elenco delle foreign key è ora calcolato una sola volta per classe e tutti gli accessi usano i metadati in cache. forceForeignKeyPropertySet() legge inoltre la reflection solo quando la proprietà non è valorizzata e ha un indice di foreign key in attesa di risoluzione, invece che a ogni lettura.

Orm/BaseClasses/BaseResultSet, Orm/HelperClasses/DataMapper, Orm/BaseClasses/BaseModel, Orm/BaseClasses/BaseAdapter, Orm/ExtendedClasses/DependentModel — reflection ricreata per ogni riga e per ogni proprietà

L'idratazione dei risultati creava una \ReflectionProperty per ogni colonna di ogni riga, il salvataggio scansionava tutte le proprietà dell'entità a ogni save(), e le query per proprietà e per relazione ricreavano la reflection a ogni chiamata. Tutti questi punti usano ora i metodi di BaseEntity; nell'idratazione il nome della colonna del vettore di inizializzazione è calcolato una volta per riga invece che per ogni colonna.

🐛 Bug Fix

Orm/BaseClasses/BaseResultSet::convertToBaseEntity() — colonna del vettore di inizializzazione assente dal risultato

Per una proprietà cifrata con valore non nullo, l'entità principale leggeva la colonna del vettore di inizializzazione senza verificarne la presenza: se la query non la selezionava, l'accesso sollevava il warning Undefined property su \stdClass. Il controllo isset() già presente nell'idratazione delle entità collegate è ora applicato anche all'entità principale; in assenza del vettore il valore è restituito così com'è.

♻️ Refactoring

Orm/BaseClasses/BaseResultSet::hydrateRelatedEntity() e Orm/ExtendedClasses/ReferencedEntity::toArray() — rimozione della logica duplicata

hydrateRelatedEntity() duplicava convertToBaseEntity() ed è stato rimosso: l'idratazione delle entità collegate usa ora convertToBaseEntity(), che accetta la classe dell'entità come secondo parametro opzionale (?string $entityClass = null, di default il tipo di ritorno del result set). ReferencedEntity::toArray() duplicava BaseEntity::toArray() e ora vi aggiunge soltanto le collezioni.

File modificati:

✅ Backward Compatibility

[12.9.1] - 2026-10-17 - Esclusione di un'Entità nelle Query per Relazione e per Padre

Patch che corregge DependentModel::getOtherEntityCollectionByEntity() e SelfDependentModel::getOtherEntityCollectionByParent(), i metodi che restituiscono le entità collegate alla stessa entità (o allo stesso padre) di un'entità data, esclusa quest'ultima: la query generata faceva riferimento a una colonna inesistente, e il primo dei due metodi perdeva anche il valore dell'entità esclusa e non accettava null.

🐛 Bug Fix

Orm/ExtendedClasses/DependentModel::getOtherEntityCollectionByEntity() e Orm/ExtendedClasses/SelfDependentModel::getOtherEntityCollectionByParent() — condizione di esclusione sulla colonna id_id

La condizione che esclude l'entità passata veniva aggiunta con appendCondition('id', ComparisonOperator::notEqual, Placeholder::placeholder, true). Il quarto parametro indica una foreign key, il cui nome colonna riceve il suffisso Id (NotationManager::convertPropertyNameToColumnName()): la condizione diventava id_id <> ?, su una colonna che nella tabella non esiste, e la query falliva con un errore SQL. La condizione è ora generata sulla colonna id, come in BaseModel::getOtherEntityCollection().

Orm/ExtendedClasses/DependentModel::getOtherEntityCollectionByEntity() — valore dell'entità esclusa perso

Quando $baseEntity era valorizzata, il suo valore e il suo tipo sostituivano gli array $bindValues e $bindTypes invece di esservi aggiunti: la query aveva due placeholder (id <> ? AND ..._id = ?) e un solo valore, con un errore sul numero dei parametri o, a seconda del driver, l'entità di riferimento legata al placeholder dell'esclusione. I due valori sono ora entrambi legati, nell'ordine dei placeholder.

Orm/ExtendedClasses/DependentModel::getOtherEntityCollectionByEntity() — null non accettato

Il metodo prevede un ramo per $baseEntity === null, che genera la condizione ..._id IS NULL, ma il parametro era dichiarato BaseEntity: passare null sollevava un TypeError prima di eseguire il metodo, e il ramo non era raggiungibile. Il parametro è ora ?BaseEntity $baseEntity = null, come $parentEntity in SelfDependentModel::getOtherEntityCollectionByParent().

I test esistenti verificavano solo il numero delle chiamate ad appendCondition(), senza controllarne gli argomenti né i valori passati a DataMapper::find(). Inoltre testGetOtherEntityCollectionByEntityWithNullEntity(), nonostante il nome, passava un'entità invece di null.

File modificati:

✅ Backward Compatibility

[12.9.0] - 2026-10-15 - Valori di Default della Configurazione dal Modulo e Parametri di Sessione e Cifratura con Password in Config

Minor release che risolve alla radice il problema delle costanti di configurazione introdotte dopo l'installazione di un progetto: Config usa ora come valori di default quelli del config.php del modulo SismaFramework, quindi un progetto che aggiorna il framework non deve più aggiungere le nuove costanti al proprio configFramework.php. Su questa base, i parametri di Session e della cifratura con password di Encryptor, che la 12.8.x aveva introdotto come costanti di classe, sono spostati in Config/config.php, come tutti gli altri parametri del framework; l'involucro della cifratura con password passa al formato sisma-pw2, che dichiara tutti i propri parametri.

✨ Nuove Funzionalità

Core/HelperClasses/Config — valori di default dal config.php del modulo

Config/configFramework.php viene copiato da Config/config.php una sola volta, in fase di installazione: le costanti aggiunte al framework dopo l'installazione mancavano nel progetto, e la prima lettura sollevava Error: Undefined constant (vedi la 12.3.0, dove l'aggiunta manuale era documentata come azione richiesta).

Il config.php del modulo dichiara ora le costanti nel namespace SismaFramework\Config, che corrisponde alla sua posizione nel modulo, e l'installazione lo copia in configFramework.php riscrivendo il namespace in Config. Entrambi i file possono quindi essere caricati insieme: Config cerca ogni costante prima in Config\ (il progetto) e, se non la trova, carica il config.php del modulo e la legge da SismaFramework\Config\. Se la costante manca anche lì, l'errore resta Error: Undefined constant. Il file del modulo viene caricato solo quando manca una costante: un progetto con la configurazione completa non lo legge mai.

Il default è il valore calcolato nel file del modulo. Per le costanti scalari (durate, iterazioni, algoritmi) è il valore corretto; una costante derivata da altre costanti o da __DIR__ (path, namespace) avrebbe invece il valore calcolato sulla cartella del modulo e sull'applicazione Sample, e va dichiarata nel progetto.

Core/HelperClasses/Session — durata e rotazione configurabili

La durata e gli attributi del cookie di sessione, il token anti-dirottamento e i parametri della rotazione dell'ID introdotti nella 12.8.2 erano scritti nella classe: per cambiarli bisognava modificare il framework, e l'aggiornamento successivo li riportava al valore originale. Sono ora costanti di configurazione:

Core/HelperClasses/Encryptor — cifratura con password configurabile e involucro sisma-pw2

I parametri della cifratura con password introdotta nella 12.8.0 erano costanti di classe. Sono ora costanti di configurazione:

L'involucro sisma-pw1 dichiarava iterazioni e sale ma non il cifrario, e la decifratura confrontava le lunghezze di IV e tag con valori fissi: con questi parametri configurabili, cambiarne uno avrebbe reso indecifrabili gli involucri esistenti. I nuovi involucri usano quindi il formato sisma-pw2$<cifrario>$pbkdf2-<hash>$<iterazioni>$<sale>$<iv>$<tag>$<dati>: decryptWithPassword() legge cifrario, hash e iterazioni dall'intestazione, IV e tag dai dati, e ricava la lunghezza della chiave dal cifrario. La configurazione decide solo come vengono creati i nuovi involucri, e modificarla non rende indecifrabili quelli esistenti; dalla configurazione vengono letti in decifratura solo i limiti (iterazioni minime e massime, tag minimo), così un involucro alterato non può imporre una derivazione troppo debole o troppo onerosa né indebolire la verifica di integrità troncando il tag. L'intestazione, cifrario compreso, resta autenticata insieme ai dati. Gli involucri sisma-pw1 non sono più supportati: il formato è stato sostituito il giorno dopo l'uscita della 12.8.0, e continuare a leggerlo avrebbe richiesto di conservare nel codice i suoi parametri fissi.

encryptWithPassword() solleva InvalidArgumentException anche se la configurazione indica un hash non supportato da hash_hmac_algos(), un cifrario che non è un cifrario autenticato supportato da OpenSSL (aes-128/192/256-gcm, -ccm, -ocb, chacha20-poly1305) o un tag più corto del minimo.

Anche la lunghezza dei token di getSimpleRandomToken(), prima fissa a 16 byte, è ora la costante SIMPLE_RANDOM_TOKEN_BYTES (16); il metodo accetta ?Config $customConfig = null come gli altri metodi di Encryptor.

Security/HttpClasses/Authentication — token CSRF e campi del form configurabili

I nomi del token CSRF e dei campi da cui Authentication legge le credenziali erano scritti nella classe. Sono ora costanti di configurazione:

Il costruttore accetta un ?Config $customConfig = null opzionale, come le altre classi che leggono la configurazione.

Security/HttpClasses/OAuthAuthentication — chiave di sessione dello state configurabile

La chiave di sessione in cui getAuthorizationUrl() salva lo state anti-CSRF, e da cui checkCallback() lo rilegge, era oauthState, scritta nella classe. È ora la costante di configurazione OAUTH_STATE_KEY (oauthState), e la lunghezza dello state, prima fissa a 16 byte, è OAUTH_STATE_BYTES (16); il costruttore accetta ?Config $customConfig = null come Authentication. I parametri error, code e state della richiesta di callback restano invariati: sono definiti dal protocollo OAuth 2.0.

🛡️ Sicurezza

Security/HttpClasses/Authentication::checkCsrfToken() — confronto del token non a tempo costante

Il token inviato dal form era confrontato con quello in sessione tramite ===, il cui tempo di esecuzione dipende dalla posizione del primo carattere diverso. Il confronto usa ora hash_equals(), come già checkOAuthState() di OAuthAuthentication e Session::isValidSession(). La documentazione di OAuthAuthentication affermava già che i due controlli seguivano lo stesso schema: ora è vero.

♻️ Refactoring

Core/HelperClasses/Session — rotazione dell'ID con nomi espressivi

followRotation() e rotate(), introdotti nella 12.8.2 con due docblock esplicativi, sono sostituiti da followRotationChainOfPresentedId() e rotateIdKeepingPreviousSessionDuringGracePeriod(), scomposti in isCurrentSessionRotated(), isRotationStillFollowable(), replaceWithEmptySession(), markCurrentSessionAsRotatedTo() e switchToSession(). I docblock sono rimossi. Il comportamento non cambia.

📖 Documentazione

docs/configuration-reference.md — esempi di configurazione errati

docs/security.md — algoritmi deboli suggeriti per SIMPLE_HASH_ALGORITHM

L'esempio di configurazione proponeva md5 e sha1 come alternative a sha256. Sono sostituiti da sha384, sha512 e sha3-256, con una nota che sconsiglia gli algoritmi vulnerabili alle collisioni e ricorda di usare getBlowfishHash() per le password.

docs/security.md — esempio del token CSRF salvato nella chiave sbagliata

L'esempio di getSimpleRandomToken() salvava il token CSRF in $_SESSION['csrf_token'], mentre checkCsrfToken() lo cerca in csrfToken: un'applicazione che seguiva l'esempio non superava mai il controllo. L'esempio usa ora Session::setItem('csrfToken', ...). Corretto anche il token d'esempio, lungo 40 caratteri invece di 32.

File modificati:

✅ Backward Compatibility

[12.8.2] - 2026-10-13 - Sessione: Richieste Concorrenti, Cookie su Porte Non Standard, Token Anti-Dirottamento

Patch che corregge tre difetti di Session: la rotazione dell'ID a ogni richiesta disconnetteva l'utente al caricamento di una normale pagina, il cookie di sessione veniva scartato dai browser sulle porte non standard, e il token anti-dirottamento veniva riscritto a ogni richiesta, rendendo isValidSession() sempre vero.

🐛 Bug Fix

Core/HelperClasses/Session::start() — sessione persa con richieste concorrenti

Dalla patch che ha introdotto session_regenerate_id(true), ogni richiesta ruotava l'ID cancellando subito la sessione precedente. Il compromesso era documentato per i casi di tab multipli e chiamate fetch in parallelo, ma riguarda anche il caso più comune: quando fogli di stile e script passano dal front controller, il browser li richiede in parallelo con lo stesso cookie della pagina; la prima richiesta servita ruota l'ID e cancella la sessione, le altre ricevono una sessione vuota e il cookie che il browser conserva è quello dell'ultima risposta arrivata. L'utente risultava disconnesso già al caricamento di una pagina con un foglio di stile e uno script.

La rotazione a ogni richiesta resta, ma con un periodo di grazia, secondo lo schema indicato dal manuale di PHP per session_regenerate_id() e senza un session handler dedicato: rotate() crea il nuovo ID con session_regenerate_id(false), che ne eredita i dati, e marca la vecchia sessione con l'istante della rotazione e il nuovo ID (Session::ROTATED_AT_KEY, Session::NEXT_SESSION_ID_KEY). Una richiesta che si presenta con un ID già ruotato da meno di Session::ROTATION_GRACE_SECONDS (30 secondi) viene agganciata alla sessione corrente, seguendo anche più rotazioni consecutive (followRotation()), e non ruota di nuovo; oltre il periodo di grazia riceve una sessione vuota, come prima. Entrambe le sessioni esistono quando vengono riaperte, quindi la rotazione funziona anche con session.use_strict_mode attivo.

Core/HelperClasses/Session::start() — cookie scartato sulle porte non standard

Il parametro domain del cookie valeva HTTP_HOST, che su una porta diversa da 80 e 443 contiene anche la porta (localhost:8080): un attributo Domain con la porta non è valido e i browser scartavano il cookie, per cui il login non funzionava in sviluppo né in qualunque installazione su porta non standard. Anche senza porta, un Domain esplicito estende il cookie a tutti i sottodomini. domain non viene più impostato: il cookie resta legato all'host esatto che l'ha emesso.

Core/HelperClasses/Session::start() — token anti-dirottamento riscritto a ogni richiesta

start() registrava a ogni richiesta l'impronta di User-Agent e indirizzo IP del client corrente, e isValidSession() la confrontava con l'impronta della stessa richiesta: il confronto era sempre vero e non poteva rilevare una sessione usata da un altro client. Il token viene ora registrato solo alla creazione della sessione.

File modificati:

✅ Backward Compatibility

[12.8.1] - 2026-10-13 - Proprietà Cifrate con Valore Nullo

Patch che permette di salvare e leggere un'entità con una proprietà cifrata facoltativa che vale null: fino alla 12.8.0 entrambe le operazioni sollevavano un TypeError.

🐛 Bug Fix

Orm/HelperClasses/DataMapper::parseSingleProperty() — cifratura di un valore nullo

Al salvataggio, una proprietà dichiarata con addEncryptedProperty() veniva passata a Encryptor::encryptString() qualunque fosse il suo valore. Per una proprietà nullable che vale null (per esempio una chiave privata custodita altrove, quindi assente) la chiamata falliva con TypeError: Encryptor::encryptString(): Argument #1 ($plainText) must be of type string, null given, e l'entità non poteva essere salvata. Un valore null viene ora scritto come NULL senza cifratura; il vettore d'inizializzazione viene generato solo quando c'è effettivamente un valore da cifrare, e resta quello già presente se l'entità ne ha uno.

Orm/BaseClasses/BaseResultSet — decifratura di un valore nullo

Alla lettura, convertToBaseEntity() e hydrateRelatedEntity() (entità caricate con join) chiamavano Encryptor::decryptString() su ogni proprietà cifrata quando la riga aveva un vettore d'inizializzazione, anche se il valore della colonna era NULL: stesso TypeError, sollevato leggendo un'entità che aveva un'altra proprietà cifrata valorizzata. Un valore NULL viene ora restituito come null senza decifratura.

File modificati:

✅ Backward Compatibility

[12.8.0] - 2026-10-13 - Cifratura con Password in Encryptor

Minor release che aggiunge a Encryptor la cifratura simmetrica con una chiave ricavata da una password, indipendente dalla passphrase dell'applicazione. Serve quando un dato conservato sul server deve restare inutilizzabile senza un segreto che conosce solo il suo titolare, per esempio una chiave privata di firma custodita sul server ma sbloccabile solo con il PIN dell'utente.

✨ Nuove Funzionalità

Core/HelperClasses/Encryptor — encryptWithPassword() e decryptWithPassword()

encryptString() usa ENCRYPTION_PASSPHRASE: chiunque controlli il server può decifrare. I due nuovi metodi ricavano invece la chiave dalla password passata dal chiamante:

Il risultato è un involucro autodescrittivo, sisma-pw1$pbkdf2-sha256$<iterazioni>$<sale>$<iv>$<tag>$<dati>, con i campi binari in base64: contiene tutto il necessario per decifrare tranne la password, quindi chi lo usa non deve conservare a parte sale e IV. L'intestazione (versione, algoritmo di derivazione, iterazioni, sale) è passata ad AES-GCM come dato autenticato aggiuntivo: alterare i parametri rende l'involucro indecifrabile invece di indebolirlo. Il limite massimo delle iterazioni impedisce che un involucro manipolato imponga una derivazione arbitrariamente costosa.

I parametri non sono letti da Config ma scritti nell'involucro, per due ragioni: un progetto già installato non riceve le nuove costanti di Config/config.php (vedi la 12.3.0), e con le costanti la prima chiamata solleverebbe Error: Undefined constant; inoltre un involucro deve restare decifrabile anche dopo che il costo di default è stato alzato. Il terzo argomento di encryptWithPassword() permette di scegliere un costo diverso per i nuovi involucri. Le costanti pubbliche PASSWORD_KEY_DERIVATION_DEFAULT_ITERATIONS e PASSWORD_KEY_DERIVATION_MINIMUM_ITERATIONS espongono i valori.

PBKDF2 e AES-GCM usano solo le estensioni hash e openssl, già richieste dal framework: nessuna nuova dipendenza (Argon2id avrebbe richiesto sodium).

File modificati:

✅ Backward Compatibility

[12.7.0] - 2026-10-06 - Query sulle Colonne JSON

Minor release che estende al query builder il supporto alle colonne JSON introdotto con la 12.6.0: condizioni, selezione e ordinamento sui valori contenuti nei documenti, con conversione del tipo dei valori gestita nell'SQL.

✨ Nuove Funzionalità

Orm/HelperClasses/Query — condizioni, selezione e ordinamento su documenti JSON

Con la 12.6.0 una colonna JSON poteva essere letta e scritta, ma non interrogata nel contenuto. Query espone ora sei metodi:

MetodoSQL generato
appendJsonCondition($column, $path, $operator, $value, $jsonValueType)JSON_UNQUOTE(JSON_EXTRACT(col, path)) <operatore> ?, con l'eventuale conversione del tipo
appendJsonContainsCondition($column, $jsonValueType, $value, $path)JSON_CONTAINS(col, <valore>, path)
appendJsonPathExistsCondition($column, $path)JSON_CONTAINS_PATH(col, 'one', path)
appendJsonNullCondition($column, $path)CAST(JSON_TYPE(JSON_EXTRACT(col, path)) AS BINARY) = 'NULL'
setJsonExtractColumn($column, $path, $jsonValueType, $columnAlias, $append)il valore estratto come colonna della SELECT
appendOrderByJsonPath($column, $path, $indexing, $jsonValueType)il valore estratto come criterio di ORDER BY

Le condizioni vanno nel WHERE o nell'HAVING secondo la clausola attiva, come appendCondition(). Le funzioni usate sono disponibili sia in MySQL sia in MariaDB, che non supporta gli operatori -> e ->>, e l'SQL generato è stato verificato su MySQL 8.4 e MariaDB 11.8. In appendJsonNullCondition() il risultato di JSON_TYPE è convertito in BINARY prima del confronto: in MariaDB la sua collation e quella del letterale, derivata dalla connessione, hanno la stessa coercibilità, e il confronto diretto fallisce con l'errore 1267 (Illegal mix of collations). 

$query->setWhere()
    ->appendJsonCondition('attributes', '$.price', ComparisonOperator::greater, Placeholder::placeholder, JsonValueType::decimal)
    ->appendAnd()
    ->appendJsonContainsCondition('attributes', JsonValueType::string, Placeholder::placeholder, '$.tags');
$bindValues = [10.5, 'sale'];
$bindTypes = [DataType::typeDecimal, DataType::typeString];

Il path si passa come stringa, inserita come letterale dopo la validazione contro la grammatica $, .chiave, [indice] (un path non conforme solleva un'AdapterException alla costruzione della query), oppure come Placeholder::placeholder, legato come parametro nella posizione in cui compare nell'SQL, prima del valore del confronto.

Orm/Enumerations/JsonValueType — tipo dei valori nei documenti

Un valore estratto da un documento è testo: un confronto > con un decimale legato come stringa sarebbe lessicografico ('9.5' > '10.5'), e il booleano JSON true estratto è la stringa 'true', diversa dall'1 con cui MySQL rappresenta un booleano SQL. Il nuovo enum (string, integer, decimal, boolean, json) indica il tipo del valore nel documento, e l'adapter genera la conversione nell'SQL: CAST(... AS SIGNED), CAST(... AS DECIMAL(65,30)) e (... = 'true') sul valore estratto, JSON_QUOTE(?), CAST(? AS CHAR) e IF(?, 'true', 'false') sul valore cercato da JSON_CONTAINS. I valori si legano con il DataType naturale, come nelle condizioni sulle colonne ordinarie. JsonValueType::json lascia il valore invariato, per cercare oggetti e array legati come SismaJson; non è ammesso nei confronti di appendJsonCondition(), dove solleva un'AdapterException.

File modificati:

🐛 Bug Fix

Orm/Adapters/AdapterMysql::parseBind() — booleani e array legati come typeJson

DataType::typeJson presuppone un valore già serializzato, SismaJson o stringa JSON, e lo lega come stringa. Un booleano subiva il cast di PHP, per cui true arrivava al database come '1', cioè il numero JSON 1, e false come stringa vuota, che non è JSON valido; un array non era convertibile. Questi valori sollevano ora un'AdapterException che indica il tipo ricevuto.

File modificati:

✅ Backward Compatibility

[12.6.0] - 2026-10-04 - Tipo SismaJson per le Colonne JSON

Minor release che introduce nell'ORM il tipo SismaJson, per mappare le colonne JSON di MySQL e MariaDB su proprietà delle entità decodificate e tracciate dal change tracking come gli altri tipi custom.

✨ Nuove Funzionalità

Orm/CustomTypes/SismaJson — proprietà JSON nelle entità

Finora una colonna JSON poteva essere mappata solo su una proprietà string, lasciando all'applicazione la codifica e la decodifica e facendo rilevare come modifica qualunque differenza testuale, anche solo nell'ordine delle chiavi che MySQL normalizza in fase di salvataggio. Una proprietà tipizzata SismaJson viene ora decodificata in lettura (Parser::parseValue()) e serializzata in scrittura (Parser::unparseValue()), sia nell'ORM sia nel parsing di form e argomenti delle action, che accettano la stringa JSON o un array. 

protected SismaJson $attributes;

$product->attributes = new SismaJson(['color' => 'red']);
$product->attributes = $product->attributes->with('size', 'M');
echo $product->attributes['color'];

SismaJson contiene un oggetto o un array JSON, decodificato in array associativo, e implementa ArrayAccess, IteratorAggregate, Countable e JsonSerializable. È immutabile: with() e without() restituiscono una nuova istanza, mentre l'assegnazione tramite indice solleva una LogicException. Un oggetto mutabile modificato in place non passerebbe da BaseEntity::__set() e la modifica non verrebbe salvata. equals() confronta i documenti ignorando l'ordine delle chiavi degli oggetti ma non quello degli elementi delle liste, con confronto stretto sui tipi.

Orm/Interfaces/CustomTypeInterface — interfaccia per i tipi custom confrontabili

Nuova interfaccia con il metodo equals(self $other): bool, implementata da SismaJson. Il change tracking di BaseEntity usa equals() per le proprietà il cui tipo implementa CustomDateTimeInterface o CustomTypeInterface. CustomDateTimeInterface resta invariata e non estende la nuova interfaccia: renderla figlia di CustomTypeInterface amplierebbe il parametro di equals(), e le implementazioni esistenti che lo dichiarano come CustomDateTimeInterface violerebbero la controvarianza dei parametri, con un fatal error.

DataType::typeJson e FilterType::isJson

File modificati:

⚠️ Limitazioni Note

✅ Backward Compatibility

[12.5.0] - 2026-10-04 - Metodo help() nei Comandi Console e Deprecazione di configure()

Minor release che introduce nei comandi console il metodo help(): string, che restituisce il testo d'aiuto del comando, e depreca configure(): void, che lo stampava. configure() sarà rimosso nella 13.0.0, dove help() diventerà obbligatorio: la release permette di convertire i comandi dei moduli prima dell'aggiornamento.

✨ Nuove Funzionalità

Console/BaseClasses/BaseCommand::help() — testo d'aiuto restituito invece che stampato

Il nome configure() richiamava una fase di preparazione del comando, sul modello di Symfony, ma per convenzione il metodo stampava soltanto il testo d'aiuto, e dalla 12.4.2 viene chiamato esclusivamente con l'opzione --help: un comando che vi inserisse una preparazione vera la vedrebbe eseguita solo con --help e mai durante l'esecuzione normale. Il nuovo metodo help(): string restituisce il testo d'aiuto, e la stampa è a carico di BaseCommand::run().

Prima: 

#[\Override]
protected function configure(): void
{
    $this->output(<<<OUTPUT
Usage: php SismaFramework/Console/sisma report <module>
OUTPUT);
}

Dopo: 

#[\Override]
protected function help(): string
{
    return <<<OUTPUT
Usage: php SismaFramework/Console/sisma report <module>
OUTPUT;
}

Con --help, run() stampa il risultato di help(). Se il comando implementa ancora soltanto configure(), run() chiama configure() come in precedenza e stampa in coda un avviso di deprecazione che indica la classe da convertire. Se il comando implementa entrambi i metodi, viene usato help().

I quattro comandi del framework (fixtures, install, scaffold, upgrade) implementano ora help().

⚠️ Deprecazioni

La conversione va completata prima di aggiornare alla 13.0.0: nella 13 la console carica all'avvio le classi di tutti i comandi dei moduli, e un comando che non implementa help(), o che dichiara configure() con #[\Override], provoca un fatal error che impedisce l'esecuzione di qualunque comando sisma, compreso sisma upgrade.

File modificati:

✅ Backward Compatibility

[12.4.2] - 2026-10-04 - Codice d'Uscita della Console e Testo d'Aiuto Solo su Richiesta

Patch che fa uscire il comando sisma con un codice diverso da zero quando un comando fallisce e che stampa il testo d'aiuto dei comandi solo con l'opzione --help, invece che a ogni esecuzione.

🐛 Bug Fix

Console/sisma — codice d'uscita 0 anche quando il comando falliva

Un comando segnala il fallimento restituendo false da execute(), e il valore risaliva correttamente fino a CommandDispatcher::run(). Lo script sisma, però, ignorava il valore restituito: il processo usciva con codice 1 solo per le eccezioni non catturate, mentre un comando che gestiva l'errore (argomento mancante, opzione non valida, file non scrivibile) terminava con codice 0, come se fosse andato a buon fine. Di conseguenza make, script con set -e, catene con &&, cron e job CI non rilevavano il fallimento. Lo script esce ora con exit($commandDispatcher->run() ? 0 : 1).

Console/BaseClasses/BaseCommand::run() — il testo d'aiuto veniva stampato a ogni esecuzione

run() chiamava sempre configure() prima di execute(). Poiché per convenzione configure() stampa il blocco «Usage / Arguments / Options / Example», il testo d'aiuto compariva anche quando il comando era invocato correttamente e andava a buon fine, sporcando l'output e i log dei comandi eseguiti da cron o da script.

run() si comporta ora così:

Console/HelperClasses/CommandDispatcher — suggerimento d'uso allineato

Il messaggio mostrato quando sisma è invocato senza argomenti indica ora sisma <command> --help per ottenere informazioni su un comando, invece di sisma <command>.

File modificati:

✅ Backward Compatibility

[12.4.1] - 2026-10-03 - Tipografia della Barra di Debug Indipendente dallo Stile della Pagina

Patch che rende la tipografia della barra di debug indipendente dai fogli di stile dell'applicazione, corregge l'apertura dei pannelli al primo click e rimuove dagli asset strutturali due file della barra non più utilizzati.

🐛 Bug Fix

Structural/Templates/debugBar.tpl — la tipografia della barra di debug ereditava lo stile della pagina

Il blocco <style> del template definiva layout e colori della barra, ma nessuna proprietà tipografica: font, dimensione e interlinea erano ereditati dal body della pagina in cui la barra viene iniettata. Di conseguenza l'aspetto della barra cambiava da un'applicazione all'altra, e regole come un font-size elevato o un font decorativo sul body potevano renderla poco leggibile o alterarne l'altezza. Anche il contenuto dei pannelli (<pre>) dipendeva dalle eventuali regole dell'applicazione sui pre.

Il template dichiara ora esplicitamente:

Structural/Templates/debugBar.tpl — il primo click su un'etichetta della barra non apriva il pannello

Lo script del template decideva se mostrare o nascondere il pannello confrontando style.display con 'none'. Al caricamento della pagina, però, il pannello è nascosto dalla regola CSS .debug-bar-body { display: none; } e non da uno stile inline, quindi style.display vale '': il confronto falliva e il primo click impostava display: none su un pannello già nascosto, senza alcun effetto visibile. Il pannello si apriva solo al secondo click. Lo stato viene ora letto con getComputedStyle(), che tiene conto anche delle regole CSS.

♻️ Pulizia Codice

Structural/Assets/ — rimossi css/debugBar.css e javascript/jquery.debugBar.js

I due file erano residui della prima implementazione della barra di debug: stili e comportamento sono da tempo incorporati in debugBar.tpl (con JavaScript nativo, senza dipendenza da jQuery) e nessuna parte del framework li referenziava. DispatcherTest::testStructuralFileFopen() usava debugBar.css come file di esempio per il servizio degli asset strutturali: ora usa svg/logo.svg.

File modificati:

✅ Backward Compatibility

[12.4.0] - 2026-09-27 - Localizzazione Gerarchica dei Template e Label common Facoltative in Localizator

Minor release che estende ai template il meccanismo di localizzazione gerarchica già usato per le viste: le chiavi della sezione templates del file di localizzazione possono ora rispecchiare, a profondità arbitraria, la struttura delle sottocartelle di Templates/, con label common condivise a ogni livello. La chiave piatta con il percorso completo del template, finora l'unica forma supportata per i template in sottocartelle, resta supportata ma è deprecata.

✨ Nuove Funzionalità

Core/HelperClasses/Localizator::getTemplateLocaleArray() — struttura gerarchica e label common per i template

getTemplateLocaleArray() cercava le label del template come chiave letterale all'interno di templates: per un template in una sottocartella (es. emails/welcome, la forma usata nella documentazione) la chiave doveva essere l'intero percorso ("emails/welcome": {...}), senza possibilità di condividere label tra template della stessa cartella. Il metodo segue ora lo stesso algoritmo di getPageLocaleArray(): suddivide il nome del template su /, scende di un livello nella sezione templates per ogni parte e unisce le label common incontrate a ogni livello, con precedenza al livello più specifico. 

"templates": {
    "common": { "signature": "Il team" },
    "emails": {
        "common": { "greeting": "Ciao" },
        "account": {
            "activation": { "subject": "Attiva il tuo account" }
        }
    }
}

Per emails/account/activation vengono restituite signature, greeting e subject.

La logica è estratta nel metodo privato getHierarchicalLocaleArray(), condiviso da getPageLocaleArray() e getTemplateLocaleArray().

🐛 Bug Fix

Core/HelperClasses/Localizator — sezioni e common radice obbligatori

getPageLocaleArray() leggeva $locale['pages']['common'] senza verificarne l'esistenza, e getTemplateLocaleArray() passava $locale['templates'] direttamente ad array_key_exists(): un file di localizzazione privo di pages.common, di pages o di templates produceva un warning seguito da un TypeError. Tutti e tre sono ora facoltativi, e la loro assenza equivale a una sezione vuota.

⚠️ Deprecazioni

📖 Documentazione

docs/internationalization.md — struttura del file di localizzazione allineata al codice

La guida descriveva un file di localizzazione piatto (chiavi direttamente alla radice), non corrispondente alla struttura letta da Localizator (sezioni pages e templates), dichiarava il supporto a file .php (Localizator legge solo file .json) e l'esempio di vista usava una variabile inesistente ($edit_post). Riscritte le sezioni "Come Funziona", "Creare un File di Lingua" e "Utilizzo nelle Viste"; aggiunte le sezioni "Utilizzo nei Template" (con la nota di deprecazione) e "Precedenza tra Label e Variabili".

docs/views.md e docs/conventions.md — estensioni e struttura dei file allineate al codice

docs/views.md indicava per il template di esempio l'estensione .html, mentre Templater cerca file .tpl; aggiunto inoltre un rimando alla localizzazione dei template. docs/conventions.md dichiarava il supporto a file di lingua .php; aggiunta la descrizione della struttura gerarchica di pages e templates.

docs-phpdoc/ — Rigenerazione

Rigenerata tramite composer phpdoc. Localizator è @internal e non compare nella documentazione generata, e le firme pubbliche di Templater sono invariate; la rigenerazione corregge due anomalie preesistenti:

File modificati:

🔧 Manutenzione

PHPUnit aggiornato alla 13.3.5 — recordTestRunHistory non riconosciuto dalla versione installata

In 12.2.0 l'attributo cacheResult di phpunit.xml era stato sostituito con recordTestRunHistory, ma quest'ultimo è stato introdotto solo in PHPUnit 13.3.0 (che contestualmente depreca cacheResult), mentre il vincolo ^13.0 di composer.json e il composer.lock fissavano PHPUnit 13.2.2. La versione installata non riconosceva quindi l'attributo e ogni esecuzione della suite terminava con "OK, but there were issues" per un warning di validazione della configurazione, invece che con un esito pulito.

File modificati:

La suite è verificata con PHPUnit 13.3.5.

✅ Backward Compatibility

[12.3.1] - 2026-09-27 - Correzione Precedenza tra Variabili e Label di Localizzazione in Templater

Patch che allinea Templater::generateTemplate() alla regola di precedenza già applicata al rendering delle view: le variabili passate dal codice applicativo prevalgono sulle label del file di localizzazione con la stessa chiave, e non viceversa.

🐛 Bug Fix

Core/HelperClasses/Templater::generateTemplate() — le label di localizzazione sovrascrivevano le variabili passate dal codice

generateTemplate() combinava le variabili e le label restituite da Localizator::getTemplateLocaleArray() con array_merge($vars, $locale): poiché array_merge() dà precedenza al secondo array, a parità di chiave la label del file di localizzazione sostituiva la variabile passata dal chiamante. Il comportamento era l'opposto di quello di RenderService, che esegue extract() prima sulle label (getPageLocaleArray()) e poi sulle variabili, lasciando l'ultima parola allo sviluppatore. La conseguenza era duplice: non era possibile specializzare una label per un singolo utilizzo del template (es. un oggetto email personalizzato) senza modificare il file di localizzazione, valido per tutti; e l'aggiunta al file di localizzazione di una chiave omonima a una variabile dinamica (es. name, url) ne sostituiva silenziosamente il valore nel template generato.

L'ordine degli argomenti di array_merge() è stato invertito, rendendo le label valori di default sovrascrivibili dalle variabili, come per le view.

Nessun test esistente copriva generateTemplate(): TemplaterTest verificava solo parseTemplate() e l'esistenza dei metodi.

File modificati:

✅ Backward Compatibility

[12.3.0] - 2026-09-09 - Crittografia Asimmetrica Completa in Encryptor (Chiavi, CSR, Certificati, Catena di Fiducia, Cifratura a Busta)

Minor release che estende Encryptor — finora limitato ad hash e cifratura simmetrica — con un set completo di primitive di crittografia asimmetrica: coppie di chiavi, richieste di firma certificato, certificati self-signed o firmati da CA (con controllo esplicito dell'estensione X.509v3 basicConstraints), verifica della catena di fiducia, firma/verifica di dati e cifratura a busta (envelope encryption). Le nuove funzioni sono generiche e riusabili da qualunque progetto basato sul framework, non legate a un caso d'uso applicativo specifico — non è stata rilasciata una prima versione ridotta (solo self-signed) perché, trattandosi di codice di libreria condiviso e non di un caso d'uso applicativo puntuale, un set di primitive incompleto (mancava, ad esempio, il corrispettivo di "firma" per la sola verifica del certificato, o l'analogo asimmetrico di encryptString()) avrebbe significato lasciare un lavoro a metà.

✨ Nuove Funzionalità

Core/HelperClasses/Encryptor — dieci nuovi metodi per crittografia asimmetrica reale (OpenSSL)

Aggiunti dieci metodi statici, nello stesso stile di quelli già esistenti (?Config $customConfig = null come ultimo parametro):

Chiavi e certificati:

Verifica:

Cifratura a busta:

Configurazione OpenSSL autosufficiente — nessun openssl.cnf di sistema richiesto

generateAsymmetricKeyPair(), generateCertificateSigningRequest(), generateSelfSignedCertificate() e signCertificateSigningRequest() passano tutte alle funzioni OpenSSL sottostanti l'opzione config, risolta da resolveOpensslConfigPath(): se Config::opensslConfigPath non è valorizzata, viene generato — una sola volta per processo, tramite tempnam(), ripulito a fine richiesta con register_shutdown_function() — un file di configurazione OpenSSL minimale (costante privata Encryptor::MINIMAL_OPENSSL_CONFIG) contenente le sezioni [req]/[req_distinguished_name] necessarie alle operazioni di base e le sezioni [v3_ca]/[v3_leaf] (rispettivamente basicConstraints critical,CA:TRUE/CA:FALSE) usate da generateSelfSignedCertificate()/signCertificateSigningRequest() per l'estensione X.509v3. Questo elimina la dipendenza da un openssl.cnf di sistema risolvibile automaticamente (assente per default su alcune installazioni PHP su Windows, dove altrimenti openssl_pkey_new()/openssl_csr_new()/openssl_csr_sign() falliscono silenziosamente ritornando false) — OPENSSL_CONFIG_PATH resta disponibile come override esplicito solo per esigenze avanzate (es. un provider/engine OpenSSL specifico).

Nuove proprietà di Config/costanti di Config/config.php (sezione "Encryptor Constants"):

CostanteProprietà ConfigTipoDefault
ASYMMETRIC_KEY_TYPEasymmetricKeyTypeintOPENSSL_KEYTYPE_RSA
ASYMMETRIC_KEY_BITSasymmetricKeyBitsint2048
ASYMMETRIC_DIGEST_ALGORITHMasymmetricDigestAlgorithmstring"sha256"
CERTIFICATE_VALIDITY_DAYScertificateValidityDaysint3650
OPENSSL_CONFIG_PATHopensslConfigPathstring"" (via getenv('OPENSSL_CONFIG_PATH'))

File modificati:

✅ Backward Compatibility

[12.2.1] - 2026-09-08 - Correzione Rilevamento Foreign Key Null in buildPropertiesConditions()

Patch che corregge un difetto di DependentModel::buildPropertiesConditions(), il metodo che traduce le proprietà passate ai finder magici generati dal framework (findByProperties(), le varianti countBy...()/deleteBy...() generate da __callStatic/__call, ecc.) in condizioni SQL: per una proprietà foreign key (dichiarata come sottoclasse di ReferencedEntity) valorizzata con null, il metodo generava una condizione sulla colonna sbagliata, priva del suffisso Id richiesto dalla convenzione di naming dell'ORM.

🐛 Bug Fix

Orm/ExtendedClasses/DependentModel::buildPropertiesConditions() — ricerca per foreign key null risolta sulla colonna sbagliata

Il quarto parametro di Query::appendCondition() (bool $foreignKey) indica all'adapter se il nome colonna va risolto con il suffisso Id (NotationManager::convertPropertyNameToColumnName($name, true), es. relatedEntity → related_entity_id) invece che come proprietà scalare (relatedEntity → related_entity). buildPropertiesConditions() determinava questo flag con $propertyValue instanceof ReferencedEntity — un controllo sul valore a runtime, non sul tipo dichiarato della proprietà. Per qualunque proprietà foreign key interrogata con valore null (il caso d'uso esplicito di una ricerca "dove la relazione è assente"), null instanceof ReferencedEntity è sempre false, indipendentemente dal tipo dichiarato della proprietà sull'entità: il metodo trattava quindi la colonna come se fosse scalare, generando una condizione WHERE related_entity IS NULL invece di WHERE related_entity_id IS NULL — una colonna che nella tabella non esiste, con conseguente errore SQL a runtime per qualunque ricerca su una foreign key nullable valorizzata a null.

buildPropertiesConditions() determina ora se una proprietà è una foreign key leggendo il tipo dichiarato tramite ReflectionProperty::getType() e is_subclass_of(..., ReferencedEntity::class), indipendentemente dal valore effettivo — corretto sia per il ramo null che per quello non-null, ed eliminando la necessità di istanziare una seconda volta ReflectionProperty nel ramo non-null (già usata per calcolare $bindTypes).

Nessun test esistente copriva questo percorso: gli unici test che invocano un finder con valore null su una proprietà foreign key (testMagicMethodCountByNullableEntityWithNullValue, testMagicMethodCountByMultiplePropertiesWithNullValues) verificano solo che appendCondition() venga chiamato, senza asserire il valore del quarto parametro.

File modificati:

✅ Backward Compatibility

[12.2.0] - 2026-09-05 - Rinominazione API di Localizator, Correzione TypeError e Nuovo Metodo getEnumerationLocaleAttribute()

Minor release che rinomina due metodi pubblici di Localizator i cui nomi non riflettevano più il tipo di ritorno effettivo (e, nel caso di getComposedEnumerationLocale(), erano diventati troppo simili al metodo privato sottostante), corregge un bug introdotto in 12.1.0, e aggiunge un nuovo metodo per leggere un singolo attributo da un valore di localizzazione composto.

♻️ Refactoring

Core/HelperClasses/Localizator — Rinominati getEnumerationLocaleArray() e getComposedEnumerationLocaleArray()

Entrambi i nomi risalivano a un paradigma precedente (commit 20eb7a15, dic 2024) in cui il primo metodo restituiva davvero un array; da allora restituisce una singola stringa (la label), ma il nome non era mai stato aggiornato. Con l'introduzione in 12.1.0 di un secondo metodo per il valore composto, la coppia di nomi (getEnumerationLocaleArray() → stringa, getComposedEnumerationLocaleArray() → array) era diventata fuorviante. Rinominati per riflettere il tipo di ritorno effettivo:

Il secondo nome evita deliberatamente la parola "Field/Fields": il metodo privato sottostante, getEnumerationLocaleField(), esegue il lookup grezzo (string|array) per un case dell'enum, mentre il metodo pubblico pretende e garantisce la forma composta (array). Chiamarlo getEnumerationLocaleFields() — come nome scelto in un primo momento — li rendeva praticamente indistinguibili a colpo d'occhio pur avendo contratti diversi (uno può restituire una stringa, l'altro lancia un'eccezione se non trova un array).

File modificati:

🐛 Bug Fix

Core/HelperClasses/Localizator::getEnumerationLocaleLabel() — TypeError quando il valore di localizzazione dell'enum è un array

Da quando, in 12.1.0, getEnumerationLocaleField() è diventato string|array per supportare le chiavi di localizzazione composte, questo metodo (allora getEnumerationLocaleArray()) — dichiarato : string — continuava a restituire il valore così com'era. Se il case dell'enum ha un valore locale composto (es. {"label": "...", "description": "..."}), la chiamata sollevava TypeError: Return value must be of type string, array returned.

Il metodo ora verifica il tipo del valore restituito da getEnumerationLocaleField() e, se è un array, estrae la chiave 'label'.

File modificati:

Core/HelperClasses/Localizator::getComposedEnumerationLocale() — Errore nativo poco chiaro quando l'enum non ha un valore locale composto

Stesso difetto del punto precedente, presente fin dall'introduzione del metodo in 12.1.0 (allora getComposedEnumerationLocaleArray()): dichiarato : array, restituiva getEnumerationLocaleField() senza verificarne il tipo. Se il case dell'enum ha un valore locale semplice (stringa), la chiamata sollevava un TypeError a carico del tipo di ritorno.

Il metodo ora verifica il tipo del valore restituito da getEnumerationLocaleField() e, se non è un array, solleva una LocalizatorException esplicita — già prevista nel framework (Core/Exceptions/LocalizatorException.php) ma finora mai utilizzata — invece del TypeError/"illegal string offset" nativo di PHP.

File modificati:

✨ Nuove Funzionalità

Core/HelperClasses/Localizator::getEnumerationLocaleAttribute() — Lettura di un singolo attributo da un valore di localizzazione composto

Aggiunto un nuovo metodo pubblico che, dato un enum e il nome di un attributo, restituisce direttamente il valore di quell'attributo dal campo di localizzazione composto, senza dover passare per getComposedEnumerationLocale() e indicizzare manualmente l'array risultante. Internamente delega a getComposedEnumerationLocale(), ereditandone la LocalizatorException quando l'enum non ha un valore locale composto.

Il tipo di ritorno è string|array e non mixed: i file di locale sono file di linguaggio, il cui unico scopo è contenere testo (eventualmente organizzato in strutture annidate, come si vede in Aurunci/Application/Locales/it_IT.json con voci a più livelli, es. nobleQualification.don.male.label); un numero o un booleano al loro interno sarebbe un errore di contenuto, non un caso d'uso legittimo da rappresentare nel tipo. Poiché il framework non dichiara strict_types da nessuna parte, un simile errore verrebbe comunque coercito silenziosamente a stringa da PHP anziché sollevare un TypeError; il vantaggio pratico del tipo esplicito è invece sul lookup di una chiave $attribute inesistente, che con string|array (non nullable) fallisce subito con un TypeError invece di propagarsi silenziosamente come null.

File modificati:

📖 Documentazione

docs-phpdoc/ — Rigenerazione completa

Localizator è marcata @internal, quindi phpDocumentor non genera per essa (né per le altre classi @internal del framework) una pagina pubblica: le modifiche di questa release non compaiono nella documentazione generata. La rigenerazione ha comunque aggiornato 14 pagine rimaste indietro rispetto a modifiche di release precedenti mai propagate alla documentazione (es. Session per la 12.1.1, MultipleSelfReferencedEnumeration per la 12.1.2).

🔧 Manutenzione

phpunit.xml — Sostituito l'attributo deprecato cacheResult

PHPUnit 13 segnala cacheResult come deprecato e ne annuncia la rimozione in PHPUnit 14 (vendor/phpunit/phpunit/src/TextUI/Configuration/Xml/Loader.php), in favore di recordTestRunHistory (stesso significato, nuovo nome). Sostituito nell'attributo radice <phpunit>.

File modificati:

✅ Backward Compatibility

[12.1.2] - 2026-09-05 - Correzione Import Mancante in MultipleSelfReferencedEnumeration

Patch che corregge un fatal error latente nel trait MultipleSelfReferencedEnumeration: il metodo getChoiceByMultipleParent() dichiara il parametro Language $language, ma il file non importava la classe SismaFramework\Core\Enumerations\Language.

🐛 Bug Fix

Core/Traits/MultipleSelfReferencedEnumeration::getChoiceByMultipleParent() — Language referenziata senza use, fatal error a runtime

Il parametro Language $language viene risolto da PHP, in assenza di un use esplicito, nel namespace corrente del file (SismaFramework\Core\Traits). Poiché la classe Language vive in SismaFramework\Core\Enumerations, qualsiasi enum concreto che utilizza il trait e invoca getChoiceByMultipleParent() solleva un Error: Class "SismaFramework\Core\Traits\Language" not found. Il difetto era presente fin dall'introduzione della firma tipizzata del metodo e non è mai emerso perché nessun test in Tests/ esercita questo trait.

Aggiunta la dichiarazione use SismaFramework\Core\Enumerations\Language; in testa al file.

File modificati:

✅ Backward Compatibility

[12.1.1] - 2026-08-27 - Correzione Bug in appendItem() e Rafforzamento della Sicurezza delle Sessioni

Patch che raggruppa un insieme di correzioni alla classe Session, emerse da una revisione mirata della gestione delle sessioni nel framework: un bug di ricorsione in appendItem() che ne vanificava silenziosamente il comportamento sulle chiavi annidate a più livelli, un disallineamento tra la durata del cookie di sessione e quella dei dati lato server, un confronto non timing-safe del token anti-hijacking, e una rotazione dell'ID di sessione ad ogni richiesta che non invalidava mai realmente l'ID precedente.

🐛 Bug Fix

Core/HelperClasses/Session::appendItemRecursive() — l'append su chiavi annidate a più livelli degradava silenziosamente a un overwrite

Per una chiave con un solo livello di annidamento (es. test[one]), appendItem() funziona correttamente: verifica se il valore è già presente nell'array di destinazione e, in caso contrario, lo accoda. Per una chiave con due o più livelli (es. test[one][two]), il ramo ricorsivo di appendItemRecursive() richiamava però setItemRecursive() invece di se stesso: il risultato, per qualunque profondità superiore a uno, era che il valore più profondo veniva sovrascritto come farebbe setItem() — perdendo l'array esistente, il controllo dei duplicati e la semantica di append che il metodo promette dalla sua firma. L'unico test esistente per l'append su chiavi annidate copriva un solo livello di profondità, motivo per cui il difetto è rimasto silente.

appendItemRecursive() richiama ora se stessa nel ramo ricorsivo, esattamente come già fanno setItemRecursive(), unsetItemRecursive(), getItemRecursive() e hasItemRecursive().

File modificati:

Core/HelperClasses/Session::start() — la sessione lato server poteva scadere prima del cookie del client

Il cookie di sessione viene emesso con lifetime: 3600 (un'ora), ma nessun punto del framework allineava session.gc_maxlifetime — il parametro PHP che determina quando i dati di sessione diventano eleggibili per la garbage collection — a quello stesso valore. Con l'ini di default di molte distribuzioni (tipicamente 1440 secondi, 24 minuti), i dati di sessione potevano essere ripuliti dal server ben prima della scadenza dichiarata al client: l'utente restava con un cookie ancora "valido" ma privo di sessione corrispondente, con un logout inatteso e difficile da riprodurre perché dipendente dalla configurazione dell'hosting.

start() imposta ora esplicitamente ini_set('session.gc_maxlifetime', 3600), in modo che la vita dei dati lato server sia sempre coerente con quella del cookie, indipendentemente dalla configurazione di php.ini dell'ambiente di destinazione.

File modificati:

🛡️ Sicurezza

Core/HelperClasses/Session::isValidSession() — confronto del token incoerente rispetto a start() e non timing-safe

start() calcola il token anti-hijacking con ($request->server['HTTP_USER_AGENT'] ?? null) . ($request->server['REMOTE_ADDR'] ?? null), tollerando l'assenza di uno dei due header. isValidSession() eseguiva lo stesso calcolo senza l'operatore di null coalescing, sollevando un warning "Undefined array key" nei contesti in cui uno dei due valori non è presente (client senza User-Agent, proxy che lo rimuovono, ambienti di test). Il confronto finale tra token atteso e token calcolato, inoltre, usava === anzichè un confronto a tempo costante, esponendo — sebbene in modo marginale, trattandosi di un hash SHA-512 non direttamente controllabile da un attaccante — a un timing attack in stile OWASP su una funzione dedicata proprio a rilevare sessioni dirottate.

isValidSession() è ora allineato a start() sull'uso di ?? null, e il confronto finale utilizza hash_equals() invece di ===.

File modificati:

Core/HelperClasses/Session::start() — l'ID di sessione precedente restava valido dopo la rotazione

start() viene invocato dal front controller (Public/index.php) ad ogni richiesta, e rigenera sempre l'ID di sessione tramite session_regenerate_id(). Chiamato senza l'argomento delete_old_session, però, il vecchio ID non viene invalidato: resta pienamente utilizzabile fino a quando non interviene la garbage collection di PHP (probabilistica, e ora fino a un'ora di distanza per effetto dell'allineamento di gc_maxlifetime sopra descritto). La rotazione ad ogni richiesta è una difesa in profondità riconosciuta contro il furto di sessione — riduce la finestra in cui un ID sottratto resta utile — ma senza l'invalidazione immediata del vecchio ID quel beneficio non si realizzava: l'ID rubato restava valido esattamente quanto se la rotazione non fosse mai avvenuta.

start() chiama ora session_regenerate_id(true), invalidando immediatamente l'ID precedente ad ogni rotazione.

File modificati:

🚀 Performance

Core/HelperClasses/Session — preg_match_all() eseguito anche per chiavi semplici senza annidamento

setItem(), getItem(), appendItem(), unsetItem() e hasItem() eseguivano incondizionatamente preg_match_all("/\\[([^\\]]*)\\]/", $key, $matches) per rilevare la sintassi di chiave annidata (foo[bar][baz]), anche quando la chiave passata era una semplice stringa priva di parentesi quadre — il caso di gran lunga più comune nell'uso tipico della classe.

Ciascuno dei cinque metodi esegue ora preg_match_all() solo se la chiave contiene effettivamente [, evitando il costo della regex nel percorso comune.

File modificati:

✅ Backward Compatibility

[12.1.0] - 2026-08-11 - Supporto Chiavi Enum Composte in Localizator

Minor release che estende Localizator con un nuovo metodo dedicato alla lettura di valori di localizzazione strutturati (array) per i case degli enum, mantenendo getEnumerationLocaleArray() invariato per l'uso corrente (label singola come stringa).

✨ Nuove Funzionalità

Core\HelperClasses\Localizator::getComposedEnumerationLocaleArray() — Lettura di chiavi di localizzazione composte per enum

Introdotto un nuovo metodo pubblico per leggere, per un case di enum, un valore di localizzazione strutturato come array (es. {"label": "...", "description": "..."}), accanto al metodo esistente getEnumerationLocaleArray() che continua a restituire una singola stringa.

Motivazione: getEnumerationLocaleArray() è tipizzato string ed è usato da SelectableEnumeration::getFriendlyLabel() per costruire le choice delle select — un ritorno string|array avrebbe costretto ogni chiamante a discriminare il tipo. Un metodo dedicato, sempre array, evita questo problema e resta esplicito su cosa aspettarsi.

Implementazione:

File modificati:

🧪 Test

Tests\Core\HelperClasses\LocalizatorTest — Copertura nuovo metodo

Aggiunto testGetComposedEnumerationLocaleArrayMethodExists(), sullo stesso modello del test esistente per getEnumerationLocaleArray().

✅ Backward Compatibility

[12.0.9] - 2026-08-11 - Correzione Firma getParent() in SelfReferencedEnumeration

Patch che corregge il contratto del trait SelfReferencedEnumeration, il cui metodo astratto getParent() era dichiarato con tipo di ritorno non nullable (self), impedendo di rappresentare correttamente la radice di una gerarchia di case enum.

🐛 Bug Fix

Core/Traits/SelfReferencedEnumeration::getParent() — impossibile rappresentare l'assenza di un padre

Un enum che implementa il trait per modellare una struttura gerarchica (analoga a una tabella auto-referenziata) ha sempre almeno un case radice privo di padre. Con getParent(): self, quel case è costretto a restituire un valore fittizio — tipicamente se stesso o un altro case a caso — perché il tipo di ritorno non ammette null. Il problema è lo stesso, concettualmente, di una foreign key auto-referenziata dichiarata NOT NULL.

Il metodo astratto è ora dichiarato getParent(): ?self, permettendo alle implementazioni di restituire null per il case radice.

File modificati:

✅ Backward Compatibility

[12.0.8] - 2026-08-05 - Ripristino della Propagazione dell'Istanza Debugger Condivisa

Patch che corregge un difetto architetturale introdotto con la conversione di Debugger da classe statica a classe di istanza (11.0.0), per cui la maggior parte dei punti che dipendono da Debugger — BaseForm, BaseController, Dispatcher, ControllerFactory, RenderService::generateView() e BaseAdapter — riceveva silenziosamente un'istanza nuova e isolata (tramite il valore di default new Debugger()) invece dell'istanza effettivamente in uso per la richiesta corrente (creata in Public/index.php e propagata tramite Dispatcher/ControllerFactory fino al controller).

🐛 Bug Fix

Core/HelperClasses/Debugger — nessun punto di accesso condiviso all'istanza della richiesta corrente

Ogni classe che dipende da Debugger lo riceve come parametro di costruttore/metodo con valore di default new Debugger() (reso possibile dal supporto di PHP 8.1 a new negli inizializzatori). Quando il chiamante omette il parametro — la norma, non l'eccezione, in tutto il codice applicativo esistente: nessun esempio in Sample/, TestsApplication/, nei template di scaffolding o nella documentazione passa esplicitamente l'istanza corretta a RenderService::generateView() — ciascuna di queste classi finisce con una propria istanza isolata. BaseController riceve correttamente l'istanza condivisa tramite ControllerFactory (che la inietta esplicitamente via reflection), ma quell'istanza non arriva mai a RenderService::generateView() (dove la debug bar viene effettivamente generata), né a BaseAdapter/DataMapper (dove vengono conteggiate le query eseguite), né a BaseForm (dove isValid() chiama setFormFilter()), perché nessuno di questi punti la passa esplicitamente. L'effetto pratico, mai notato perché silenzioso: la debug bar non ha mai mostrato dati reali in nessuno scenario realistico.

Debugger espone ora getInstance()/setInstance()/resetInstance(), sul modello già in uso in Config e RenderService. I punti di wiring elencati sotto sostituiscono il parametro Debugger $debugger = new Debugger() con ?Debugger $debugger = null e delegano il fallback a Debugger::getInstance() nel corpo del metodo — necessario perché PHP consente new ma non chiamate a metodi statici arbitrari come valore di default di un parametro. La dependency injection resta intatta: chi passa già un'istanza esplicita (o un mock, nei test) continua a poterlo fare esattamente come prima.

File modificati:

✅ Backward Compatibility

[12.0.7] - 2026-08-01 - Correzione Gestione Valori Non Stringa in Filter::customFilter()

Patch che corregge un difetto di Filter::customFilter(), l'unico metodo della classe Filter che passava il valore da validare direttamente a una funzione nativa di stringa (preg_match()) senza verificarne preventivamente il tipo, a differenza di tutti gli altri metodi (isString(), isEmail(), isSecurePassword(), ecc.) che già gestiscono in modo uniforme i valori non stringa restituendo false.

🐛 Bug Fix

Core/HelperClasses/Filter::customFilter() — valori non stringa passati direttamente a preg_match()

customFilter() dichiara $value come mixed ma lo passa senza controlli al parametro $subject di preg_match(), tipizzato internamente come string non nullable. Quando questo filtro viene collegato tramite FilterType::customFilter a un campo opzionale di un BaseForm (ad esempio uno slug che rispetta un pattern di caratteri consentiti), FormValidator valorizza il dato a validare con null per un campo lasciato vuoto e lo passa comunque al filtro: preg_match() riceve quindi direttamente null, che PHP 8.1+ segnala come deprecato e può risultare in un comportamento non controllato, invece del fallimento di validazione pulito (false) che ci si aspetterebbe in analogia con gli altri metodi della classe.

customFilter() ora verifica esplicitamente is_string($value) prima di invocare preg_match(), e confronta l'esito con === 1 invece di affidarsi alla conversione implicita int→bool del valore restituito da preg_match() (che vale anche false in caso di espressione regolare non valida). Qualunque valore non stringa, incluso null, produce ora un fallimento di validazione esplicito e coerente con il resto della classe.

File modificati:

✅ Backward Compatibility

[12.0.6] - 2026-07-23 - Correzione Corruzione Slug Numerici nel Dispatch verso CallableController

Patch che corregge un difetto nell'inoltro delle richieste verso i controller che implementano CallableController (routing dinamico via __call()), per cui la porzione di slug numerica-con-trattini di un URL veniva irrimediabilmente corrotta prima di raggiungere il metodo magico del controller.

🐛 Bug Fix

Core/HelperClasses/Dispatcher::executeCallableController() — slug con parti numeriche separate da trattino decodificati in modo errato

executeCallableController() invocava sempre il controller usando parsedAction, la versione dello slug convertita in camelCase da NotationManager::convertToCamelCase() (pensata per i nomi di metodo reali, non per i segmenti di uno slug arbitrario). Per uno slug come slug-with-2000-01-01-day, la conversione produce slugWith20000101Day: i trattini tra cifre vengono rimossi senza lasciare alcun separatore, rendendo impossibile ricostruire a valle il valore originale (2000-01-01 diventa indistinguibile da 20000101). Poiché il controller non definisce un metodo reale con quel nome, la chiamata ricadeva su __call(), che riceveva quindi il nome già corrotto.

executeCallableController() ora chiama il controller con parsedAction solo se corrisponde a un metodo realmente definito sulla classe (ReflectionClass::hasMethod()); altrimenti utilizza pathAction, il segmento di URL originale, non trasformato — lo stesso valore già usato da isCallableController() per la verifica di compatibilità tramite checkCompatibility(), ripristinando la coerenza tra i due controlli.

File modificati:

✅ Backward Compatibility

[12.0.5] - 2026-07-17 - Correzione Permessi Cache/Logs/filesystemMedia Mai Applicati in Installazione

Patch che corregge un difetto della procedura di installazione (sisma install) per cui le cartelle scrivibili a runtime (Cache, Logs, filesystemMedia) non ricevevano mai i permessi di scrittura previsti dal codice, lasciando l'applicazione priva di accesso in scrittura subito dopo l'installazione.

🐛 Bug Fix

Console/Services/Installation/InstallationManager — permessi 0777 su Cache, Logs, filesystemMedia mai applicati

install() chiama createProjectStructure(), che creava già tutte e cinque le cartelle previste (Config, Public, Cache, Logs, filesystemMedia) con mkdir(..., 0755, true). La successiva chiamata a createAdditionalFolders() — pensata apposta per portare Cache, Logs e filesystemMedia a 0777, le uniche tre che l'applicazione deve poter scrivere a runtime, a differenza di Config e Public — eseguiva mkdir()/chmod() solo if (!is_dir($path)): condizione sempre falsa, perché le tre cartelle esistevano già per effetto di createProjectStructure(). Il blocco pensato per garantire la scrittura era quindi sempre inattivo, codice morto fin dalla sua introduzione.

L'effetto pratico: subito dopo l'installazione, Cache/Logs/filesystemMedia restavano a 0755, di proprietà dell'utente che ha eseguito sisma install — tipicamente diverso dall'utente sotto cui gira il server web — impedendo a quest'ultimo di scrivere cache, log e media fino a un eventuale intervento correttivo esterno alla procedura di installazione stessa.

createProjectStructure() ora crea solo Config e Public; la creazione di Cache, Logs e filesystemMedia resta di esclusiva competenza di createAdditionalFolders(), che a questo punto le trova sempre assenti ed esegue realmente mkdir(0777, true) + chmod(0777).

File modificati:

✅ Backward Compatibility

[12.0.4] - 2026-07-14 - Buffer-Involucro per il Recovery degli Errori Residui in Sviluppo

Patch che completa la correzione avviata in 12.0.3. La guardia headers_sent() introdotta in quella release per evitare la cascata di pagine d'errore duplicate in produzione impediva, come effetto collaterale non voluto, anche la visualizzazione della pagina di dettaglio per i warning residui in ambiente di sviluppo: da quando RenderService scarica realmente l'output a fine rendering (12.0.2), all'avvio della shutdown function registrata da registerNonThrowableErrorHandler() (che PHP esegue solo alla terminazione effettiva dello script) gli header risultavano ormai quasi sempre già inviati per qualunque richiesta completata con successo, facendo uscire la guardia prima ancora di controllare l'ambiente. Il risultato era la contraddizione esplicitamente esclusa dal changelog 12.0.3: un warning residuo, anche in sviluppo, non generava più visibleError.

🐛 Bug Fix

Core/HelperClasses/ErrorHandler::registerNonThrowableErrorHandler() — warning residui non mostravano più la pagina di dettaglio in sviluppo

La causa non era l'ordine dei controlli nella shutdown function, ma il fatto che il contenuto della risposta fosse già stato scaricato per davvero (quindi irrecuperabile) ben prima che la shutdown function avesse la possibilità di intervenire. PHP mantiene invece aperti i buffer di output durante l'esecuzione delle shutdown function, scaricandoli automaticamente solo al termine di tutte — la stessa proprietà su cui si basava implicitamente il comportamento (corretto) precedente alla chiusura esplicita del buffer introdotta in 12.0.2.

registerNonThrowableErrorHandler() apre ora un buffer-involucro (ob_start() grezzo, non tracciato da BufferManager) non appena viene invocato, prima ancora di registrare la shutdown function: essendo aperto fuori dal livello base tracciato da BufferManager, i normali cicli start()/flush() di RenderService — inclusi quelli innescati da rendering completati con successo — vi trasferiscono il contenuto senza mai scaricarlo realmente all'esterno, lasciandolo recuperabile fino alla reale terminazione dello script. Quando la shutdown function deve sostituire integralmente la risposta (sempre in sviluppo; solo per errori realmente fatali in produzione, dopo la consueta verifica headers_sent()), il nuovo metodo BufferManager::discardAll() scarta anche questo involucro — cosa che il precedente clear(), vincolato a non retrocedere sotto il livello base per non toccare buffer esterni al framework, non poteva fare — e resetta il livello base, cosicché il rendering della pagina d'errore che segue venga effettivamente consegnato come unico output della richiesta.

File modificati:

Core/HelperClasses/Dispatcher::run() — warning di deprecazione residuo su QUERY_STRING assente

Portato alla luce testando la correzione precedente: strlen($this->request->server['QUERY_STRING']) generava un warning di deprecazione (strlen(): Passing null...) ogni volta che la richiesta non aveva query string e la chiave non risultava valorizzata nell'array $_SERVER (caso riscontrato con il server PHP integrato). Il warning, residuo a fine richiesta, veniva finora silenziato dal difetto descritto sopra; una volta corretto quest'ultimo, avrebbe fatto scattare la pagina di dettaglio ad ogni richiesta priva di query string.

File modificati:

📖 Documentazione

docs-phpdoc/ — Rigenerazione completa

Rigenerata tramite composer phpdoc per riflettere il nuovo metodo BufferManager::discardAll().

✅ Backward Compatibility

[12.0.3] - 2026-07-04 - Correzione Ordine http_response_code()/Flush e Cascata di Pagine d'Errore Duplicate

Patch che corregge due difetti resi visibili dalla chiusura esplicita del buffer introdotta in 12.0.2: impostare il codice di risposta HTTP dopo aver già scaricato l'output al client, e una shutdown function che non distingueva un errore fatale reale da un semplice warning residuo né verificava se una risposta fosse già stata inviata.

🐛 Bug Fix

Core/Services/RenderService — http_response_code() impostato dopo l'invio dell'output

Da quando BufferManager::flush() chiude realmente tutti i livelli di buffer del framework fino al floor (12.0.2), invocarlo durante il rendering scarica per davvero il contenuto al client, gli header compresi. generateView(), generateData() e generateJson() costruivano però l'oggetto Response — il cui costruttore chiama http_response_code() per impostare il codice desiderato (es. 500 per una pagina d'errore) — solo dopo aver chiamato BufferManager::flush(). A quel punto gli header erano già stati inviati, e PHP generava il warning http_response_code(): Cannot set response code - headers already sent (output started at .../BufferManager.php:55).

Spostata la costruzione di Response prima di BufferManager::flush() in tutti e tre i metodi: il codice di stato viene ora impostato mentre l'output è ancora bufferizzato, prima che gli header vengano effettivamente inviati.

File modificati:

Core/HelperClasses/ErrorHandler::registerNonThrowableErrorHandler() — cascata di pagine d'errore duplicate

Il warning descritto sopra, in quanto ultimo errore PHP della richiesta, veniva intercettato da error_get_last() nella shutdown function registrata da registerNonThrowableErrorHandler(). Questa si limitava a verificare is_array($error), senza distinguere un errore realmente fatale da un semplice warning né controllare se una risposta fosse già stata inviata per la richiesta corrente: trattava quindi il warning come un crash non catturato e tentava di renderizzare un'ulteriore pagina d'errore completa, la quale — generando a sua volta lo stesso warning — poteva ripetere la cascata una terza volta, questa volta mostrata "nuda" da PHP perché display_errors era già stato riattivato da showErrorInDevelopmentEnvironment() (chiamato nel blocco finally di Public/index.php, eseguito prima della shutdown function).

Aggiunte due guardie alla shutdown function:

In ambiente di sviluppo il comportamento resta volutamente invariato: qualsiasi errore residuo, warning incluso, continua a generare la pagina di dettaglio (nonThrowableError()), scelta progettuale per rendere visibile ogni anomalia durante lo sviluppo.

File modificati:

♻️ Pulizia Codice

Core/HelperClasses/Dispatcher/ControllerFactory::createController() — rimossa condizione "fast path" ridondante

Il metodo selezionava un "fast path" (new $controllerClassName($this->dataMapper, $this->debugger)) per i costruttori senza parametri, con un solo parametro DataMapper, o con DataMapper seguito da Debugger. Per tutti e tre i casi, il percorso generico resolveConstructorArguments() produce però esattamente lo stesso risultato: PHP ignora silenziosamente gli argomenti posizionali passati in eccesso rispetto ai parametri dichiarati da un costruttore, quindi passare sempre $dataMapper/$debugger a un costruttore che ne dichiara meno (o nessuno) equivaleva già a quanto fa resolveConstructorArguments() valutando i tipi dichiarati uno per uno. La condizione non copriva inoltre alcun caso non già gestito dal percorso generico: era codice morto.

Rimossa la condizione: createController() passa ora sempre attraverso resolveConstructorArguments().

File modificati:

📖 Documentazione

docs-phpdoc/ — Rigenerazione completa

Rigenerata tramite composer phpdoc. Nessuna modifica di rilievo: le correzioni di questa release non toccano segnature pubbliche né aggiungono classi, l'unico file con differenze (SismaFramework-Core-Services-RenderService.html) riflette esclusivamente lo spostamento dei numeri di riga dovuto al riordino del codice in RenderService.php.

✅ Backward Compatibility

[12.0.2] - 2026-07-04 - Chiusura Esplicita del Buffer di Rendering in RenderService

Patch che rende esplicita la chiusura del buffer di output aperto da RenderService durante il rendering, invece di fare affidamento sullo scaricamento implicito a fine script. La correzione ha permesso di eliminare un workaround diventato necessario nella suite di test e ha reso visibili due difetti preesistenti che il workaround mascherava.

🐛 Bug Fix

Core/Services/RenderService — Buffer di rendering non chiuso esplicitamente

assemblesComponents() (usato da generateView() e generateData()) e generateJson() aprono un livello di buffer tramite BufferManager::start() ma non lo richiudevano mai esplicitamente: il contenuto renderizzato restava bufferizzato fino alla chiusura naturale dello script PHP, che scarica automaticamente i buffer residui a fine richiesta. Questo comportamento implicito funziona in un normale ciclo richiesta/risposta (un processo per richiesta), ma lascia il buffer indefinitamente "in sospeso" in qualunque contesto che riutilizzi lo stesso processo per più cicli logici — come la suite di test, dove PHPUnit esegue centinaia di test nello stesso processo.

Aggiunta una chiamata esplicita a BufferManager::flush() al termine di generateView(), generateData() e generateJson(), subito prima di restituire la Response: il buffer aperto da ciascuna chiamata viene ora sempre chiuso nello stesso punto logico in cui viene aperto, senza fare affidamento sullo scaricamento implicito di fine script. Valutata anche l'aggiunta della stessa chiamata in Dispatcher::run(): verificato che è superflua, perché BufferManager::start() viene invocato solo da RenderService, che ora si chiude sempre da solo.

File modificati:

🧪 Test

Allineamento della suite dei test alla nuova gestione del buffer

Con BufferManager::flush() ora invocato esplicitamente da RenderService, la suite di test ha smesso di richiedere il workaround manuale (\ob_end_clean() a inizio test) precedentemente necessario per compensare il buffer di rendering mai chiuso. Rimosse le chiamate manuali a \ob_end_clean() in DispatcherTest, RenderTest e RenderServiceTest, e unificate le chiamate multiple a expectOutputRegex() per singolo test (non supportate da PHPUnit oltre la prima) in un'unica regex con lookahead.

La correzione ha inoltre reso visibili due difetti preesistenti, prima mascherati dal workaround:

File modificati:

✅ Backward Compatibility

[12.0.1] - 2026-07-03 - Fix: Copertura Incompleta Comando sisma upgrade (11.x → 12.0.0) e Miglioramenti al Sito di Autopromozione

🐛 Bug Fix

Estensione copertura comando sisma upgrade (11.x → 12.0.0)

La strategy Upgrade11to12Strategy copriva solo 2 delle 3 breaking change della 12.0.0 (rinomina SelfReferencedModel e riordino parametri di setFulltextIndexColumn), lasciando silenziosa la rimozione dei metodi deprecati e delle classi LogException/NoLogException.

File aggiunti:

File modificati:

robots.txt e sitemap.xml non raggiungibili (404) sul sito di autopromozione

Le richieste a /robots.txt e /sitemap.xml restituivano la pagina di errore generica del sito (Errore seguito dal path grezzo) invece del contenuto atteso. I due file erano posizionati nella root del modulo Sample/, ma ResourceHandler::handleResourceFile() risolve i file statici solo in tre percorsi: la root di progetto, gli assets strutturali del framework e la cartella Assets/ del modulo applicativo (Sample/Assets/) — mai la root del modulo stesso, che è riservata all'albero di classi/viste (Controllers/, Models/, Views/, ecc.). Non trovando il file in nessuno dei tre percorsi, il dispatcher lanciava una PageNotFoundException con il path richiesto come messaggio, gestita da SampleController::error() come una pagina di errore qualsiasi.

File spostati:

Config/config.php — La root del sito (/) serviva la pagina degli esempi invece della homepage

DEFAULT_PATH era impostato su sample: RouteResolver::parsePath() lo usa come controller quando l'URL è vuoto, quindi ogni richiesta a / risolveva a SampleController::index() (la lista di articoli demo) invece che a HomeController::index() (la landing page del framework). HomeController::welcome(), il cui docblock dichiara URL: /, era di fatto irraggiungibile da quel path — mentre sitemap.xml e robots.txt indicavano / come homepage con priorità massima.

File modificati:

Core/HelperClasses/Dispatcher/ControllerFactory.php — Istanziazione errata dei controller con parametri di costruttore aggiuntivi dopo DataMapper

createController() decideva se usare la "fast path" di istanziazione (new $controllerClassName($this->dataMapper, $this->debugger)) controllando solo che il primo parametro del costruttore fosse di tipo DataMapper, senza verificare che il secondo fosse effettivamente Debugger. Per un controller con firma __construct(DataMapper $dataMapper, XxxService $xxxService) — come Sample/Controllers/HomeController.php, DocsController.php e SampleController.php, che accettano FrameworkInfoService come secondo parametro — veniva comunque intrapresa la fast path, passando un'istanza di Debugger al posto del servizio atteso: il dispatcher reale falliva con un TypeError all'istanziazione del controller.

Il controllo ora enumera esplicitamente i soli casi ammessi per la fast path: costruttore senza parametri, un solo parametro di tipo DataMapper, oppure esattamente due parametri rispettivamente DataMapper e Debugger. Qualsiasi altra combinazione (inclusi eventuali costruttori con tre o più parametri) passa sempre dalla risoluzione generica resolveConstructorArguments(), che istanzia ogni parametro in base al proprio tipo — più robusta anche di un controllo basato solo su "il secondo parametro è Debugger?", che avrebbe comunque richiamato la fast path (con soli due argomenti posizionali) anche in presenza di un eventuale terzo parametro obbligatorio.

File modificati:

Sample/Controllers/SampleController::protected() — Metodi inesistenti su Authentication

L'azione chiamava $auth->isLogged(), $auth->getAuthenticatedUser() e $auth->getUserIdentifier() su Security\HttpClasses\Authentication: nessuno di questi tre metodi esiste, né su quella classe né sulla base BaseAuthentication (che espone solo getAuthenticableInterface(), utilizzabile esclusivamente nella stessa richiesta in cui checkAuthenticable() ha già validato le credenziali). Qualunque richiesta a /sample/protected falliva con un Error: Call to undefined method. Mancava inoltre la view sample/protected.php, mai creata.

Come documentato in docs/security.md, Authentication si occupa solo della validazione delle credenziali in fase di login; la persistenza dello stato di autenticazione tra richieste va gestita tramite Session. Riscritta l'azione per verificare Session::hasItem('userId'), coerente con l'esempio di login già presente nella documentazione. Il modulo demo non include un flusso di login (nessuna entity implementa AuthenticableInterface), quindi l'azione dimostra il pattern di guardia ma reindirizza sempre alla pagina di errore in assenza di sessione.

File aggiunti:

File modificati:

Core/HelperClasses/BufferManager — clear()/flush() non gestivano output buffer annidati

clear() e flush() operavano solo sul livello di output buffer più interno (ob_clean()/ob_flush() agiscono su un singolo livello), mentre diverse view che si appoggiano a siteLayout.php aprono un proprio buffer annidato (ob_start() per catturare $content prima di includere il layout condiviso) dentro quello già aperto da RenderService::assemblesComponents(). Se un'eccezione (ogni BaseException, incluse tutte le eccezioni HTTP del framework, chiama BufferManager::clear() nel proprio costruttore) veniva sollevata mentre il buffer della view era ancora aperto, clear() ripuliva solo quel livello interno, lasciando aperto e non azzerato il livello esterno del framework — una correttezza che si è retta finora solo sul fatto che quel livello esterno risultava sempre vuoto in pratica, non su una garanzia del codice.

clear()/flush() ora svuotano in loop tutti i livelli di buffer aperti dal framework, tramite ob_end_clean()/ob_end_flush(). Per evitare di richiudere buffer non di proprietà del framework (es. quello di PHPUnit durante i test, o un eventuale buffer aperto dal server prima dell'avvio della richiesta), la classe memorizza ora un livello di base ($baseLevel), rilevato al primo utilizzo, sotto il quale i due metodi non scendono mai. Una prima versione che svuotava incondizionatamente fino al livello 0 assoluto è stata scartata perché rompeva l'isolamento dei buffer di PHPUnit (57 test segnalati come "risky" nella suite completa).

File modificati:

📖 Documentazione

docs-phpdoc/ — Rigenerazione completa

Rigenerata tramite composer phpdoc per includere le nuove classi introdotte in questa release (ExceptionBaseClassTransformer, DeprecatedMethodUsageTransformer) e riflettere le modifiche a Upgrade11to12Strategy e UpgradeManager. Sample/, Config/ e Tests/ restano esclusi dalla generazione (phpdoc.xml), quindi le modifiche al sito di autopromozione e alla configurazione di questa release non compaiono in questa documentazione API.

🎨 Miglioramenti Sito di Autopromozione (Sample)

Rimosso l'uso di ob_start()/ob_get_clean() dalle view (commonParts/siteLayout.php sostituito da header/footer)

Le view basate sul layout condiviso (home/*, docs/*, quasi tutte le sample/*) catturavano il proprio contenuto con ob_start()/ob_get_clean() in una variabile $content, poi interpolata a metà di siteLayout.php tra navbar e footer — un buffer annidato dentro quello già aperto da RenderService::assemblesComponents(). Non è il pattern documentato dal framework: docs/views.md indica esplicitamente di dividere il layout in header.php/footer.php e usare require sequenziali, proprio per evitare qualunque trucco di output buffering nelle view. Le view più vecchie del sito (error.php, notify.php) seguivano già correttamente questo pattern.

Sample/Views/commonParts/siteLayout.php è stato sostituito da siteLayoutHeader.php (tutto fino alla chiusura della navbar) e siteLayoutFooter.php (dal footer alla chiusura di </html>). Le 12 view interessate ora fanno require del primo prima del contenuto e del secondo dopo, senza alcun output buffering proprio. Verificato con rendering reale (PHP built-in server) di tutte le pagine coinvolte, oltre alla suite PHPUnit completa.

File aggiunti:

File rimossi:

File modificati:

Versione e data di rilascio visibili nel sito

La versione corrente del framework e la data di rilascio non erano visibili in nessuna pagina del sito di autopromozione (Sample), se non nel CHANGELOG.md. Aggiunto un badge versione in navbar (linkato a /docs/changelog) e una riga "Versione X.Y.Z — rilasciata il ..." nel footer; corretto anche il campo softwareVersion nel JSON-LD della homepage, rimasto hardcoded a 10.0.3 per diverse major.

Le informazioni vengono ricavate automaticamente da composer.json (versione) e dal primo blocco datato del CHANGELOG.md (data di rilascio corrispondente), tramite un nuovo Service iniettato nei controller — coerente con il pattern di dependency injection già usato per DataMapper/Debugger — evitando così di doverle allineare manualmente ad ogni rilascio.

File aggiunti:

File modificati:

Rimozione codice di debug residuo

Rimossi gli script usati per diagnosticare il bug del parser Markdown risolto in 11.8.1, mai ripuliti dopo il fix, incluso un metodo di controller raggiungibile pubblicamente via URL.

File rimossi:

File modificati:

Sample/module.json — Allineamento versione

framework_version e requires.sismaframework erano rimasti fermi a 11.0.0; allineati a 12.0.1.

File modificati:

Sample/Assets/sitemap.xml — Allineamento con le pagine reali del sito

La sitemap indicizzava solo 2 delle 31 pagine di documentazione (getting-started, api-reference), non includeva /docs/changelog, ed elencava tutte le pagine con <lastmod> fermo al 2025-01-15. Riscritta per includere l'intero albero di docs/index.md, raggruppato per sezione con priorità decrescente, e aggiornate le date.

File modificati:

✅ Backward Compatibility

[12.0.0] - 2026-07-02 - Breaking Changes: Rinomina SelfReferencedModel e Riordinamento Parametri Query

💥 Breaking Changes

SelfReferencedModel → SelfDependentModel

La classe SelfReferencedModel è stata rinominata in SelfDependentModel per allineare la nomenclatura del layer model al concetto di dipendenza (anziché referenziazione). Nel layer model la chiave classificatoria è la presenza di chiavi esterne nell'entità gestita (dipendenza), non il fatto di essere referenziata da altre entità (referenziazione, concetto proprio del layer entity). L'autoreferenziazione è bidirezionale, quindi un'entità autoreferenziata è anche autodipendente; il nome SelfDependentModel riflette correttamente la prospettiva del layer model.

File modificati:

Migrazione: Sostituire ogni occorrenza di SelfReferencedModel con SelfDependentModel nei use statement e nelle dichiarazioni extends dei propri model.

Query::setFulltextIndexColumn() — Riordinamento parametri

I parametri del metodo setFulltextIndexColumn della classe Query sono stati riordinati per garantire coerenza con la firma degli altri metodi della classe.

File modificati:

Migrazione: Verificare e aggiornare l'ordine degli argomenti in ogni chiamata a setFulltextIndexColumn.

Rimozione metodi e classi deprecati

Come pianificato, i metodi e le classi deprecati con rimozione prevista in questa versione sono stati eliminati.

DependentModel — rimossi i metodi deprecati dalla v10.1.0:

SelfDependentModel — rimossi i metodi deprecati dalla v10.1.0:

Security/ExtendedClasses/LogException e Security/ExtendedClasses/NoLogException — rimosse interamente, deprecate dalla v11.0.0. AccessDeniedException ora estende direttamente BaseException implementando ShouldBeLoggedException.

File modificati:

File rimossi:

Migrazione: Sostituire ogni chiamata ai metodi rimossi con l'equivalente metodo magico; sostituire extends LogException/extends NoLogException con extends BaseException (implementando ShouldBeLoggedException se la classe deve essere loggata).

✨ Nuove Funzionalità

Supporto upgrade automatico 11.x → 12.x nel comando sisma upgrade

Il sistema di upgrade automatico dei moduli ora copre anche la migrazione dalla versione 11 alla 12. Le due breaking change di questa versione vengono gestite tramite due nuovi transformer, integrati nella nuova strategy Upgrade11to12Strategy.

Transformer ClassRenameTransformer (confidence: 95%):

Transformer FulltextIndexColumnTransformer (confidence: 70%):

File aggiunti:

File modificati:

Console/Traits/InteractiveInputTrait — Iniezione dello stream di input per i test

Il trait espone ora il metodo pubblico setInputStream(), che permette di sostituire lo stream php://stdin usato da ask(), askConfirmation() e askSecret() con uno stream arbitrario (es. php://memory), rendendo testabili i comandi interattivi senza dover simulare un vero input da terminale. Lo stream, se non iniettato esplicitamente, viene aperto una sola volta e riutilizzato tra le chiamate successive (in precedenza veniva aperto e richiuso ad ogni singola richiesta).

File modificati:

🔧 Pulizia Configurazione

Config/config.php e Core/HelperClasses/Config.php — Rimozione costanti non utilizzate

Rimosse le costanti dichiarate in Config/config.php (e le relative proprietà esposte da Core/HelperClasses/Config.php) non più referenziate da alcuna classe del framework: ADAPTERS, ADAPTER_NAMESPACE, ADAPTER_PATH, CONFIGURATION_PASSWORD, CORE, CORE_NAMESPACE, CORE_PATH, DEFAULT_CONTROLLER, DEFAULT_CONTROLLER_NAMESPACE, DEFAULT_CONTROLLER_PATH, DEFAULT_META_URL, MODEL_PATH, ORM, ORM_NAMESPACE, ORM_PATH, PUBLIC_PATH, STRUCTURAL_RESOURCES_PATH, THIS_DIRECTORY.

Rimosse anche LOG_WARNING_ROW e LOG_DANGER_ROW: non erano lette da alcuna classe del framework (che usa invece LOG_VERBOSE_ACTIVE, LOG_DEVELOPMENT_MAX_ROW e LOG_PRODUCTION_MAX_ROW per la rotazione dei log), ma solo da moduli applicativi esterni per colorare un indicatore nella dashboard di back-end. La loro dichiarazione va spostata nel file di configurazione del modulo consumatore, secondo il pattern già seguito da costanti equivalenti (es. soglie di warning/danger per la dimensione dei media).

File modificati:

Migrazione: chi facesse riferimento diretto a una di queste costanti tramite \Config\NOME_COSTANTE in un modulo applicativo deve dichiararla nel file di configurazione del proprio modulo.

[11.9.0] - 2026-06-27 - Configurazione Database e Crittografia tramite Variabili d'Ambiente

Questa minor release permette di configurare le credenziali del database e la passphrase di cifratura tramite variabili d'ambiente, evitando di doverle scrivere come valori letterali in Config/configFramework.php — file che, a differenza di Config/config.php, viene generato durante l'installazione e tipicamente committato nel progetto applicativo. L'installer rileva automaticamente quando queste variabili sono già presenti nell'ambiente e salta la richiesta interattiva/CLI corrispondente.

✨ Nuove Funzionalità

Config/config.php — Costanti database e cifratura risolte tramite getenv()

Le costanti DATABASE_HOST, DATABASE_NAME, DATABASE_USERNAME, DATABASE_PASSWORD, DATABASE_PORT ed ENCRYPTION_PASSPHRASE non sono più dichiarate con const ma con define(__NAMESPACE__ . '\NOME_COSTANTE', getenv('NOME_COSTANTE') ?: ""). Questo era necessario perché PHP non ammette chiamate a funzione (getenv()) all'interno di un'espressione costante dichiarata con const; define() accetta invece un'espressione valutata a runtime. Il namespace va qualificato esplicitamente (__NAMESPACE__ . '\...') perché, a differenza di const, define() non eredita automaticamente il namespace del file.

Se la variabile d'ambiente non è impostata, il fallback resta la stringa vuota "", identico al valore di default precedente: il comportamento per chi non adotta variabili d'ambiente è invariato.

File modificati:

Console/Commands/InstallationCommand::collectDatabaseConfiguration() — Skip automatico con variabili d'ambiente già presenti

Aggiunto il metodo privato hasDatabaseConfigFromEnvironment(), che verifica se almeno una tra DATABASE_HOST, DATABASE_NAME, DATABASE_USERNAME, DATABASE_PASSWORD, DATABASE_PORT è già impostata nell'ambiente del processo. Il controllo viene eseguito dopo quello sulle opzioni CLI (--db-host e affini, che restano prioritarie se esplicitamente fornite) e prima del prompt interattivo: se l'ambiente fornisce già la configurazione, l'installer stampa un messaggio informativo e prosegue senza chiedere nulla, evitando di scrivere un fallback letterale — e quindi un potenziale segreto — in Config/configFramework.php.

Aggiornato anche il testo di --help del comando per documentare il nuovo comportamento.

File modificati:

.env.example — Documentazione delle variabili d'ambiente consultate dal framework

Aggiunto un file .env.example nella root del framework che elenca le sei variabili d'ambiente lette via getenv() in Config/config.php. Il file è puramente documentale: il framework non effettua alcun parsing di file .env (nessuna nuova dipendenza, nessun loader interno) — le variabili devono essere rese disponibili come variabili d'ambiente del processo PHP da chi gestisce il deployment (Docker env_file, direttive del web server, systemd EnvironmentFile, export manuale, ecc.).

File creati:

🔧 Modifiche Interne

Console/Services/Installation/InstallationManager::updateConfigFile() — Supporto al nuovo pattern define()+getenv()

La sostituzione dei valori raccolti da CLI/prompt interattivo in Config/configFramework.php riconosceva solo il pattern const NOME = "valore";. Aggiunto un secondo pattern che riconosce define(__NAMESPACE__ . '\NOME', getenv('NOME') ?: "valore") e aggiorna soltanto il valore di fallback dopo ?:, lasciando intatta la chiamata a getenv() — così l'ambiente continua ad avere priorità anche su un valore scritto in fase di installazione.

File modificati:

✅ Backward Compatibility

[11.8.1] - 2026-06-25 - Correzione Parsing Code Block Annidati nelle Blockquote (Sample)

Patch che corregge il parser Markdown del sito di autopromozione/documentazione (Sample/Controllers/DocsController.php): i fenced code block annidati in una blockquote venivano interpretati in modo scorretto, corrompendo il rendering di tutto il contenuto successivo del documento. Corretto anche un fence orfano nel file docs/advanced-orm.md.

🐛 Bug Fixes

Sample/Controllers/DocsController::parseMarkdown() — Code block annidati in blockquote

La regex che estrae i fenced code block (sequenza di tre backtick) cercava i marcatori ovunque nel testo, senza considerare un eventuale prefisso > di blockquote. Quando un code block era annidato in una blockquote (es. una riga > seguita dai tre backtick e dal nome del linguaggio), il marcatore di chiusura — anch'esso prefissato da > — non veniva riconosciuto come tale: la regex continuava ad espandersi non-greedy fino ai successivi tre backtick "nudi" (non prefissati da > ) nel documento, inghiottendo tutto il contenuto intermedio (inclusi altri code block, header e liste) in un unico blocco corrotto con lingua errata.

Aggiunto un nuovo step, eseguito prima dell'estrazione dei code block "normali" e dello step delle blockquote, che riconosce specificamente i fenced code block prefissati da > su ogni riga (apertura, contenuto e chiusura), rimuove il prefisso dal contenuto e li converte in <pre><code> esattamente come gli altri code block. Le righe di blockquote senza code block annidato continuano a essere gestite dallo step esistente.

File modificati:

docs/advanced-orm.md — Fence di chiusura orfano

Un marcatore di chiusura (tre backtick) senza apertura corrispondente era stato lasciato per errore dopo una lista (sezione "Best Practices" del capitolo sul lazy loading). Da quel punto in poi, l'alternanza apertura/chiusura dei fence successivi nel documento risultava sfasata, producendo blocchi di codice corrotti che inghiottivano header e sezioni successive.

File modificati:

✅ Backward Compatibility

[11.8.0] - 2026-06-23 - Miglioramento Flessibilità addRequest() in BaseForm e Standardizzazione Formattazione

Questa minor release estende la flessibilità del metodo addRequest() della classe BaseForm permettendo il controllo esplicito sulle sovrascritture di valori nella request. Inoltre, standardizza la formattazione del codice con miglior indentazione e trailing comma secondo le best practice PHP moderne.

✨ Nuove Funzionalità

Core/BaseClasses/BaseForm::addRequest() — Controllo esplicito sulle sovrascritture

Il metodo addRequest() è stato esteso con due miglioramenti:

Ampliamento tipi di $value:

Consente di iniettare nella request dati di diversi tipi primitivi, non solo stringhe e array.

Aggiunta parametro $override con controllo sulle sovrascritture:

Il parametro $override = true (default) mantiene il comportamento precedente: sovrascrive sempre. Passando false, il metodo scrive il valore solo se la proprietà non esiste ancora in request->input.

Caso d'uso: 

// Inietta un valore di default che non sovrascrive l'input dell'utente
$this->addRequest('email', 'default@example.com', override: false);

File modificati:

🎨 Miglioramenti Formattazione Codice

Standardizzazione Indentazione e Trailing Comma

Standardizzate le convenzioni di formattazione secondo PSR-12:

Costruttore di BaseForm:

Metodi con parametri multipli:

Vantaggi della trailing comma:

File modificati:

🧪 Test

Tests/Core/BaseClasses/BaseFormTest — Copertura nuovo parametro $override

Aggiunti tre test per verificare il comportamento del nuovo parametro $override in addRequest():

File creati:

File modificati:

✅ Backward Compatibility

[11.7.0] - 2026-06-18 - Opzione --module e Discovery dei Moduli Non Configurati

Introduce l'opzione --module=NomeModulo per selezionare esplicitamente quale modulo deve gestire un comando quando più moduli registrano lo stesso nome. Aggiunge contestualmente la discovery automatica dei moduli fisicamente presenti su filesystem ma non ancora dichiarati in MODULE_FOLDERS, risolvendo il problema di bootstrap circolare per cui un modulo non poteva registrarsi tramite il proprio comando di installazione perché non ancora configurato.

✨ Nuove Funzionalità

Console/HelperClasses/CommandDispatcher — Opzione --module per selezione esplicita del modulo

Aggiunta l'opzione globale opzionale --module=NomeModulo al dispatcher dei comandi console. Quando specificata, il dispatcher filtra la lista dei comandi compatibili e ne esegue solo uno appartenente al modulo indicato; se nessun comando di quel modulo è compatibile, viene lanciata RuntimeException come per un comando sconosciuto. Senza l'opzione il comportamento rimane invariato (primo match vince, nell'ordine di priorità della discovery).

Per supportare il filtro, ogni comando scoperto viene ora associato al proprio modulo di appartenenza tramite un array parallelo $commandModules[]. La firma di discoverFromDirectory() include il parametro string $module e addCommandStrategy() accetta un secondo parametro opzionale string $module = '' per retrocompatibilità con i chiamanti esistenti.

File modificati:

Console/HelperClasses/CommandDispatcher — Discovery automatica dei moduli non configurati

Il metodo privato discoverUnconfiguredModules() esegue un glob su {rootPath}/*/Console/Commands/ e restituisce le cartelle modulo che hanno quella struttura ma non sono ancora presenti in MODULE_FOLDERS. Questi moduli vengono scansionati dopo quelli configurati e prima del framework, con priorità inferiore rispetto ai moduli dichiarati nella configurazione. La combinazione con --module= permette di eseguire il comando di installazione di un modulo anche prima che sia stato aggiunto a MODULE_FOLDERS.

File modificati:

🧪 Test

Tests/Console/HelperClasses/CommandDispatcherTest — Copertura opzione --module e moduli non configurati

File modificati:

✅ Backward Compatibility

[11.6.3] - 2026-06-17 - Correzione Input Password e Sostituzione Valori Numerici nel File di Configurazione

Patch che corregge due bug nel comando di installazione CLI: askSecret() emetteva un errore stty su ambienti senza TTY reale (IDE, pipe, container), e updateConfigFile() troncava i valori numerici come la porta del database a causa di un'ambiguità nelle backreference PCRE della stringa di sostituzione.

🐛 Bug Fixes

Console/Traits/InteractiveInputTrait — Errore stty su stdin non-TTY

Il metodo askSecret() chiamava system('stty -echo') condizionato solo al check PHP_OS === 'WIN', che non copre i casi in cui stdin non è un terminale reale anche su Linux/macOS (IDE come VS Code o PhpStorm, esecuzione via pipe, container Docker, ambienti CI). In questi contesti stty stampava l'errore stty: 'standard input': Inappropriate ioctl for device subito dopo il prompt della password.

Il check è stato sostituito con stream_isatty($handle), che verifica correttamente se il file descriptor è collegato a un TTY reale indipendentemente dal sistema operativo. Se stdin non è un TTY, la password viene letta senza tentare di disabilitare l'echo.

File modificati:

Console/Services/Installation/InstallationManager — Troncamento valori numerici in updateConfigFile()

Il metodo updateConfigFile() costruiva la stringa di sostituzione per preg_replace() interpolando il valore direttamente in una stringa PHP: "$1$2{$value}$2". Quando $value iniziava con una cifra (es. la porta 3306), l'interpolazione produceva la stringa $1$23306$2, che PCRE interpretava come $1 + $23 (backreference al gruppo 23, inesistente → stringa vuota, consumando la prima cifra) + 306 (letterale) + $2 (la virgoletta). Il risultato nel file di configurazione era DATABASE_PORT = 306" — valore troncato e virgoletta di chiusura mancante.

Il metodo è stato riscritto usando preg_replace_callback(): il valore di sostituzione viene concatenato direttamente nella closure PHP, senza mai passare per il parser delle backreference PCRE. Questo risolve anche il caso analogo di password contenenti $ o \.

File modificati:

🧪 Test

Tests/Console/Services/Installation/InstallationManagerTest — Copertura regressione valori numerici

✅ Backward Compatibility

[11.6.2] - 2026-06-09 - Correzione Ordine di Discovery dei Comandi Console

Patch che corregge un comportamento anomalo nel CommandDispatcher: i comandi dei moduli venivano scoperti dopo quelli del framework, impedendo ai moduli di estendere o sovrascrivere i comandi nativi. L'ordine è stato invertito — moduli prima (nell'ordine di MODULE_FOLDERS), framework come fallback — allineando il CommandDispatcher alla stessa logica di precedenza già adottata dal web Dispatcher.

🐛 Bug Fixes

Console/HelperClasses/CommandDispatcher — Ordine di discovery dei comandi

Il metodo discoverCommands() scansionava prima la directory dei comandi del framework (SismaFramework/Console/Commands/) e poi quella dei moduli, nell'ordine inverso rispetto al comportamento atteso. Poiché run() si ferma al primo comando compatibile, qualsiasi comando di un modulo con lo stesso nome di un comando del framework veniva silenziosamente ignorato, rendendo impossibile estendere o sovrascrivere i comandi nativi dall'esterno del framework.

L'ordine è stato corretto: i moduli vengono scansionati per primi, rispettando la sequenza dichiarata in MODULE_FOLDERS; il framework viene aggiunto per ultimo come fallback. Questo rispecchia esattamente la logica di precedenza del web Dispatcher e permette ai moduli di estendere i comandi del framework tramite ereditarietà, chiamando parent::execute() dopo aver aggiunto la propria logica.

File modificati:

✅ Backward Compatibility

[11.6.1] - 2026-05-26 - Compatibilità phpDocumentor, Fix SismaLogger e Correzione Documentazione

Patch di manutenzione che allarga il vincolo su psr/log per consentire l'installazione di phpDocumentor come dipendenza di sviluppo, corregge un potenziale TypeError in SismaLogger::interpolate() con messaggi \Stringable, aggiorna la documentazione Markdown (esempi API errati, sezione OAuth mancante) e rigenera la documentazione phpDocumentor allineandola alle classi introdotte in 11.6.0.

🐛 Bug Fixes

Core/HelperClasses/SismaLogger — Gestione \Stringable in interpolate()

Il metodo privato interpolate() dichiarava string $message come tipo del parametro. Poiché LoggerInterface (psr/log 2.x/3.x) consente di passare oggetti \Stringable ai metodi di log, qualsiasi chiamata con un \Stringable avrebbe generato un TypeError prima di raggiungere il metodo. Il tipo è stato aggiornato a \Stringable|string e viene applicato un cast (string) all'inizio del metodo, garantendo la compatibilità con l'intera gamma di messaggi ammessi dall'interfaccia PSR-3.

File modificati:

Console/Services/Installation/InstallationManager — Vincolo psr/log nei nuovi progetti

Il metodo che inietta la dipendenza psr/log nel composer.json dei nuovi progetti impostava il vincolo a ^3.0. Aggiornato a ^2.0 || ^3.0 per allinearlo al vincolo del framework e consentire la coesistenza con phpDocumentor anche nei progetti installati.

File modificati:

🔧 Dipendenze e Tooling

composer.json — Allargamento vincolo psr/log e aggiunta phpDocumentor

Il vincolo "psr/log": "^3.0" impediva l'installazione di phpDocumentor come require-dev, poiché le sue dipendenze indirette richiedono psr/log ^2.0. Il vincolo è stato allargato a ^2.0 || ^3.0: il codice del framework non usa alcuna API specifica di psr/log 3.x (i metodi LoggerInterface sono implementati senza type hint espliciti su $message, compatibili con tutte e tre le major), quindi l'allargamento non introduce alcun rischio regressivo.

Aggiunto inoltre "config": {"platform": {"php": "8.4.99"}} per permettere la risoluzione delle dipendenze su PHP 8.5 (dove phpdocumentor/json-path — dipendenza indiretta — non dichiara ancora supporto esplicito, pur funzionando correttamente). Aggiunto script "phpdoc": "php vendor/bin/phpdoc --config phpdoc.xml" per semplificare la rigenerazione della documentazione API.

File modificati:

🧪 Test

Tests/Console/Services/Installation/InstallationManagerTest — Allineamento asserzioni

Le due asserzioni che verificavano il valore del vincolo psr/log iniettato da InstallationManager sono state aggiornate da '^3.0' a '^2.0 || ^3.0'.

File modificati:

📖 Documentazione

docs/security.md — Correzione esempi API e aggiunta sezione OAuth

La sezione di esempio per l'autenticazione form-based conteneva riferimenti a metodi inesistenti nell'API pubblica (isLogged(), login()) e a un pattern logicamente scorretto (checkAuthenticable() && checkPassword(), dove checkPassword() è già chiamato internamente da checkAuthenticable()). Corretti anche gli accessi alle proprietà di Request (da notazione ad oggetto ->get() a accesso array ['key'], coerente con la definizione della classe) e il nome del metodo getAuthenticable() → getAuthenticableInterface().

Aggiunta sezione completa Autenticazione OAuth 2.0 che documenta OAuthAuthentication, OAuthWrapperInterface, il flusso Authorization Code in due fasi e un esempio di implementazione di un wrapper provider.

File modificati:

docs/forms.md — Correzione nome metodo getFilterErrors()

L'esempio del controller utilizzava $form->returnFilterErrors(), metodo inesistente. Corretto in $form->getFilterErrors() (metodo ereditato da SubmittableTrait).

File modificati:

docs/controllers.md — Correzione esempio autowiring Authentication

L'esempio di autowiring utilizzava $auth->isLogged() (metodo inesistente), il namespace errato SismaFramework\Security\Authentication e l'accesso alle proprietà di Request tramite ->get(). Corretti namespace, metodo di verifica sessione e accesso array.

File modificati:

docs/api-reference.md — Correzione firme BaseForm e aggiunta sezioni Security/HTTP

getErrors(): FormFilterErrorCollection era il nome errato del metodo (corretto in getFilterErrors(): FormFilterError); la firma di handleRequest() mancava del parametro Request $request. Aggiunte le sezioni Security Classes (Authentication, OAuthAuthentication, OAuthWrapperInterface, BaseVoter, BasePermission) e HTTP Classes (Response), che erano elencate nell'indice del documento ma mai implementate nel corpo.

File modificati:

docs-phpdoc/ — Rigenerazione completa

Rigenerata da zero tramite composer phpdoc per includere le nuove classi introdotte in 11.6.0 (OAuthAuthentication, OAuthWrapperInterface, BaseAuthentication, SubmittableTrait) ed eliminare il file orfano SismaFramework-Core-AbstractClasses-Submittable.html, rimasto dalla generazione precedente dopo la rimozione del file PHP sorgente.

Correzione annotazioni @deprecated — versione di introduzione e rimozione

Quattro classi/metodi presentavano annotazioni @deprecated incomplete o errate: mancavano la versione in cui la deprecazione era stata introdotta, la versione di rimozione pianificata, oppure il testo era in inglese anziché italiano, creando incoerenza con il resto della codebase.

Orm/ExtendedClasses/DependentModel e Orm/ExtendedClasses/SelfReferencedModel — i tre metodi deprecati (countEntityCollectionByEntity, getEntityCollectionByEntity, deleteEntityCollectionByEntity) riportavano dalla versione 11.0.0, ma la deprecazione era stata introdotta in v10.1.0 (commit 9c9f5ed4, 2025-11-21). Corretto in dalla versione 10.1.0; aggiunta la versione di rimozione pianificata 12.0.0.

Security/ExtendedClasses/LogException e Security/ExtendedClasses/NoLogException — le annotazioni erano in inglese e prive di numeri di versione. La deprecazione è stata introdotta in v11.0.0 (commit 87843e03, 2025-12-18). Aggiunta versione di introduzione 11.0.0, versione di rimozione 12.0.0; testo armonizzato in italiano coerentemente con gli altri messaggi di deprecazione del framework.

File modificati:

✅ Backward Compatibility

[11.6.0] - 2026-05-04 - Rifattorizzazione Gerarchia di Autenticazione, Introduzione SubmittableTrait e Supporto OAuth

Rifattorizzazione interna del sistema di autenticazione: la classe astratta Submittable è stata convertita in un trait, e il comportamento comune a tutte le classi di autenticazione è stato estratto nella nuova classe astratta BaseAuthentication. Il refactoring ha abilitato l'implementazione di OAuthAuthentication, che supporta il flusso Authorization Code OAuth 2.0 senza SubmittableTrait poiché in OAuth non esiste un form da sottomettere né errori di validazione da riportare al template.

♻️ Refactoring

Core/Traits/SubmittableTrait — Conversione da classe astratta a trait

Submittable era una classe astratta @internal usata come base sia da Authentication che da BaseForm, pur non rappresentando un tipo condiviso tra le due gerarchie, bensì un comportamento ortogonale (rilevamento form submission). È stata convertita in un trait e spostata in Core/Traits/.

Il trait espone:

File modificati:

Security/BaseClasses/BaseAuthentication — Nuova classe astratta base per l'autenticazione

Estratta da Authentication la logica comune a qualsiasi flusso di autenticazione (form-based, OAuth, ecc.). La nuova classe astratta BaseAuthentication, marcata @internal, centralizza:

SubmittableTrait non è incluso in BaseAuthentication perché non tutti i flussi di autenticazione hanno un form: Authentication (form-based) lo usa, OAuthAuthentication no.

File modificati:

Security/HttpClasses/Authentication — Adeguamento alla nuova gerarchia

Authentication passa da extends Submittable a extends BaseAuthentication con use SubmittableTrait. Le property $filter, $session, $authenticableInterface e il metodo getAuthenticableInterface() sono stati spostati in BaseAuthentication. Il costruttore chiama parent::__construct() e $this->initSubmittable().

File modificati:

Core/BaseClasses/BaseForm — Adeguamento al SubmittableTrait

BaseForm passa da extends Submittable a use SubmittableTrait, dichiarando protected Request $request direttamente nella classe. Il costruttore sostituisce parent::__construct() con $this->initSubmittable().

File modificati:

✨ Nuove Funzionalità

Security/HttpClasses/OAuthAuthentication — Autenticazione OAuth 2.0 Authorization Code Flow

Nuova classe OAuthAuthentication extends BaseAuthentication che implementa il flusso Authorization Code OAuth 2.0. Non usa SubmittableTrait perché in OAuth non esiste un form da sottomettere: gli errori arrivano come parametri URL dal provider e vengono gestiti tramite valori di ritorno ed eccezioni, non tramite FormFilterError.

Il flusso si articola in due fasi:

Fase 1 — Redirect al provider:

Fase 2 — Callback dal provider:

La protezione CSRF del callback segue lo stesso pattern difensivo di Authentication::checkCsrfToken(): verifica sequenziale con early return.

File modificati:

Security/Interfaces/Wrappers/OAuthWrapperInterface — Contratto per i provider OAuth

Nuova interfaccia che astrae la comunicazione con il provider OAuth. Ogni provider (Google, GitHub, ecc.) implementa:

File modificati:

🧪 Test

Tests/Security/HttpClasses/OAuthAuthenticationTest — Copertura completa del flusso OAuth

Sette test che coprono tutti i percorsi di checkCallback() e getAuthorizationUrl():

File modificati:

✅ Backward Compatibility

[11.5.2] - 2026-04-04 - Rifattorizzazione Template Controller nello Scaffolding

Piccola rifattorizzazione del template del controller generato dal comando di scaffolding, per semplificare eventuali personalizzazioni post-generazione.

♻️ Refactoring

Console/Services/Scaffolding/Templates/Controller.tpl — Estrazione variabile entità prima del salvataggio

Nelle azioni create e update, la chiamata a resolveEntity() era concatenata direttamente come argomento di $this->dataMapper->save() su un'unica riga. L'entità risolta viene ora assegnata a una variabile dedicata prima di essere passata al DataMapper. 

  ${{entityShortNameLower}} = ${{entityShortNameLower}}Form->resolveEntity();
  $this->dataMapper->save(${{entityShortNameLower}});

Questo rende il codice generato più leggibile e facilita eventuali personalizzazioni (es. manipolare l'entità tra resolveEntity() e save()), senza alcuna modifica al comportamento a runtime.

Rimossi inoltre i trailing whitespace sulle righe vuote tra i metodi della classe.

File modificati:

✅ Backward Compatibility

[11.5.1] - 2026-04-01 - Correzione Template Controller nello Scaffolding

Questa patch corregge due bug nel template del controller generato dal comando di scaffolding.

🐛 Bug Fixes

Console/Services/Scaffolding/Templates/Controller.tpl — Namespace modello errato e metodo form scorretto

Bug 1 — Namespace use del modello con segmento Models duplicato

Il namespace nell'istruzione use includeva un segmento \Models\ ridondante: poiché {{modelNamespace}} contiene già il segmento Models, il risultato era una duplicazione (es. …\Models\Models\{{entityShortName}}Model), producendo un'istruzione non valida nel controller generato.

Bug 2 — Uso di getEntity() al posto di resolveEntity() nelle azioni create ed edit

Il salvataggio dell'entità nelle azioni create ed edit chiamava getEntity(), che non risolve correttamente le relazioni del form. Il metodo corretto è resolveEntity().

File modificati:

✅ Backward Compatibility

[11.5.0] - 2026-03-15 - Supporto Cross-Platform per il Comando sisma

Questa minor aggiunge il supporto nativo al comando sisma su Windows e semplifica l'avvio su Linux/macOS tramite shebang.

✨ Nuove Funzionalità

Console/sisma — Aggiunto shebang #!/usr/bin/env php

Lo script sisma può ora essere invocato direttamente da terminale su Linux e macOS (es. sisma fixtures) senza anteporre php, grazie alla riga shebang. PHP ignora la riga #! quando il file viene eseguito tramite php sisma, garantendo piena retrocompatibilità.

File modificati:

Console/sisma.bat — Nuovo wrapper per Windows

Aggiunto file sisma.bat nella stessa directory di sisma, che consente di invocare il comando come sisma fixtures anche su Windows nativo (senza Docker). Windows riconosce automaticamente l'estensione .bat quando il nome del comando è nel PATH.

File aggiunti:

✅ Backward Compatibility

[11.4.1] - 2026-03-11 - Consolidamento Bootstrap e Estrazione enableErrorDisplay() in ErrorHandler

Questa patch consolida la gestione del bootstrap nei due entry point del framework. Il require_once dell'autoload di Composer viene spostato direttamente nello skeleton di index.php, semplificando la procedura d'installazione. La logica di abilitazione degli errori viene estratta in un metodo statico di ErrorHandler, eliminando la dipendenza da LoggerInterface nel contesto di bootstrap della console.

♻️ Refactoring

ErrorHandler — Estrazione di enableErrorDisplay() come metodo statico

La versione 11.4.0 aveva introdotto showErrorInDevelopmentEnvironment() come metodo d'istanza, usato anche nello script sisma. Questo richiedeva l'istanziazione di ErrorHandler e quindi la dipendenza da Psr\Log\LoggerInterface (via vendor autoload) già in fase di bootstrap della console, prima ancora di qualsiasi comando. Il blocco ini_set è stato estratto nel nuovo metodo statico enableErrorDisplay(), senza dipendenze esterne, riutilizzabile sia da sisma che internamente da showErrorInDevelopmentEnvironment().

Modifica:

File modificati:

Public/index.php — vendor/autoload.php incluso nello skeleton

Il require_once dell'autoload di Composer veniva iniettato dinamicamente da InstallationManager::copyPublicFolder() tramite manipolazione di stringa sul file copiato. Poiché il percorso relativo dirname(__DIR__) . '/vendor/autoload.php' è invariante sia nello skeleton (SismaFramework/vendor/) sia nel progetto installato (projectRoot/vendor/), la riga è ora inclusa direttamente nel file sorgente. L'ordine di caricamento è: autoload SismaFramework prima, autoload vendor dopo.

File modificati:

✅ Backward Compatibility

[11.4.0] - 2026-03-09 - Auto-discovery dei Comandi Console tramite Factory Pattern

Questa minor introduce l'auto-discovery automatico dei comandi console tramite il pattern factory nel CommandDispatcher, allineando l'architettura della console a quella del Dispatcher HTTP. I comandi non devono più essere registrati manualmente nello script sisma: vengono scoperti automaticamente sia nel framework che in tutti i moduli configurati.

✨ Nuove Funzionalità

CommandDispatcher — Auto-discovery dei comandi via factory

Il CommandDispatcher registrava i comandi esclusivamente tramite chiamate esplicite ad addCommandStrategy() nello script di avvio. Questo approccio richiedeva la modifica manuale del file sisma ad ogni aggiunta di un nuovo comando, sia nel framework che nei moduli applicativi.

Ora il costruttore invoca internamente discoverCommands(), che scansiona via reflection le directory Console/Commands/ del framework e di tutti i moduli presenti in Config::$moduleFolders, istanziando automaticamente ogni classe concreta che estende BaseCommand tramite la nuova classe CommandFactory.

Modifica:

File modificati:

Console/sisma — Rimozione registrazione manuale dei comandi

Lo script di avvio della console registrava esplicitamente tutti i comandi del framework (FixturesCommand, InstallationCommand, ScaffoldCommand, UpgradeCommand) tramite addCommandStrategy(). Con l'auto-discovery queste chiamate sono ridondanti e sono state rimosse.

Sostituito inoltre il blocco error_reporting / ini_set con l'utilizzo di ErrorHandler::showErrorInDevelopmentEnvironment(), in linea con il resto del framework.

File modificati:

✅ Backward Compatibility

[11.3.6] - 2026-03-08 - Transazione Atomica nell'Esecuzione delle Fixtures e Fix Rollback

Questa patch introduce l'esecuzione atomica delle fixtures tramite una transazione globale nel FixturesManager, e corregge il comportamento del TransactionManager::rollback() che non verificava lo stato attivo della transazione prima di eseguire il rollback sul database.

🐛 Bug Fixes

TransactionManager::rollback() — Guardia su transazione attiva

Il metodo rollback() eseguiva $this->adapter->rollbackTransaction() incondizionatamente, senza verificare se una transazione fosse effettivamente aperta. Questo poteva causare un errore del driver database in caso di chiamata su connessione senza transazione attiva.

Modifica:

File modificati:

✨ Miglioramenti

FixturesManager::run() — Esecuzione atomica tramite transazione globale

L'esecuzione delle fixtures avveniva senza una transazione globale: ogni save() apriva e chiudeva la propria transazione autonomamente. In caso di errore a metà esecuzione, i record già inseriti dai fixture precedenti rimanevano nel database.

Ora run() apre una transazione prima di eseguire i fixture e la committa solo al termine di tutti. Se un save() fallisce internamente, esegue il rollback dell'intera transazione e rilancia l'eccezione, che propaga naturalmente al sisma script.

File modificati:

Console/sisma — Path con DIRECTORY_SEPARATOR

Il file di avvio della console usava / hardcoded per costruire i path di configurazione e autoload, causando potenziali problemi su sistemi Windows.

File modificati:

🧪 Test

ScaffoldingManagerTest::testDoubleExecution — Path con DIRECTORY_SEPARATOR

Il messaggio di eccezione atteso nel test usava \ hardcoded per il path, causando il fallimento del test su sistemi Linux/macOS dove il separatore è /.

File modificati:

✅ Backward Compatibility

[11.3.5] - 2026-03-04 - Ripristino Compatibilità PHP in ModuleManager

Questa patch ripristina il codice precedente nel metodo setApplicationModuleByClassName() della classe ModuleManager, rimuovendo l'uso di array_first() introdotto involontariamente nella versione 11.3.4. La funzione array_first() è disponibile solo a partire da PHP 8.5, incompatibile con il requisito minimo del framework (PHP 8.3).

🐛 Bug Fixes

Ripristino accesso diretto all'array in ModuleManager::setApplicationModuleByClassName()

Il commit della versione 11.3.4 aveva sostituito $classNameParts[0] con array_first($classNameParts), funzione introdotta in PHP 8.5 e non disponibile in PHP 8.3 e 8.4.

Ripristino:

File modificati:

✅ Backward Compatibility

[11.3.4] - 2026-03-03 - Impostazione Modulo nella Classe ErrorHandler

Questa patch release corregge un bug per cui la classe ErrorHandler non impostava il modulo applicativo prima di invocare i controller di errore, causando un fallimento nella risoluzione delle view di errore.

🐛 Bug Fixes

Impostazione del modulo nei metodi di gestione errori

I metodi pubblici di ErrorHandler chiamavano i controller di errore senza prima impostare il modulo tramite ModuleManager, a differenza di quanto avviene nel Dispatcher. Il sistema di rendering non riusciva quindi a individuare il percorso corretto delle view.

Modifiche applicate:

File modificati:

🧪 Test

Correzione BackupManagerTest con estensione ZIP non disponibile

Il tearDown() accedeva alla proprietà tipizzata $testDir anche quando setUp() aveva chiamato markTestSkipped() prima di inizializzarla (assenza dell'estensione ZIP), causando un errore Typed property must not be accessed before initialization.

Fix: l'assegnazione di $testDir è stata spostata prima del controllo sull'estensione, garantendo che la proprietà sia sempre inizializzata prima che tearDown() venga eseguito.

File modificati:

✅ Backward Compatibility

[11.3.3] - 2026-02-22 - Ripristino Proprietà project nella Classe Config

Questa patch release corregge un errore introdotto nella versione 11.3.2, dove la proprietà $project era stata erroneamente rimossa dalla classe Config nonostante venisse ancora utilizzata dal FrameworkController.

🐛 Bug Fixes

Ripristino di Config::$project

La proprietà $project era stata inclusa per errore nell'elenco delle proprietà "orfane" rimosse nella versione 11.3.2. In realtà viene letta a runtime in FrameworkController::throwableError() e FrameworkController::nonThrowableError() per popolare la variabile di template $vars['project'] nella pagina di errore visibile.

File modificati:

✅ Backward Compatibility

[11.3.2] - 2026-02-21 - Spostamento Fixtures nella Console

Questa patch release rifattorizza il sistema di esecuzione delle fixtures, spostandolo dal contesto HTTP (Dispatcher) al contesto CLI (Console). Il comportamento delle fixtures resta invariato: cambiano solo il punto di invocazione e la collocazione del codice. Include inoltre la documentazione del sistema di Upgrade introdotto nella versione 11.3.0.

🔧 Refactoring

Migrazione delle Fixtures dal Dispatcher alla Console

Le fixtures erano una funzionalità nata quando il framework non disponeva di una console CLI. Venivano eseguite tramite un endpoint HTTP (/fixtures), integrato nel Dispatcher e nel RouteResolver. Con l'introduzione della console, questa collocazione risultava architetturalmente inadeguata.

Nuovo comando CLI: 

php SismaFramework/Console/sisma fixtures

File creati:

File modificati:

File eliminati:

Modifiche al FixturesManager:

Pulizia proprietà orfane nella classe Config

Rimosse 10 proprietà dalla classe Config che non venivano mai lette a runtime tramite $config->proprietà. Queste proprietà esistevano come mapping delle corrispondenti costanti in config.php, ma nessun codice PHP le accedeva — le costanti servono esclusivamente come building block per la composizione di altre costanti e restano invariate.

Proprietà rimosse: $adapters, $assets, $cache, $core, $defaultController, $logs, $project, $resources, $thisDirectory, $directoryUp

✅ Test

📖 Documentazione

✅ Backward Compatibility

[11.3.1] - 2026-02-11 - Correzione Percorsi Cross-Platform nell'Autoloader

Questa patch release corregge un bug nell'Autoloader che impediva il caricamento delle classi mappate tramite AUTOLOAD_NAMESPACE_MAPPER e AUTOLOAD_CLASS_MAPPER su sistemi Linux/macOS.

🐛 Bug Fixes

Correzione Conversione Separatori di Directory nei Mapper dell'Autoloader

Corretti i metodi mapNamespace() e mapClass() in Autoloader.php per convertire correttamente i backslash nei percorsi provenienti dalle costanti di configurazione:

Scenario del bug:

  1. La configurazione AUTOLOAD_NAMESPACE_MAPPER contiene percorsi con backslash (es. "plugins\PHPMailer\src")
  2. Su Windows, i backslash funzionano come separatori di directory, mascherando il problema
  3. Su Linux/macOS (es. dentro un container Docker), DIRECTORY_SEPARATOR è /
  4. Il percorso risultante conteneva backslash letterali: /var/www/html/plugins\PHPMailer\src/PHPMailer.php
  5. file_exists() falliva perché il percorso non era valido su Linux

Dopo la correzione:

✅ Backward Compatibility

📊 Impatto

[11.3.0] - 2026-02-08 - Sistema di Upgrade Automatico e Miglioramenti ORM Fulltext

Questa release introduce un sistema completo di upgrade automatico che consente di migrare moduli tra versioni major del framework applicando automaticamente le trasformazioni necessarie per i breaking changes. Inoltre, viene aggiunto il parametro TextSearchMode ai metodi di ricerca fulltext dell'ORM, consentendo un controllo esplicito sulla modalità di ricerca testuale.

✨ Nuove Funzionalità

  {
    "name": "ModuleName",
    "version": "1.0.0",
    "framework_version": "11.0.0",
    "description": "Module description",
    "authors": ["Author Name"],
    "requires": {
      "sismaframework": ">=11.0.0"
    }
  }

| Trasformazione | Confidence | Note | |----------------|------------|------| | Static→Instance | 70-75% | Alta per index.php, warning per altri file | | ReturnType void→bool | 80-85% | Rilevamento automatico indentazione | | Response constructor | 65-70% | Warning per pattern complessi | | Method renaming | 90% | Alta affidabilità |

🛡️ Sicurezza e Affidabilità

📊 Report e Trasparenza

🔧 Exceptions

📋 Esempi di Utilizzo

# Preview upgrade (raccomandato come primo step)
php Console/sisma upgrade Blog --to=11.0.0 --dry-run

# Applicazione upgrade dopo review
php Console/sisma upgrade Blog --to=11.0.0

# Upgrade da versione specifica
php Console/sisma upgrade Blog --from=10.1.7 --to=11.0.0

# Salta file critici per review manuale
php Console/sisma upgrade Blog --to=11.0.0 --skip-critical

# Output minimale
php Console/sisma upgrade Blog --to=11.0.0 --quiet

🔄 Estensibilità

Il sistema è progettato per essere facilmente estensibile:

  1. Nuova Major Version: Creare Upgrade11to12Strategy.php implementando UpgradeStrategyInterface
  2. Nuove Trasformazioni: Creare transformer implementando TransformerInterface
  3. Custom Strategies: Sistema a plugin completamente estensibile

🔧 Miglioramenti ORM

Aggiunta parametro TextSearchMode alla ricerca fulltext

Aggiunto il parametro TextSearchMode ai metodi di ricerca fulltext per consentire un controllo esplicito sulla modalità di ricerca testuale:

Motivazione:

⚠️ Limitazioni

🛠️ Mitigazioni

[11.2.0] - 2026-01-30 - Aggiornamento Requisiti PHP e PHPUnit

Questa minor release aggiorna i requisiti minimi del framework a PHP 8.3 e PHPUnit 12, allineandosi con le versioni attivamente supportate e sfruttando le feature moderne del linguaggio già presenti nel codebase. Inoltre, il processo di installazione ora crea automaticamente la struttura del modulo applicativo.

✨ Nuove Funzionalità

Creazione Automatica Struttura Modulo durante Installazione

Il comando install ora crea automaticamente la struttura completa del modulo applicativo:

Struttura creata automaticamente: 

MyProject/
├── Application/
│   ├── Controllers/
│   ├── Entities/
│   ├── Enumerations/
│   ├── Forms/
│   ├── Models/
│   └── Views/
├── Config/
│   └── configFramework.php
├── Public/
│   └── index.php
├── Cache/
├── Logs/
├── filesystemMedia/
├── .htaccess
└── composer.json

Vantaggi:

🔧 Aggiornamenti Requisiti

PHP 8.3 come Requisito Minimo

Motivazione:

PHPUnit 12 come Requisito per i Test

Motivazione:

🔍 Miglioramenti Qualità Codice

Completamento Attributi #[\Override]

Aggiunti gli attributi #[\Override] mancanti ai metodi che sovrascrivono metodi di classi parent o implementano metodi di interfacce:

Vantaggi:

🧪 Miglioramenti Test Suite

Conformità PHPUnit 12

Aggiornati i test per conformarsi alle best practice di PHPUnit 12:

Riorganizzazione Configurazione PHPUnit

Vantaggi:

📖 Utilizzo

# Esecuzione test (PHPUnit trova automaticamente phpunit.xml)
./vendor/bin/phpunit

# Esecuzione test senza code coverage
./vendor/bin/phpunit --no-coverage

# Esecuzione test con coverage (richiede Xdebug)
XDEBUG_MODE=coverage ./vendor/bin/phpunit

✅ Backward Compatibility

📚 Aggiornamento Documentazione e Materiali Promozionali

Tutti i riferimenti alla versione PHP sono stati aggiornati da 8.1 a 8.3 nei seguenti file:

📊 File Modificati

FileTipoDescrizione
composer.jsonModificatoRequisiti PHP ≥8.3, PHPUnit ^12.0
.gitignoreModificatoAggiunto composer.lock
Console/Services/Installation/InstallationManager.phpModificatoAggiunta chiamata a initializeModule()
Console/Commands/InstallationCommand.phpModificatoAggiornato output installazione
Core/CustomTypes/FormFilterErrorCollection.phpModificatoAggiunto #[\Override]
Core/HelperClasses/SismaLogger.phpModificatoAggiunto #[\Override] ai metodi PSR-3
Core/HelperClasses/SismaLogReader.phpModificatoAggiunto #[\Override]
Orm/CustomTypes/SismaDate.phpModificatoAggiunto #[\Override]
Orm/CustomTypes/SismaDateTime.phpModificatoAggiunto #[\Override]
Orm/CustomTypes/SismaTime.phpModificatoAggiunto #[\Override]
Orm/BaseClasses/BaseResultSet.phpModificatoAggiunto #[\Override] ai metodi Iterator
Orm/ExtendedClasses/SelfReferencedModel.phpModificatoAggiunto #[\Override]
phpunit.xmlNuovo (rinominato)Configurazione PHPUnit spostata nella root
Tests/configuration.xmlRimossoSostituito da phpunit.xml
Tests/Console/Services/Installation/InstallationManagerTest.phpModificatoAggiunto test per verifica creazione modulo
Tests/Core/BaseClasses/BaseControllerTest.phpModificatocreateMock → createStub
Tests/Core/HelperClasses/ErrorHandlerTest.phpModificatocreateMock → createStub
Tests/Core/Services/RenderServiceTest.phpModificatocreateMock → createStub
Tests/Core/Services/RouterServiceTest.phpModificatocreateMock → createStub
TestsApplication/Controllers/SampleController.phpModificatoAggiunto #[\Override]

[11.1.0] - 2026-01-21 - Input Interattivo per Configurazione Database

Questa minor release aggiunge la possibilità di configurare i parametri del database in modo interattivo durante l'installazione del framework, migliorando l'esperienza utente senza compromettere la retrocompatibilità.

✨ Nuove Funzionalità

Input Interattivo da Console

Aggiunto nuovo trait InteractiveInputTrait per gestire l'input utente dalla console:

Configurazione Database Interattiva

Migliorato InstallationCommand con richiesta interattiva dei parametri database:

📖 Utilizzo

# Installazione con richiesta interattiva database
php SismaFramework/Console/sisma install MyProject

# Installazione senza configurazione database
php SismaFramework/Console/sisma install MyProject --skip-db

# Installazione con parametri da command line (comportamento precedente)
php SismaFramework/Console/sisma install MyProject --db-host=localhost --db-name=mydb --db-user=root

Esempio di output interattivo: 

Installing SismaFramework project: MyProject

Database Configuration (optional)
Press Enter to skip each field or use defaults.

Do you want to configure database settings? [y/N]: y
Database Host [127.0.0.1]: localhost
Database Port [3306]: 3306
Database Name []: myproject_db
Database Username []: root
Database Password: ********

Creating project structure...

✅ Backward Compatibility

🔧 Dettagli Tecnici

  • Il trait InteractiveInputTrait può essere riutilizzato da altri comandi o moduli
  • Su Windows, askSecret() non nasconde l'input (limitazione del sistema)
  • Su Linux/macOS, askSecret() utilizza stty -echo per nascondere l'input

📊 File Modificati

FileTipoDescrizione
Console/Traits/InteractiveInputTrait.phpNuovoTrait per input interattivo
Console/Commands/InstallationCommand.phpModificatoAggiunta configurazione interattiva DB

[11.0.5] - 2026-01-21 - Correzione Sostituzione Costanti File Configurazione

Questa patch release corregge un bug nel processo di installazione che impediva la corretta sostituzione delle costanti nel file di configurazione quando queste utilizzavano apici doppi invece di apici singoli.

🐛 Bug Fixes

Correzione Regex Sostituzione Costanti

Corrette le espressioni regolari in InstallationManager.php per supportare sia apici singoli (') che apici doppi (") nella sostituzione delle costanti:

Scenario del bug:

  1. Il file Config/config.php del framework utilizza apici doppi per le stringhe (es. const PROJECT = "SismaFramework")
  2. Le regex in InstallationManager cercavano solo apici singoli
  3. Durante l'installazione (php SismaFramework/Console/sisma install MyProject), le costanti non venivano sostituite
  4. Il file configFramework.php risultante manteneva i valori originali invece di quelli specificati dall'utente

Dopo la correzione:

  • Le costanti vengono sostituite correttamente indipendentemente dal tipo di apice usato
  • Il processo di installazione funziona sia con file di configurazione che usano apici singoli che doppi
  • Maggiore robustezza e compatibilità del processo di installazione

🧪 Testing

Aggiornamento Test InstallationManager

Aggiornati i test per essere agnostici rispetto al tipo di apice utilizzato:

Esempio di verifica aggiornata: 

// ❌ Prima (verificava solo apici singoli):
$this->assertStringContainsString("const PROJECT = 'MyTestProject'", $content);

// ✅ Dopo (verifica entrambi i tipi di apici):
$this->assertMatchesRegularExpression("/const PROJECT = ['\"]MyTestProject['\"]/", $content);

✅ Backward Compatibility

📊 Impatto

[11.0.4] - 2026-01-17 - Correzione Percorso File di Log

Questa patch release corregge un bug nel file di configurazione del framework dove la costante LOG_PATH puntava a un percorso errato.

🐛 Bug Fixes

Correzione Costante LOG_PATH

Corretto il percorso del file di log nella configurazione predefinita del framework:

Scenario del bug:

  1. La costante LOG_PATH era definita come DIRECTORY_SEPARATOR . 'log.txt'
  2. Questo puntava erroneamente alla root del filesystem (/log.txt su Linux, \log.txt su Windows)
  3. Nella configurazione standard, questa costante non viene modificata durante l'installazione
  4. Il file di log non veniva scritto nella posizione corretta (Sample/Logs/log.txt)

Dopo la correzione:

  • LOG_PATH utilizza correttamente LOG_DIRECTORY_PATH come base del percorso
  • Il file di log viene creato nella directory corretta: {ROOT}/Sample/Logs/log.txt
  • Il sistema di logging funziona correttamente senza necessità di configurazione manuale

✅ Backward Compatibility

📊 Impatto

[11.0.3] - 2026-01-08 - Correzione Installazione File .htaccess

Questa patch release corregge un bug nel processo di installazione che non copiava il file .htaccess necessario per il reindirizzamento verso la directory Public.

🐛 Bug Fixes

Copia File .htaccess Durante Installazione

Aggiunta la copia del file .htaccess durante il processo di installazione automatica:

Scenario del bug:

  1. Utente esegue: php SismaFramework/Console/sisma install MyProject
  2. Il file .htaccess non veniva copiato nella root del progetto
  3. Il web server non riusciva a reindirizzare correttamente le richieste verso Public/index.php
  4. L'applicazione non funzionava correttamente senza configurazione manuale del virtual host

Dopo la correzione:

  • Il file .htaccess viene copiato automaticamente nella root del progetto
  • Il file contiene le regole di reindirizzamento verso Public/ già configurate
  • L'applicazione funziona immediatamente senza configurazione aggiuntiva del web server

Contenuto del file .htaccess: 

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteCond %{QUERY_STRING} fbclid= [NC]
RewriteRule ^(.*)$ /$1? [R=301,L]
RewriteCond %{THE_REQUEST} \ /(.+/)?index\.php\/(.*)$ [NC]
RewriteRule ^(.+/)?index\.php\/(.*)$ /$1$2 [R=301,L]
RewriteCond %{THE_REQUEST} \ /(.+/)?index\.php(.*)$ [NC]
RewriteRule ^(.+/)?index\.php(.*)$ /$1$2 [R=301,L]
RewriteCond %{REQUEST_URI} !^/Public/
RewriteRule ^(.*)$ Public/ [L]
</IfModule>

✅ Backward Compatibility

📊 Impatto

[11.0.1] - 2026-01-06 - Correzioni Processo di Installazione

Questa patch release corregge tre bug critici nel processo di installazione automatica del framework che causavano errori nella generazione del file composer.json e nel riferimento al file di configurazione.

🐛 Bug Fixes

Correzione Formato Nome Composer.json

Corretto il formato del nome del progetto nel file composer.json generato durante l'installazione:

Scenario del bug:

  1. Utente esegue: php SismaFramework/Console/sisma install MyProject
  2. Il file composer.json veniva creato con "name": "myproject" invece di "name": "vendor/myproject"
  3. Questo causava errori durante composer install o composer update perché il formato non era valido

Dopo la correzione:

  • Il file composer.json ha il formato nome corretto: "vendor/myproject"
  • Il comando composer install funziona senza errori

Correzione Percorso configFramework.php in index.php

Corretto il percorso del file di configurazione nel file Public/index.php generato durante l'installazione:

Scenario del bug:

  1. Durante l'installazione, il file Config/configFramework.php viene creato nella root del progetto
  2. Il file Public/index.php veniva modificato per cercare il config in SismaFramework/Config/configFramework.php
  3. L'applicazione non trovava il file di configurazione causando errori fatali

Dopo la correzione:

  • Il file Public/index.php include correttamente dirname(__DIR__) . DIRECTORY_SEPARATOR . 'Config' . DIRECTORY_SEPARATOR . 'configFramework.php'
  • Il percorso Autoload viene correttamente modificato in SismaFramework/Autoload
  • L'applicazione trova il file di configurazione e si avvia correttamente

Correzione ROOT_PATH in configFramework.php

Corretto il numero di livelli di risalita della costante ROOT_PATH nel file di configurazione installato:

Scenario del bug:

  1. Il file originale SismaFramework/Config/config.php si trova in root/SismaFramework/Config/config.php
  2. La ROOT_PATH sale di due livelli: SismaFramework/Config → SismaFramework → root (corretto per il framework)
  3. Il file installato Config/configFramework.php si trova in root/Config/configFramework.php
  4. Con due livelli di risalita: Config → root → parent (errato)
  5. Con un livello di risalita: Config → root (corretto)

Dopo la correzione:

  • La costante ROOT_PATH punta correttamente alla root del progetto
  • Tutti i percorsi derivati (cache, log, etc.) funzionano correttamente

🧪 Testing

Aggiornamento Test Suite

Aggiornati i test per riflettere le correzioni apportate:

- ❌ Prima: Verificava presenza di 'SismaFramework' . DIRECTORY_SEPARATOR . 'Config'

- ✅ Dopo: Verifica presenza di 'Config' . DIRECTORY_SEPARATOR . 'configFramework.php'

- ❌ Prima: Verificava nome come 'mytestproject'

- ✅ Dopo: Verifica nome come 'vendor/mytestproject'

✅ Backward Compatibility

 1. Aggiornare manualmente composer.json per aggiungere il prefisso vendor/

2. Verificare che Public/index.php punti a Config/configFramework.php e non a SismaFramework/Config/configFramework.php 3. Verificare che ROOT_PATH in Config/configFramework.php salga di un solo livello

📊 Impatto

[11.0.0] - 2026-01-02 - Rifattorizzazione Architetturale e Semplificazione API

Questa major release introduce miglioramenti architetturali significativi: rifattorizzazione completa di BaseForm con principi SOLID, semplificazione API Response attraverso rimozione del metodo pubblico setResponseType(), e implementazione completa dello standard PSR-3 per il logging con supporto per logger di terze parti.

La release introduce breaking changes: il metodo astratto customFilter() di BaseForm ora ritorna bool invece di void, il metodo pubblico setResponseType() di Response è stato rimosso in favore dell'immutabilità tramite constructor injection, e le classi ErrorHandler e Debugger sono state trasformate da statiche a di istanza per migliorare testabilità e dependency injection.

🏗️ Architettura

Vantaggi della rifattorizzazione:

  • Ogni classe ha una singola, chiara responsabilità (SRP)
    • Codice più testabile con dipendenze iniettabili
    • Migliore leggibilità e manutenibilità
    • Facilita l'estensione con validatori o filtri custom
    • Riduce la complessità della classe BaseForm da oltre 400 linee a circa 200
 
  public function __construct(
      ?BaseEntity $baseEntity = null,
      DataMapper $dataMapper = new DataMapper(),
      FilterManager $filterManager = new FilterManager(),
      ?FormValidator $formValidator = null,
      EntityResolver $entityResolver = new EntityResolver()
  )

Questo permette di iniettare implementazioni custom per testing o estensioni.

Vantaggi dell'implementazione PSR-3:

Esempio di utilizzo con logger custom: 

  use Monolog\Logger;
  use Monolog\Handler\StreamHandler;
  
  // Logger di terze parti (Monolog)
  $monolog = new Logger('app');
  $monolog->pushHandler(new StreamHandler('path/to/your.log', Logger::WARNING));
  
  // Injection in ErrorHandler
  $errorHandler = new ErrorHandler(logger: $monolog);
  $errorHandler->registerNonThrowableErrorHandler();
 
    // Prima (10.x):
    ErrorHandler::disableErrorDisplay();
    ErrorHandler::handleNonThrowableError();
    Debugger::startExecutionTimeCalculation();
    
    // Dopo (11.0.0):
    $errorHandler = new ErrorHandler();
    $errorHandler->disableErrorDisplay();
    $errorHandler->registerNonThrowableErrorHandler();
    $debugger = new Debugger();
    $debugger->startExecutionTimeCalculation();
    $dispatcher = new Dispatcher(debugger: $debugger);

Motivazione della trasformazione:

Vantaggi del Pattern Facade + Singleton:

Utilizzo nei Controller: 

  class ProductController extends BaseController
  {
      public function index(): Response
      {
          // Sintassi di istanza (nuovo, preferito):
          return $this->render->generateView('product/index', $this->vars);
          
          // Sintassi statica (legacy, ancora supportato):
          return Render::generateView('product/index', $this->vars);
      }
      
      public function create(): Response
      {
          // Sintassi di istanza per router:
          return $this->router->redirect('product/list');
          
          // Sintassi statica (legacy):
          return Router::redirect('product/list');
      }
  }
 
  protected RenderService $router;
  protected RenderService $render;
  
  public function __construct(DataMapper $dataMapper = new DataMapper(), Debugger $debugger = new Debugger())
  {
      $this->dataMapper = $dataMapper;
      $this->debugger = $debugger;
      $this->router = RouterService::getInstance();
      $this->render = RenderService::getInstance();
      // ...
  }

Questo permette di utilizzare $this->render e $this->router come istanze in tutti i controller che estendono BaseController.

💥 Breaking Changes

Prima (10.x): 

  $response = new Response();
  $response->setResponseType(ResponseType::httpNotFound);

Dopo (11.0.0): 

  $response = new Response(ResponseType::httpNotFound);

Motivazione:

  • Promuove immutabilità: un oggetto Response dovrebbe nascere con un tipo e mantenerlo
    • Proprietà $responseType ora readonly (PHP 8.1+) per garantire immutabilità a livello di linguaggio
    • Semplifica API: constructor injection è più pulito e type-safe
    • Elimina metodi non utilizzati: nessun codice nel framework usava setResponseType() dopo creazione oggetto
    • Migliora testabilità: stato dell'oggetto più prevedibile

Impatto: Il metodo setResponseType() non è più disponibile. Utilizzare il costruttore per impostare il response type.

Azione richiesta:

  • Sostituire chiamate a setResponseType() passando il ResponseType al costruttore
    • Se necessario modificare il response type, creare una nuova istanza di Response

Prima (10.x): 

  abstract protected function customFilter(): void;

Dopo (11.0.0): 

  abstract protected function customFilter(): bool;

Motivazione: Il nuovo tipo di ritorno bool permette al metodo customFilter() di contribuire al risultato finale di validazione del form. Ritornando true se la validazione custom ha successo o false in caso di errori, si ottiene un'API più coerente e un flusso di validazione più chiaro.

Impatto: Tutte le classi che estendono BaseForm devono essere aggiornate per ritornare un valore booleano dal metodo customFilter().

Azione richiesta:

  • Aggiungere return true; alla fine del metodo customFilter() se non ci sono errori di validazione custom
    • Ritornare false quando la validazione custom fallisce
    • Esempio:
    // Prima (10.x):
    protected function customFilter(): void
    {
        if ($this->entity->startDate > $this->entity->endDate) {
            $this->formFilterError->startDateError = true;
        }
    }

    // Dopo (11.0.0):
    protected function customFilter(): bool
    {
        if ($this->entity->startDate > $this->entity->endDate) {
            $this->formFilterError->startDateError = true;
            return false;
        }
        return true;
    }

Prima (10.x): 

  ErrorHandler::disableErrorDisplay();
  ErrorHandler::handleNonThrowableError();
  Debugger::startExecutionTimeCalculation();

Dopo (11.0.0): 

  $errorHandler = new ErrorHandler();
  $errorHandler->disableErrorDisplay();
  $errorHandler->registerNonThrowableErrorHandler();
  $debugger = new Debugger();
  $debugger->startExecutionTimeCalculation();

Motivazione:

  • Eliminazione dello stato globale
    • Miglioramento della testabilità attraverso dependency injection
    • Conformità ai principi SOLID
    • Possibilità di iniettare logger custom conformi a PSR-3

Impatto: Il file Public/index.php deve essere aggiornato per creare istanze delle classi invece di usare metodi statici. Tutte le chiamate statiche a ErrorHandler e Debugger devono essere convertite a chiamate di istanza.

Azione richiesta:

  • Aggiornare il file Public/index.php per creare istanze di ErrorHandler e Debugger
    • Se si desidera utilizzare un logger custom (es. Monolog), iniettarlo nel costruttore di ErrorHandler
    • Verificare che non esistano altre chiamate statiche a queste classi nel codebase

Prima (10.x): 

  $iv = Encryptor::createInizializationVector();

Dopo (11.0.0): 

  $iv = Encryptor::createInitializationVector();

Motivazione: Correzione di un typo nel nome del metodo per migliorare la coerenza del codebase e facilitare l'uso dell'API.

Impatto: Questo è un potenziale breaking change se il metodo veniva chiamato direttamente nel codice utente. Il metodo è principalmente utilizzato internamente dal framework (in DataMapper per proprietà crittografate), ma potrebbe essere stato usato in codice custom per crittografia manuale.

Azione richiesta:

  • Cercare tutte le occorrenze di createInizializationVector nel proprio codebase
    • Sostituire con createInitializationVector (con la "t" invece della "z")
    • Verificare il corretto funzionamento delle operazioni di crittografia

✨ Miglioramenti

Questo facilita il debugging e rende più chiaro agli sviluppatori il motivo degli errori di configurazione.

🧪 Testing

Copertura totale: +603 linee di test per garantire affidabilità del nuovo pattern architetturale.

📝 Documentazione

🔄 Compatibilità

Questa è una major release (11.0.0) che introduce breaking changes. L'aggiornamento richiede modifiche al codice esistente:

📋 Checklist di Migrazione da 10.x a 11.0.0

[10.1.7] - 2025-12-21 - Correzione Bug buildPropertiesConditions e Test Suite

Questa patch release corregge un bug critico introdotto nella versione 10.1.0 nel metodo buildPropertiesConditions di DependentModel e SelfReferencedModel, che impediva il corretto override del metodo di BaseModel. Inoltre corregge errori sistematici nella test suite che utilizzavano nomi di proprietà in formato snake_case invece di camelCase.

🐛 Bug Fixes

Correzione Typo Nome Metodo buildPropertiesConditions

Corretto un errore di battitura nel nome del metodo introdotto nella versione 10.1.0 che impediva l'override corretto del metodo di BaseModel:

Scenario del bug:

  1. Nella versione 10.1.0 è stata introdotta la feature "Estensione Query Dinamiche ORM a Tutte le Proprietà"
  2. Il metodo in BaseModel si chiamava correttamente buildPropertiesConditions (plurale)
  3. Il metodo in DependentModel e SelfReferencedModel era stato erroneamente chiamato buildPropertyConditions (singolare)
  4. A causa del nome diverso, non avveniva l'override del metodo
  5. Questo causava due problemi critici:

Conseguenze del bug:

  • Per le proprietà ReferencedEntity, il quarto parametro ($isForeignKey) non veniva impostato a true
  • Questo impediva l'aggiunta automatica del suffisso _id ai nomi delle colonne foreign key
  • Per le proprietà builtin (string, int, bool, etc.), il bind type era erroneamente typeEntity invece del tipo corretto
  • Query SQL potenzialmente malformate e errori di binding dei parametri

Impatto della correzione:

  • Il metodo ora fa correttamente override, utilizzando l'implementazione specializzata per DependentModel/SelfReferencedModel
  • Il quarto parametro di appendCondition() viene passato correttamente: $propertyValue instanceof ReferencedEntity
  • I bind types vengono determinati dinamicamente tramite DataType::fromReflection() invece di essere hardcodati
  • Le query SQL vengono costruite correttamente con i suffissi _id per le foreign key

Correzione Test Suite: Convenzione Naming Proprietà

Corretti errori sistematici nella test suite che utilizzavano nomi di proprietà in formato snake_case (convenzione database) invece di camelCase (convenzione PHP):

Motivo del problema:

Esempio di correzione: 

// ❌ PRIMA (errato - nome colonna database):
$posts = $postModel->getEntityCollectionByEntity(['author_id' => $user]);

// ✅ DOPO (corretto - nome proprietà PHP):
$posts = $postModel->getEntityCollectionByEntity(['author' => $user]);

Convenzione del framework:

  • Magic methods: getByAuthor($user) → genera internamente ['author' => $user] (camelCase)
  • Metodi espliciti: devono ricevere ['author' => $user] (camelCase), non ['author_id' => $user]
  • La conversione snake_case → camelCase avviene automaticamente solo nella costruzione delle query SQL

🧪 Testing

Nuovi Test per Prevenire Regressioni

Aggiunti 2 nuovi test in DependentModelTest.php che avrebbero catturato il bug della versione 10.1.0:

Copertura test totale:

  • 2 nuovi test aggiunti
  • 18 test esistenti corretti (convenzione naming)
  • Tutti i test ora passano correttamente

✅ Backward Compatibility

📊 Impatto

🎓 Note per gli Sviluppatori

Quando si utilizzano i metodi getEntityCollectionByEntity(), countEntityCollectionByEntity(), deleteEntityCollectionByEntity(), ricordare che le chiavi dell'array devono essere nomi di proprietà PHP in camelCase, non nomi di colonne database in snake_case: 

// ✅ CORRETTO:
$posts = $postModel->getEntityCollectionByEntity([
    'author' => $user,           // nome proprietà PHP
    'category' => $category,     // nome proprietà PHP
    'isPublished' => true        // nome proprietà PHP
]);

// ❌ ERRATO:
$posts = $postModel->getEntityCollectionByEntity([
    'author_id' => $user,        // nome colonna database - causerà ReflectionException
    'category_id' => $category,  // nome colonna database - causerà ReflectionException
    'is_published' => true       // nome colonna database - causerà ReflectionException
]);

La conversione da camelCase (proprietà PHP) a snake_case (colonne database) avviene automaticamente all'interno del framework tramite NotationManager.

[10.1.6] - 2025-12-20 - Hotfix Costante LOG_DIRECTORY_PATH

Questa patch release corregge un bug critico introdotto nella versione 10.1.5 relativo alla definizione ricorsiva della costante LOG_DIRECTORY_PATH nel file di configurazione.

🐛 Bug Fixes

Correzione Definizione Ricorsiva LOG_DIRECTORY_PATH

Corretto un bug introdotto nella versione 10.1.5 che causava una definizione ricorsiva della costante LOG_DIRECTORY_PATH: 

    // Pattern di sostituzione corretto (linee 115-116):
    "const LOG_DIRECTORY_PATH = SYSTEM_PATH . APPLICATION_PATH . LOGS . DIRECTORY_SEPARATOR;",
    "const LOG_DIRECTORY_PATH = ROOT_PATH . LOGS . DIRECTORY_SEPARATOR;",
 
    $this->assertStringContainsString(
        "const LOG_DIRECTORY_PATH = ROOT_PATH . LOGS . DIRECTORY_SEPARATOR;", 
        $content
    );

Scenario del bug:

  1. Nella versione 10.1.5, la costante LOG_DIRECTORY_PATH era definita usando se stessa: ... . LOG_DIRECTORY_PATH
  2. Questo causava una definizione ricorsiva non valida che avrebbe potuto generare errori a runtime
  3. Il bug era presente sia nel file di configurazione del framework che nel processo di installazione

Impatto della correzione:

  • Il percorso dei log viene ora costruito correttamente utilizzando DIRECTORY_SEPARATOR
  • Sia il file Config/config.php del framework che il processo di installazione automatica utilizzano la definizione corretta
  • I test verificano che la sostituzione durante l'installazione funzioni correttamente

✅ Backward Compatibility

📊 Impatto

[10.1.5] - 2025-12-20 - Correzione Configurazione Framework Post-Installazione

Questa patch release corregge un problema nel processo di installazione automatica che non modificava correttamente alcune costanti del file di configurazione framework nella root del progetto.

🐛 Bug Fixes

Aggiornamento Automatico Costanti in configFramework.php

Corretto il processo di installazione per aggiornare automaticamente le costanti del file configFramework.php creato nella root del progetto durante l'installazione:

1. APPLICATION:

2. REFERENCE_CACHE_DIRECTORY:

3. LOG_DIRECTORY_PATH:

4. MODULE_FOLDERS:

Scenario del problema:

  1. Utente esegue: php SismaFramework/Console/sisma install MyProject
  2. Il file Config/configFramework.php veniva creato nella root del progetto
  3. La costante PROJECT veniva aggiornata correttamente, ma APPLICATION, REFERENCE_CACHE_DIRECTORY, LOG_DIRECTORY_PATH e MODULE_FOLDERS mantenevano i valori del framework originale
  4. Questo causava percorsi errati per cache e log, e riferimenti all'applicazione 'Sample' invece di 'Application'

Dopo la correzione:

  • Il file configFramework.php ha i valori corretti per un nuovo progetto
  • I percorsi di cache e log puntano alla root del progetto invece che al framework
  • L'applicazione è correttamente identificata come 'Application'
  • L'array MODULE_FOLDERS è vuoto, pronto per essere popolato dall'utente

🧪 Testing

Aggiornamento Test InstallationManager

Aggiornati i test per verificare le nuove modifiche al processo di installazione:

- Verifica const APPLICATION = 'Application'

- Verifica const REFERENCE_CACHE_DIRECTORY = ROOT_PATH . CACHE . DIRECTORY_SEPARATOR; - Verifica const LOG_DIRECTORY_PATH = ROOT_PATH . LOGS . LOG_DIRECTORY_PATH; - Verifica const MODULE_FOLDERS = [];

- Aggiunge costanti APPLICATION = 'Sample'

- Aggiunge costanti CACHE, LOGS, SYSTEM_PATH, APPLICATION_PATH, ROOT_PATH - Aggiunge REFERENCE_CACHE_DIRECTORY e LOG_DIRECTORY_PATH con valori originali del framework - Aggiunge MODULE_FOLDERS con 'SismaFramework' nel array - Questo permette ai test di verificare che la trasformazione avvenga correttamente

✅ Backward Compatibility

📊 Impatto

[10.1.4] - 2025-12-14 - Correzioni Installazione e Aggiornamento Test Suite PHPUnit

Questa patch release corregge un bug nel processo di installazione automatica e aggiorna la test suite per conformità alle best practice di PHPUnit 11+ eliminando deprecation notices relative all'uso di mock al posto di stub.

🐛 Bug Fixes

Correzione Riferimento File Configurazione in Installazione

Corretto il processo di installazione automatica per rinominare correttamente il riferimento al file di configurazione in Public/index.php: 

    $patterns = [
        "dirname(__DIR__) . DIRECTORY_SEPARATOR . 'Config'",
        "dirname(__DIR__) . DIRECTORY_SEPARATOR . 'Autoload'",
        "'Config' . DIRECTORY_SEPARATOR . 'config.php'",  // ← NUOVO
    ];
    $replacements = [
        "dirname(__DIR__) . DIRECTORY_SEPARATOR . 'SismaFramework' . DIRECTORY_SEPARATOR . 'Config'",
        "dirname(__DIR__) . DIRECTORY_SEPARATOR . 'SismaFramework' . DIRECTORY_SEPARATOR . 'Autoload'",
        "'Config' . DIRECTORY_SEPARATOR . 'configFramework.php'",  // ← NUOVO
    ];

Scenario del bug:

  1. Utente esegue: php Console/sisma install MyProject
  2. Il file Public/index.php veniva copiato e aggiornato per i path di Autoload e Config
  3. Tuttavia, il riferimento al file di configurazione rimaneva config.php invece di configFramework.php
  4. L'applicazione non riusciva a trovare il file di configurazione causando errori fatali

Dopo la correzione:

  • Il file Public/index.php include correttamente Config/configFramework.php
  • L'installazione automatica produce un progetto immediatamente funzionante

🧪 Testing

Aggiornamento Test Suite per PHPUnit 11+

Aggiornati tutti i file di test per utilizzare createStub() al posto di createMock() quando non vengono configurate aspettative (expectations), eliminando deprecation notices introdotte in PHPUnit 11:

InstallationCommandTest.php: $mockInstallationManager → $installationManagerStub

* ScaffoldCommandTest.php: $mockScaffoldingManager → $scaffoldingManagerStub * ScaffoldingManagerTest.php: $configMock → $configStub (2 occorrenze) * InstallationManagerTest.php: Rimossi setAccessible(true) deprecati (PHP 8.1+)

* BaseFixtureTest.php: $configMock → $configStub, $dataMapperMock → stub

* BaseFormTest.php: $configMock → $configStub, $dataMapperMock → stub, $requestMock → stub * FilterTypeTest.php, AutoloaderTest.php, ConfigTest.php, DebuggerTest.php, DispatcherTest.php * EncryptorTest.php, FilterTest.php, FixturesManagerTest.php, LoggerTest.php * ModuleManagerTest.php, NotationManagerTest.php

* AdapterMysqlTest.php, BaseEntityTest.php, BaseModelTest.php, SismaCollectionTest.php

* DependentModelTest.php, ReferencedEntityTest.php, SelfReferencedEntityTest.php, SelfReferencedModelTest.php * CacheTest.php, DataMapperTest.php, ErrorHandlerTest.php, ProcessedEntitiesCollectionTest.php, QueryTest.php * JoinEagerLoadingTest.php, ResultSetMysqlTest.php

* BasePermissionTest.php, BaseVoterTest.php, AuthenticationTest.php 
    // ❌ Prima (PHPUnit 11 deprecation warning):
    $configMock = $this->createMock(Config::class);
    $configMock->expects($this->any())  // ← expects() su stub non necessario
            ->method('__get')
            ->willReturnMap([...]);
    
    // ✅ Dopo (conforme PHPUnit 11+):
    $configStub = $this->createStub(Config::class);
    $configStub->method('__get')  // ← solo configurazione valori di ritorno
            ->willReturnMap([...]);

🔧 Refactoring

Pulizia Codice InstallationManager

Refactorizzata formattazione del codice in InstallationManager.php per migliorare leggibilità:

Impatto: Nessun cambiamento funzionale, solo miglioramento della manutenibilità.

✅ Backward Compatibility

📊 Metriche

[10.1.3] - 2025-12-10 - Correzione Parsing Argomenti CLI

Questa patch release corregge un bug critico nel sistema di parsing degli argomenti posizionali dei comandi CLI che impediva il corretto funzionamento del comando install.

🐛 Bug Fixes

Parsing Dinamico Argomenti Posizionali CLI

Corretto bug nel CommandDispatcher che utilizzava nomi hardcodati per gli argomenti posizionali, causando incompatibilità tra comandi diversi:

Scenario del bug:

  1. Utente esegue: php Console/sisma install MyProject
  2. CommandDispatcher assegnava l'argomento come ['entity' => 'MyProject']
  3. InstallationCommand cercava getArgument('projectName') → null
  4. Il comando falliva con errore "Project name is required"

Dopo la correzione:

  1. CommandDispatcher assegna: ['0' => 'MyProject']
  2. InstallationCommand legge getArgument('0') → 'MyProject'
  3. Il comando funziona correttamente

🧪 Testing

✅ Backward Compatibility

📊 Impatto

[10.1.2] - 2025-12-10 - Normalizzazione Gestione Slash nei Path

Questa patch release migliora la robustezza della gestione dei path nel router attraverso la normalizzazione automatica degli slash, eliminando potenziali bug da doppi slash o slash mancanti.

🔧 Refactoring

Correzioni PHPStan per Qualità del Codice

Risolti warning di analisi statica segnalati da PHPStan per migliorare la qualità e la correttezza del codice:

Normalizzazione Automatica Slash in Router

Migliorata la gestione dei path nel Router per rendere più robusta e consistente la concatenazione degli URL:

- ❌ Prima: La responsabilità di aggiungere / era del chiamante (concatenateMetaUrl('/path'))

- ✅ Dopo: Il metodo normalizza automaticamente il path (concatenateMetaUrl('path') → /path)

- Idempotenza: rtrim() rende l'operazione sempre sicura

- Prevenzione doppi slash: eliminati potenziali path malformati come /meta//url - API più intuitiva: non serve più passare / manualmente

- Prima: Router::concatenateMetaUrl('/' . $this->pathController)

- Dopo: Router::concatenateMetaUrl($this->pathController)

🧪 Testing

✅ Backward Compatibility

📊 Impatto

[10.1.1] - 2025-12-06 - Supporto HTTP Range Requests e Miglioramenti API Response

Questa patch release corregge un bug critico di conformità agli standard HTTP che impediva la riproduzione di video in Safari. Implementato il supporto completo per HTTP Range Requests (RFC 7233) con gestione di 206 Partial Content e 416 Range Not Satisfiable. Migliorata l'API della classe Response con constructor injection.

🐛 Bug Fixes

Supporto HTTP Range Requests per Streaming Media

Corretto bug critico nel serving di file statici che causava la mancata riproduzione di video in Safari:

Scenario del bug:

  1. Safari richiede un video con header Range: bytes=0-1023
  2. Il server ignorava l'header e restituiva 200 OK con l'intero file
  3. Safari rifiutava di riprodurre il video
  4. Impossibilità di fare seek/skip nei file multimediali

Casi d'uso risolti:

🎨 Refactoring

Response Constructor Injection

Migliorata l'API della classe Response:

🧪 Testing

🔧 Dettagli Tecnici

[10.1.0] - 2025-12-02 - Strumenti CLI per Scaffolding, Installazione e Rifatorizzazione Dispatcher

Benvenuti alla release 10.1.0, una delle più ricche di novità nella storia del framework! Utility CLI rivoluzionano il flusso di sviluppo quotidiano, con scaffolding automatico e installazione guidata che accelerano drasticamente la creazione di nuovi progetti. Ottimizzato profondamente il Dispatcher attraverso una rifatorizzazione completa seguendo i principi SOLID, separando le responsabilità in sette classi specializzate che rendono il codice più manutenibile e testabile.

Nascono nuove funzionalità per l'ORM: le funzioni di aggregazione SQL (AVG, MAX, MIN, SUM) permettono ora query analitiche avanzate con supporto per DISTINCT, alias, subquery e aggregazioni multiple, mentre l'estensione del sistema di query dinamiche con metaprogrammazione a tutte le proprietà (non più solo entità referenziate) riduce drasticamente la necessità di scrivere metodi repository ripetitivi generando automaticamente query type-safe, e il supporto completo per JOIN SQL con eager loading gerarchico multi-entità risolve definitivamente il problema N+1 delle query supportando relazioni nested a più livelli con dot notation e sintassi array.

Comandi CLI di scaffolding generano automaticamente l'intero stack CRUD (Controller, Model, Form, Views) a partire da un'Entity esistente, mentre il sistema di installazione configura progetti completi in pochi secondi. Oltre 400 linee di nuovi test garantiscono una copertura completa di tutte le nuove funzionalità, assicurando robustezza e affidabilità.

Molto è stato fatto anche sul fronte architetturale: la rifatorizzazione del Dispatcher riduce la complessità ciclomatica da oltre 400 linee a meno di 200, creando sette nuovi file di helper classes che gestiscono routing, factory dei controller, parsing degli argomenti e gestione delle risorse statiche. Pattern consolidati come Command/Manager vengono applicati sistematicamente ai comandi CLI, con dependency injection e gestione centralizzata delle eccezioni.

Livello enterprise raggiunto con le funzioni di aggregazione ORM: AVG, MAX, MIN e SUM supportano ora DISTINCT, alias personalizzati, subquery e aggregazioni multiple sulla stessa query, portando l'ORM a competere con i framework più evoluti. Estesa significativamente anche la documentazione, con due nuove guide complete per scaffolding e installazione automatica.

Architettura completamente rinnovata: il Dispatcher è stato suddiviso in sette classi specializzate (RouteResolver, ControllerFactory, ActionArgumentsParser, ResourceHandler, RouteInfo, FixturesManager, ResourceMaker) che seguono i principi SOLID e facilitano manutenibilità ed estensibilità future.

Notevole il numero di miglioramenti introdotti in questa release, che rappresenta un punto di svolta nella maturità del framework. Dedichiamo questa versione a tutti gli sviluppatori che quotidianamente utilizzano SismaFramework per creare applicazioni robuste e scalabili.

Nuove possibilità si aprono con questi strumenti professionali: template personalizzabili per lo scaffolding, configurazione database da CLI, protezione contro sovrascritture accidentali e auto-detection intelligente del tipo di Model più appropriato.

Ottima base per futuri sviluppi: questa release pone le fondamenta per ulteriori miglioramenti al sistema di scaffolding e all'ORM, con possibilità di estensione illimitate che verranno esplorate nelle prossime versioni.

Finalmente, dopo mesi di lavoro intenso, possiamo dire che il framework ha raggiunto un livello di maturità che lo rende adatto anche a progetti complessi e mission-critical.

Ricordiamo che questa release è completamente retrocompatibile e l'aggiornamento è fortemente consigliato a tutti gli utenti della versione 10.0.x per beneficiare di questi importanti miglioramenti.

Articolata in tre aree principali (CLI Tools, Architettura, ORM), questa release rappresenta un passo significativo nell'evoluzione del framework, portando strumenti professionali di livello enterprise alla portata di tutti gli sviluppatori PHP.

✨ Nuove Funzionalità

Esempio di utilizzo: 

  php SismaFramework/Console/sisma scaffold Product Catalog
  php SismaFramework/Console/sisma scaffold User Blog --type=DependentModel --force

Esempio di utilizzo: 

  php SismaFramework/Console/sisma install MyProject
  php SismaFramework/Console/sisma install BlogPersonale --db-host=localhost --db-name=blog_db --db-user=root --db-pass=secret

Esempi di utilizzo: 

  // PRIMA (solo entità referenziate):
  $model->getEntityCollectionByEntity(['referenced_entity' => $entity]);

  // ADESSO (qualsiasi proprietà):
  $users = $userModel->getByStatus(UserStatus::ACTIVE);
  $count = $productModel->countByPrice(99.99);
  $model->deleteByEmail('test@example.com');

  // Proprietà multiple con AND logico:
  $products = $productModel->getByNameAndCategory('iPhone', $electronics);

  // Con searchKey e paginazione:
  $articles = $articleModel->getByAuthor($author, 'keyword', ['date' => 'DESC'], 0, 20);

  // Query gerarchiche (SelfReferencedModel):
  $subCategories = $categoryModel->getByParentAndActive($parent, true);

  // Valori null su proprietà nullable:
  $orphans = $entityModel->getByNullableParent(null); // WHERE nullable_parent IS NULL

🏗️ Architettura

Vantaggi della rifatorizzazione:

🧪 Testing

📝 Documentazione

🚀 ORM

Esempio di utilizzo: 

  // Media dei prezzi
  $query->setAVG('price', 'average_price');

  // Somma con DISTINCT
  $query->setSum('amount', 'total', distinct: true);

  // Multiple aggregazioni
  $query->setMin('price', 'min_price')
        ->setMax('price', 'max_price', append: true)
        ->setAVG('price', 'avg_price', append: true);

Esempi di utilizzo: 

  // Many-to-one: eager loading con JOIN
  $articles = $articleModel->getEntityCollectionWithRelations(['author', 'category']);
  foreach ($articles as $article) {
      echo $article->author->name; // Già caricato, nessuna query N+1
  }

  // One-to-many: eager loading con batch loading
  $authors = $authorModel->getEntityCollectionWithRelations(['articleCollection']);

  // Relazioni nested multi-livello (dot notation)
  $articles = $articleModel->getEntityCollectionWithRelations(['author.country.continent']);

  // Relazioni nested (sintassi array)
  $articles = $articleModel->getEntityCollectionWithRelations([
      'author' => ['country', 'publisher' => ['city']]
  ]);

  // SelfReferencedEntity (tree structures)
  $categories = $categoryModel->getEntityCollectionWithRelations([
      'parentCategory',     // Padre
      'sonCollection'       // Figli
  ]);

  // Con parametri aggiuntivi
  $products = $productModel->getEntityCollectionWithRelations(
      relations: ['category', 'brand'],
      searchKey: 'laptop',
      order: ['price' => 'ASC'],
      limit: 20,
      joinType: JoinType::inner
  );

🧪 Testing

🔧 Miglioramenti Interni

[10.0.7] - 2025-11-17 - Correzione Bug SismaCollection

Questa patch release corregge un bug critico nella gestione delle entità persistenti all'interno delle SismaCollection.

🐛 Bug Fixes

Correzione Inserimento Entità Persistenti in SismaCollection

Corretto un bug nel metodo addOrUpdateIntoEntityCollection() della classe ReferencedEntity che causava errori durante l'inserimento in una SismaCollection di entità già persistenti dopo entità non ancora salvate: 

    // Prima (bug):
    if (isset($entity->id) && ($includedEntity->id === $entity->id)) {
        $includedEntity = $entity;
        $found = true;
    }
    
    // Dopo (corretto):
    if (isset($entity->id) && isset($includedEntity->id) && ($includedEntity->id === $entity->id)) {
        $includedEntity = $entity;
        $found = true;
    }

Scenario del bug:

  1. Una SismaCollection contiene un'entità non ancora salvata (con id = null)
  2. Si tenta di aggiungere un'entità già persistente (con id valorizzato)
  3. Il confronto null === 123 falliva, ma il controllo isset() mancava per $includedEntity->id
  4. Questo poteva causare comportamenti imprevisti nell'aggiornamento della collection

Impatto: Risolve problemi di inconsistenza nelle SismaCollection quando si mescolano entità persistite e non persistite.

🧪 Testing

[10.0.6] - 2025-11-07 - Refactoring Filter e Documentazione Migrazione

Questa patch release migliora la qualità del codice della classe Filter attraverso l'eliminazione di duplicazioni e il riordino dei metodi secondo i principi del Clean Code. Include inoltre la documentazione per la migrazione dalla versione 9.x alla 10.x.

🔧 Refactoring

Eliminazione Duplicazione Codice in Filter.php

Refactorizzata la classe Filter per eliminare codice duplicato nei metodi di validazione con limiti di lunghezza: 

    public function isMinLimitString($value, int $minLimit): bool
    {
        $result = true;
        $result = ($this->isString($value)) ? $result : false;
        $result = (strlen($value) >= $minLimit) ? $result : false;
        return $result;
    }
    public function isMinLimitString($value, int $minLimit): bool
    {
        return $this->isMinLengthForValidator($value, $minLimit, fn($v) => $this->isString($v));
    }

    private function isMinLengthForValidator(mixed $value, int $minLimit, callable $validator): bool
    {
        return $validator($value) && strlen($value) >= $minLimit;
    }

📚 Documentazione

Aggiunta Guida Migrazione 9.x → 10.x

Introdotto il file UPGRADING.md con documentazione completa per la migrazione:

📊 Metriche

✅ Backward Compatibility

[10.0.5] - 2025-11-01 - Refactoring Architetturale DataMapper

Questa patch release rifattorizza il DataMapper monolitico introducendo una separazione delle responsabilità in classi dedicate, seguendo i principi SOLID e Clean Code.

🏗️ Architettura

Refactoring DataMapper: Da Monolite a Separazione delle Responsabilità

Suddiviso il DataMapper monolitico (420 righe) in componenti specializzati per migliorare manutenibilità e testabilità:

- Metodi: start(), commit(), rollback()

- Flag di stato transazione centralizzato - Testabile indipendentemente

- Metodi: find(), findFirst(), getCount(), setVariable()

- Logica cache isolata e riutilizzabile - Parametro esplicito bool $ormCacheEnabled passato ai metodi invece di dereferenziare proprietà

- Elimina duplicazione del metodo privato getType()

- Riutilizzabile in altri contesti del framework 

    public function __construct(
        ?BaseAdapter $adapter = null,
        ?ProcessedEntitiesCollection $processedEntityCollection = null,
        ?Config $config = null,
        private TransactionManager $transactionManager = new TransactionManager(),
        private QueryExecutor $queryExecutor = new QueryExecutor()
    )

🔧 Miglioramenti Interni

✅ Backward Compatibility

📊 Metriche

[10.0.4] - 2025-10-22 - Miglioramenti Qualità Codice e Correzione Dispatcher

Questa patch release corregge un bug importante nella gestione del routing.

🐛 Bug Fixes

Correzione Impostazione URL nel Router

Corretto il momento in cui viene impostato l'URL attuale nel Router all'interno del Dispatcher:

Impatto: Previene l'impostazione di URL per azioni non valide, migliorando la precisione del routing e la gestione degli errori 404.

[10.0.3] - 2025-10-08 - Hotfix Test Suite

Questa hotfix release corregge i test rotti nella versione 10.0.2.

🐛 Bug Fixes

Ripristino Mock BaseAdapter nei Test con DataMapper Reale

Ripristinati i mock di BaseAdapter nei test che istanziano DataMapper con costruttore reale:

Causa del problema: Questi test creano istanze di DataMapper con costruttore (non completamente mockato), che a sua volta istanzia Query, il cui costruttore chiama BaseAdapter::getDefault(). Senza il mock, getDefault() ritorna null causando errori Call to a member function getAdapterClass() on null.

Soluzione: Ripristinato BaseAdapter::setDefault($baseAdapterMock) in questi test specifici.

✅ Test Suite Finale

Mock rimossi con successo (14 test):

Mock mantenuti (7 test + 3 specifici ORM):

[10.0.2] - 2025-10-08 - Ottimizzazione Connessione Database [RITIRATA]

⚠️ NOTA: Questa versione è stata ritirata a causa di test rotti. Utilizzare la versione 10.0.3 invece.

Questa patch release ottimizza significativamente le performance eliminando connessioni al database non necessarie attraverso l'implementazione del lazy loading in BaseAdapter.

🚀 Performance

Lazy Loading della Connessione Database

Implementato lazy loading della connessione al database in BaseAdapter per evitare connessioni inutili:

Impatto sulle performance:

🧪 Testing

Semplificazione Test Suite

Rimossi 21 mock di BaseAdapter non più necessari grazie al lazy loading:

Impatto: Test più puliti e leggibili, eliminando boilerplate di setup per il mock del database.

✅ Backward Compatibility

[10.0.1] - 2025-09-25 - Correzione Bug Router

Questa patch release corregge un bug nella generazione degli URL con il Router.

🐛 Bug Fixes

Correzione Generazione URL con Parametri Query String

Corretto il metodo Router::makeCleanUrl() per gestire correttamente i parametri query string:

Esempio: 

// Prima (bug):
Router::makeCleanUrl('/search', ['q' => 'test', 'page' => 2])
// Output errato: /search?q=test?page=2

// Dopo (corretto):
Router::makeCleanUrl('/search', ['q' => 'test', 'page' => 2])
// Output corretto: /search?q=test&page=2

Impatto: Risolve problemi di URL malformati quando si passano parametri query string al Router.

[10.0.0] - 2025-09-15 - Release Maggiore con Breaking Changes

Questa major release introduce breaking changes significativi per migliorare la qualità del codice e l'architettura del framework.

💥 Breaking Changes

1. CallableController::checkCompatibility() è ora statico

Motivazione: Il metodo checkCompatibility() non dovrebbe dipendere dallo stato dell'istanza del controller. 

class MyController extends BaseController implements CallableController
{
    public function checkCompatibility(array $arguments): bool
    {
        return count($arguments) === 2;
    }
}
class MyController extends BaseController implements CallableController
{
    public static function checkCompatibility(array $arguments): bool
    {
        return count($arguments) === 2;
    }
}

Azione richiesta: Aggiungere la keyword static alla firma del metodo checkCompatibility() in tutti i controller che implementano CallableController.

2. Rimozione dell'interfaccia CrudInterface

Motivazione: L'interfaccia CrudInterface non forniva valore aggiunto rispetto a BaseController e creava confusione. 

class PostController extends BaseController implements CrudInterface
{
    // Implementazione
}
class PostController extends BaseController
{
    // Implementazione (nessuna modifica ai metodi)
}

Azione richiesta: Rimuovere implements CrudInterface dalla dichiarazione delle classi controller. Nessuna modifica ai metodi è necessaria.

3. Language::getFriendlyLabel() richiede file di localizzazione

Motivazione: Eliminare valori hardcoded e centralizzare le traduzioni in file di configurazione. 

// Funzionava anche senza file di localizzazione
$label = Language::getFriendlyLabel('it');
// Output: "Italiano" (hardcoded)
// Richiede il file config/locales/it.json con:
// {
//   "language": {
//     "friendly_label": "Italiano"
//   }
// }
$label = Language::getFriendlyLabel('it');
// Output: "Italiano" (da file di configurazione)

Azione richiesta:

  1. Creare la directory config/locales/ se non esiste
  2. Per ogni lingua supportata, creare un file JSON (es. it.json, en.json)
  3. Aggiungere la struttura richiesta con il nome della lingua

Esempio di file di localizzazione:

config/locales/it.json: 

{
  "language": {
    "friendly_label": "Italiano"
  }
}

config/locales/en.json: 

{
  "language": {
    "friendly_label": "English"
  }
}

🚀 Miglioramenti

📚 Migrazione

Per una guida completa alla migrazione dalla versione 9.x alla 10.x, consultare il file UPGRADING.md.

Hai trovato un problema?

Se hai trovato errori o vuoi suggerire miglioramenti, apri una issue su GitHub.

Report Issue Edit on GitHub