Aggiornamenti

Gli aggiornamenti in WebBlocks CMS sono basati sulle release e sui pacchetti.

CMS include il runtime condiviso Publisher Client come sorgenti sincronizzati in src/Support/Updates/Client, senza richiedere il pacchetto Composer privato. Gli adattatori CMS gestiscono cronologia, versione persistente, migrazioni, riparazione cataloghi e backup completi. Non modificare file generati. Il repository privato è autorevole: composer embed:sync-all aggiorna le copie registrate; composer embed:check-all rileva divergenze tramite .publisher-client.json.

• La versione installata riflette l'ultima release reale applicata all'installazione.
• Il normale sviluppo del codice sorgente non modifica la versione installata.
• L'updater integrato applica pacchetti di release pubblicati, non le modifiche locali dell'albero di lavoro.
• I nuovi consumatori Composer devono installare prima con composer require fklavyenet/webblocks-cms e php artisan webblocks:install prima di usare il normale flusso di aggiornamento basato sulle release.
• Le attuali installazioni native di pacchetto consumano direttamente gli ZIP di release con radice di pacchetto.
• Le System Updates native di pacchetto applicano l'artefatto del pacchetto alla radice canonica del pacchetto Composer, vendor/fklavyenet/webblocks-cms, così che l'aggiornamento con Composer e la System Update producano la stessa struttura di pacchetto installata.
• Storicamente, le installazioni precedenti al modello nativo di pacchetto, come 1.31.53, non potevano consumare direttamente gli ZIP di release con radice di pacchetto e richiedevano prima il ponte gestito dalla radice nel vecchio formato 1.32.33. Quel percorso ponte è ora ritirato dalla validazione di release ordinaria perché non restano vecchie installazioni gestite dalla radice da supportare nei controlli normali.

La documentazione canonica risiede in docs/ del repository indipendente webblocks-cms-docs, inclusi docs/guides/ e media. Le pagine /docs e /guides sono destinazioni di pubblicazione. CMS include il contratto resources/contracts/inventory.md, ancora accessibile tramite GET /webadmin/api/inventory. Installare o aggiornare CMS non richiede il repository documentale. La separazione non ha introdotto motori di pubblicazione o sincronizzazione.

La transizione della licenza usa una versione ponte del pacchetto:

• 1.89.1: Gli ZIP Publisher includono solo il percorso storico docs/LICENSE per consentire ai client esistenti di installare il ponte. Composer/Git mantengono LICENSE nella radice. L'updater accetta entrambi, preferisce LICENSE nella radice se coesistono e installa la licenza canonica. La documentazione resta esclusa.
• 1.89.2 e successivi: Gli ZIP Publisher contengono LICENSE nella radice senza generare docs/. I metadati richiedono almeno CMS 1.89.1. Le installazioni precedenti devono prima installare 1.89.1 e ricontrollare. Composer permette aggiornamenti diretti.
• 1.89.3: Publisher Client incorporato passa a 1.1.13, valida la compatibilità del ponte e cerca il prossimo aggiornamento dopo l'installazione riuscita. L'adattatore CMS conserva update_path e rifiuta versioni minime del prodotto malformate.
• 1.89.4: Publisher Client incorporato passa a 1.1.14. Le note includono solo versioni successive all'installata e non superiori al target scelto, anche se è un ponte.

Per esempio, un'installazione precedente può ricevere 1.89.1 prima di 1.89.4. Verificare e applicare il ponte, poi aggiornare alla versione corrente dopo un nuovo controllo. Lo schermo del ponte mostra note solo fino a 1.89.1. È distinto dal ponte storico 1.32.33 gestito dalla radice.

• Eseguite gli aggiornamenti solo da release pubblicate.
• Mantenete i file specifici dell'installazione nei percorsi preservati come .env, storage/ e project/.
• Trattate separatamente i flussi di lavoro di sviluppo e di release.
• System Updates punta sempre alla radice Composer vendor/fklavyenet/webblocks-cms. Le copie sorgenti si aggiornano con git/Composer. La modalità ritirata da sorgente e l'impostazione WEBBLOCKS_UPDATES_MIGRATION_STRATEGY sono ignorate da 1.41.0.
• I pacchetti di release contengono solo codice riutilizzabile del core del CMS e non devono includere contenuti project/ specifici dell'installazione.
• I percorsi preservati durante l'aggiornamento non modificano il confine del pacchetto di release: project/ resta locale all'installazione e fuori dall'artefatto pubblicato.
• Le copie di lavoro CMS installate sono consumatrici di aggiornamenti, non publisher upstream. Se un'installazione ha un origin git, mantenete l'accesso in fetch se necessario ma disabilitate il push con git remote set-url --push origin DISABLED.
• Il successo si registra solo quando il runtime riporta la versione target da WebBlocks\Cms\Support\WebBlocks. Una versione precedente o inattesa causa errore e ripristino automatico. Lo stato è restored se il ripristino riesce, altrimenti failed con entrambe le tracce d'errore.

Un host può installare più pacchetti con Publisher Client in namespace distinti. La configurazione Laravel è globale; publisher-client non è uno stato permanente del prodotto. Un altro provider può scrivere prodotto, risolutore versione, target, validazione, migrazioni e valori post-applicazione nello stesso avvio.

Ogni ingresso aggiornamento CMS ripristina tutta la configurazione prima di risolvere un servizio. I controller iniettano solo CmsPublisherClientConfigurator, chiamano configure(), poi risolvono SystemUpdateInspector, UpdateServerClient, SystemUpdater o AdminUpdateIndicator. Iniettarli nel costruttore o metodo d'azione potrebbe risolvere dipendenze prima del ripristino ed è vietato. Il test di coesistenza sostituisce la configurazione con un prodotto estraneo e verifica il ripristino congiunto di risolutore, versione, target e client CMS.

System Updates mostra una scheda con due stati. Se aggiornato, mostra versione e ultimo controllo. Se c'è un aggiornamento compatibile, mostra percorso versioni, What's new richiudibile con note per versione, Update to X con un clic e backup automatico/ripristino in caso d'errore, più il collegamento ai backup completi prima di aggiornamenti importanti. Confronta il codice CMS attivo con l'ultima versione pubblicata; la versione memorizzata serve solo alla cronologia e persistenza.

I superamministratori hanno un indicatore asincrono nella navigazione superiore. Nascosto per default, legge /webadmin/system/updates/indicator in background e appare solo con una nuova versione affidabile. Il rendering normale non attende il server aggiornamenti; le installazioni aggiornate non mostrano scorciatoie permanenti.

Il controllo preliminare verifica database, ZIP/sodium, esecuzione PHP/Composer/processi, scrittura in radice/workspace e spazio libero. Ogni test passa o fallisce; aggiornare richiede tutti superati e nessun blocco attivo. La cronologia è richiusa e i log si aprono in modali; non ci sono azioni distruttive.

I registri vengono ripuliti dopo controlli e applicazioni. Si conservano gli ultimi cinque e l'ultimo errore fino a un successo successivo. La schermata li elenca senza cancellazione. Ispezionare con php artisan webblocks:updates:runs, php artisan webblocks:updates:runs --last, php artisan webblocks:updates:runs --failed; pulire in modo controllato con php artisan webblocks:updates:prune-runs --keep=5.

Release mostra metadati da title, summary, highlights, fixes, compatibility_notes, migration_notes, asset_notes, operator_notes, technical_notes come testo con escape. changelog_entries contiene voci cumulative, più recenti prima, successive all'installata e non oltre il target, tratte da changelog, releases, changelog_entries. Senza lista, usa la sola voce target; What's new non è vuoto.

La stringa legacy release_notes resta supportata per i payload di release più vecchi. Se non sono presenti note di release, la schermata indica No release notes were provided for this release. L'updater non deduce le modifiche dai numeri di versione.

I metadati si preparano con composer release:prepare e pubblicano con composer release:publish-update. Il wrapper verifica GitHub CLI prima della scrittura irreversibile su Publisher, pubblica lì e crea/aggiorna il GitHub Release come latest. Richiede una sezione CHANGELOG.md corrispondente, usa i punti per release_notes e summary/highlights, aggiunge riferimento, checksum e versione minima. Invia campi superiori e annidati: nuovi client ricevono note ricche, vecchi testo semplice. Si leggono campi superiori, details, release_details, meta.release_details/meta.details.

GitHub Actions non crea pacchetti né pubblica metadati; .github esegue solo test/lint. Il wrapper locale allinea GitHub latest al tag stabile. System Updates usa solo Publisher. publisher.webblocksui.com è il servizio canonico: pubblicazione https://publisher.webblocksui.com/api/updates/publish, lettura https://publisher.webblocksui.com/api/updates/latest, download https://publisher.webblocksui.com/downloads/.... Nei normali .env non servono chiavi server/prodotto/canale: ReleaseDefaults definisce server, prodotto, stable e percorsi. Il vecchio ponte updates.webblocksui.com è storico, non configurazione attiva.

Comandi per i manutentori:

release:push invia ramo e tag annotato insieme a origin, eseguendo i controlli pre-push una volta. Solo dopo replica gli stessi riferimenti su backup con --no-verify; confronta ramo e commit risolto del tag su entrambi i remoti col commit locale.

La pubblicazione usa WEBBLOCKS_PUBLISHER_TOKEN e, per firmare, WEBBLOCKS_PUBLISHER_SIGNING_KEY. Default: https://publisher.webblocksui.com, prodotto webblocks-cms, canale stable, lettura /api/updates/latest; pubblicazione con stessa identità e /api/updates/publish. Il wrapper Composer legge solo questi due segreti da .env nel processo Testbench isolato; la configurazione in cache li aggiorna da .env. Non serve export manuale. Dry-run valida chiave e artefatti senza upload. Senza token, la pubblicazione reale resta non pubblicata e termina con errore; non conta come pubblicazione.

I controlli includono telemetria rispettosa della privacy. Publisher distingue download da installazioni anonime attive. I download contano gli artefatti scaricati; le installazioni attive contano identificativi unici che riportano nel tempo.

La telemetria è attiva per default; per disattivarla:

Con telemetria attiva, il primo controllo necessario genera installation_id casuale locale e lo salva nelle impostazioni di sistema. Non contiene dati personali o del sito, resta stabile e può cambiare ricreando l'installazione o reimpostando storage/database.

Il controllo invia solo questi campi:

• product_key
• installed_version
• channel
• installation_id
• telemetry_schema_version

CMS non invia domini, URL completi, email admin, percorsi, nomi database, titolari licenza, conteggi utenti, token, segreti o valori arbitrari. Con WEBBLOCKS_TELEMETRY=false, richiede ancora metadati con prodotto, canale e versione, ma non crea né invia installation_id.

Un aggiornamento interno è un'esecuzione con un clic: scarica e verifica il pacchetto, crea backup automatico, applica i file e poi, nell'ordine:

• migrazioni di aggiornamento del pacchetto, se presenti
• passaggi di pulizia della cache
• sincronizzazione del catalogo incluso (webblocks:catalog-repair --all)
• registrazione dell'esecuzione di aggiornamento
• persistenza della versione installata

Se applicazione o verifica falliscono, ripristina automaticamente il backup precedente. Lo stato è restored; se fallisce anche il ripristino, è failed con entrambe le tracce nel log. Il backup resta disponibile nella schermata Backup o via CLI php artisan system:backup:restore per ripristino manuale.

Dopo il successo si applica la pulizia configurata e si registrano quantità eliminate e byte liberati. Gli errori di pulizia non annullano l'aggiornamento; sono registrati per revisione. Default: backup precedenti 14 giorni e almeno gli ultimi cinque riusciti; backup di sicurezza ripristino 30 giorni e punti contenuto 7. I backup di aggiornamenti falliti/ripristinati sono protetti 90 giorni. Esclusi manuali, caricati e in esecuzione. Configurare/anteprima in Maintenance → Cleanup; vedere Operazioni per scheduler, CLI e API.

Gli aggiornamenti applicano pacchetti pubblicati e dopo la pulizia cache eseguono webblocks:catalog-repair --all come sottoprocesso del nuovo codice. Allineano cataloghi blocchi, blocchi plugin, slot, layout e icone; aggiungono voci come Rating/Comments senza comando manuale. Il manifest ricostruito rileva nuovi comandi. Sono idempotenti e preservano voci personalizzate.

La sincronizzazione è best-effort: file e migrazioni sono già riusciti, quindi un suo errore non fa fallire l'aggiornamento. Il log segnala l'incompletezza e la possibilità di rieseguire php artisan webblocks:catalog-repair --all. Lo schema cambia tramite migrazioni esplicite; il sync ripara solo dati del catalogo.

I passaggi di pulizia della cache comprendono le pulizie di configurazione, viste, cache applicativa e rotte di Laravel, così che i layout e gli helper Blade di proprietà del pacchetto vengano ricompilati dopo la sostituzione dei file. Su installazioni PHP-FPM in produzione con OPcache configurato per non validare i timestamp, ricaricate il servizio PHP-FPM pertinente dopo un aggiornamento riuscito, in modo che PHP non continui a servire dalla memoria classi del pacchetto precedenti all'aggiornamento.

Durante l'aggiornamento, una modale non chiudibile mostra il percorso con il caricamento WebBlocks UI. PHP può riavviarsi durante la richiesta, quindi non ne attende la fine: avvia e interroga l'indicatore ogni 1,5 secondi, tornando comunque all'admin entro 3 minuti. Ogni risposta, incluso il redirect al login, ricarica lo schermo.

System Update non esegue mai database/migrations dell'host, evitando conflitti di migrazioni Laravel pendenti come 0001_01_01_000000_create_users_table.php con tabelle CMS esistenti. Applica il pacchetto a vendor/fklavyenet/webblocks-cms ed esegue solo migrazioni PHP in vendor/fklavyenet/webblocks-cms/database/migrations/updates. Se assenti, registra il salto e continua con cache/versione. Qui vanno anche riparazioni sicure dello schema, come chiavi padre per backup completi portabili.

Qualsiasi modifica allo schema di WebBlocks CMS richiesta dal codice a runtime deve supportare entrambi i percorsi di installazione:

1. Installazioni nuove o da consumatore del pacchetto: aggiornate il percorso di migrazione dello schema normale o di installazione nuova.
2. Installazioni native di pacchetto esistenti aggiornate tramite System Updates: aggiungete una migrazione di aggiornamento del pacchetto sotto database/migrations/updates del pacchetto; i consumatori installati la eseguono da vendor/fklavyenet/webblocks-cms/database/migrations/updates.

Lo schema di installazione nuova da solo non basta. Se il nuovo codice a runtime si aspetta una tabella o una colonna, la release deve includere una migrazione di aggiornamento per le installazioni esistenti, oppure l'aggiornamento deve fallire in modo sicuro prima che il nuovo percorso di codice possa generare un errore 500 grezzo. Le System Updates native di pacchetto non devono richiedere agli utenti ordinari di collegarsi via SSH a un sito ed eseguire migrazioni manuali dopo un aggiornamento riuscito.

Il successo richiede codice, schema, cache e verifica finale allineati. Admin/API/runtime dipendenti dal nuovo schema devono mostrare istruzioni controllate, non errori grezzi. Il caso 1.32.146→1.32.147 è il riferimento: cms_api_tokens era solo nelle migrazioni normali; dopo l'update System -> API Tokens dava errore finché 1.32.147 aggiunse migrazione del pacchetto e gestione dello schema mancante.

Lo schema interazioni segue lo stesso contratto. Gli aggiornamenti garantiscono wbcms_comment_entries/wbcms_content_ratings automaticamente senza richiedere artisan migrate dell'host. La riparazione idempotente conserva e rinomina le tabelle storiche senza prefisso o crea quelle prefissate; nel rollback preserva intenzionalmente i dati.

I report di release con modifiche allo schema devono rispondere esplicitamente a:

• percorso dello schema di installazione nuova aggiornato: sì/no
• migrazione di aggiornamento del pacchetto aggiunta: sì/no
• test di regressione della migrazione di aggiornamento aggiunto: sì/no
• comportamento corretto in assenza di schema necessario/aggiunto: sì/no

Durante la transizione a pacchetto, alcune installazioni possono avere ancora una copia obsoleta packages/webblocks-cms nella radice dell'installazione o una vecchia copia annidata di transizione in vendor. Questi percorsi sono artefatti legacy della transizione, non la fonte di verità nativa di pacchetto attiva. La System Update nativa di pacchetto sostituisce ora la radice canonica del pacchetto Composer in vendor/fklavyenet/webblocks-cms e verifica la versione di destinazione da quella radice di pacchetto. Non mantiene packages/webblocks-cms come seconda copia runtime aggiornata.

Il vendor precedente vendor/fklavyenet/webblocks-cms può contenere artisan, app/, bootstrap/, packages/webblocks-cms/, plugins/, tests/ come repository. System Update lo sostituisce col pacchetto piatto: composer.json, LICENSE radice, src/, routes/, resources/, database/, public/, config/, stubs/ sotto vendor/fklavyenet/webblocks-cms. Normalizza metadati Composer prima dell'autoload ottimizzato e verifica che WebBlocks\Cms\ provenga da vendor/fklavyenet/webblocks-cms/src, non vendor/fklavyenet/webblocks-cms/packages/webblocks-cms/src. Percorsi obsoleti fanno fallire l'update anziché dichiarare successo con admin guasto.

Gli aggiornamenti moderni preservano la separazione tra l'amministrazione /webadmin e gli asset /cms introdotta dalla migrazione della v1.32.56. /cms è solo uno spazio dei nomi per asset statici, non un prefisso di amministrazione, perché il try_files di Nginx può risolvere /cms/ come la directory fisica public/cms/ prima che Laravel veda una rotta. Gli aggiornamenti non devono ripristinare alias di amministrazione /cms di proprietà del CMS, redirect /cms, rotte /admin o un passaggio a public/cms/index.php, né nella radice dell'installazione né negli asset pubblici del pacchetto.

Questa sezione è storica. L'updater della 1.31.53 validava il vecchio contratto di archivio gestito dalla radice: artisan e composer.json dovevano trovarsi nella radice dell'archivio o dentro un'unica directory contenitore. Gli artefatti con radice di pacchetto come 1.32.31 non contenevano intenzionalmente un artisan di radice, perciò quei vecchi client fallivano prima dell'applicazione con Package validation failed because composer.json and artisan were not found at the archive root.

La strategia del ponte ritirato prevedeva due passaggi:

• Pubblicare o ripubblicare un artefatto di release ponte nella vecchia forma gestita dalla radice, costruito da un sorgente compatibile con il ponte che conteneva ancora i wrapper legacy App\Support\System\Updates\* e che convalidava già archivi stretti con radice di pacchetto fklavyenet/webblocks-cms. Per il ponte 1.32.33 il riferimento sorgente era v1.32.30.
• Pubblicare release con radice di pacchetto con minimum_client_version impostato a 1.32.18 o successivo, in modo che ai client vecchi non venisse proposto l'ultimo artefatto con radice di pacchetto prima del ponte.
• Dopo l'applicazione del ponte, l'updater installato poteva convalidare e applicare la forma stretta di artefatto con radice di pacchetto fklavyenet/webblocks-cms usata dalle release moderne.

scripts/build-root-managed-bridge-archive.sh VERSION [OUTPUT_DIR] [GIT_REF] è mantenuto soltanto come strumento archiviato di ripristino manuale per lo ZIP ponte nella vecchia forma; per esempio scripts/build-root-managed-bridge-archive.sh 1.32.33 dist v1.32.30. Il builder esclude intenzionalmente i percorsi di proprietà dell'installazione come .env, storage/, project/, public/site/, public/storage e il config/ radice; i valori predefiniti di proprietà del pacchetto sotto packages/webblocks-cms/config restano parte del runtime del pacchetto. La validazione ordinaria nativa del pacchetto non esegue questo percorso ponte.

Il percorso storico completato è stato 1.31.53 -> 1.32.33 bridge -> 1.32.34+ package-rooted. Le installazioni già compatibili con il ponte, come 1.32.30, hanno saltato il ponte e sono state aggiornate direttamente a una release con radice di pacchetto 1.32.34+. Gli attuali controlli di rilascio proteggono soltanto l'artefatto con radice di pacchetto e il comportamento dell'updater nativo del pacchetto.

System Updates esegue webblocks:catalog-repair --all automaticamente dopo l'installazione; vedere Flusso di applicazione. Gli stessi comandi restano disponibili per riparazioni manuali tra release o sincronizzazioni incomplete:

Il comando supporta --block-types, --plugin-block-types, --slot-types, --page-layouts, --icons. Eseguire prima --dry-run per vedere voci create, aggiornate, invariate o saltate. È idempotente, conserva le voci personalizzate e non le elimina.

La sincronizzazione dei tipi di blocco di livello inferiore resta disponibile per compatibilità:

Il percorso di riparazione dei tipi di blocco mantiene il catalogo block_types memorizzato nel database allineato al catalogo del core CMS distribuito nelle installazioni esistenti:

• i tipi di blocco core mancanti vengono creati
• i tipi di blocco core esistenti vengono aggiornati sul posto
• i tipi di blocco personalizzati specifici dell'installazione vengono preservati
• non vengono create righe core duplicate

Questo flusso di manutenzione copre il caso in cui un'installazione debba aggiornare le righe di catalogo senza costringere ogni applicazione di un pacchetto di release a eseguire un'ampia riparazione del catalogo nel database.

Quando l'updater viene eseguito all'interno di un clone di installazione gestito con git che punta ancora all'upstream canonico del CMS, il CMS disabilita ora automaticamente anche il push su origin dopo i comandi di post-installazione, così che futuri tentativi accidentali di git push falliscano in modo chiaro mentre il normale accesso in fetch o pull resta disponibile.

• Operazioni
• Installazione
• Contributi