Installazione

Panoramica

WebBlocks CMS è distribuito come pacchetto Composer installato in un'applicazione host Laravel. L'applicazione host rimane responsabile del bootstrap, dell'ambiente, del database, delle code, della posta, dello scheduler, della distribuzione, dei backup e della root dei documenti pubblici. Le notifiche e-mail batch/giornaliere e i riepiloghi e-mail giornalieri richiedono la pianificazione ogni minuto; i nuovi siti abilitano questi criteri per impostazione predefinita. La visualizzazione dei messaggi salvati e delle notifiche del pannello non richiede la pianificazione o la posta in uscita.

Prima di predisporre un server di produzione, consultare i Requisiti di hosting, valutare il carico con la Verifica della capacità, confrontarlo con i Risultati di capacità, esplicitamente provvisori, e completare la Lista di preparazione. Queste pagine distinguono il contratto di installazione dalle dipendenze opzionali di immagini, posta, pianificazione, backup e aggiornamenti del pacchetto; le misurazioni parziali non certificano l'uso in produzione.

Per un'installazione normale, utilizzare un'applicazione Laravel 12.55+ o Laravel 13 nuova o esistente con chiave e database configurati. Installare il pacchetto con Composer, quindi eseguire l'installer CMS.

Un'installazione è considerata completa quando l'applicazione dispone di una base funzionante del CMS:

esiste una chiave applicativa
il database è raggiungibile
esistono le tabelle richieste
esistono i dati di seed di base
esiste il primo super_admin attivo
un marcatore di completamento dell'installazione è memorizzato in system_settings

Installazione come pacchetto consumer

Dalla radice dell'applicazione Laravel ospitante, eseguire:

composer require fklavyenet/webblocks-cms
php artisan webblocks:install --name="Admin User" --email="admin@example.com" --password="secret-password"

Aprire quindi /webadmin/login. Questo è il percorso di installazione principale e supportato per gli utenti CMS. Clonare il repository non crea un'applicazione Laravel autonoma.

Opzioni supportate:

--name= nome visualizzato del primo super admin
--email= indirizzo e-mail del primo super admin
--password= password del primo super admin
--site-name= nome del primo sito; se omesso, si usa WEBBLOCKS_CMS_DEFAULT_SITE_NAME quando configurato, altrimenti l'host normalizzato di APP_URL
--site-handle= handle del sito predefinito
--repair-partial rinomina le tabelle CMS parziali vuote prima delle migrazioni di installazione nuova
--skip-starter-content pubblica una home vuota anziché la pagina iniziale inclusa
--force sovrascrive gli asset CMS di proprietà del pacchetto o i file di configurazione pubblicati quando serve

Che cosa fa webblocks:install:

assegna al primo sito il nome dell'host normalizzato di APP_URL, mantenendo l'identificatore interno default; omette www., conserva i sottodomini significativi e usa Default Site per host locali o IP
pubblica config/webblocks-cms.php quando l'applicazione ospite non lo ha già
rimuove da routes/web.php la rotta welcome intatta di un Laravel nuovo quando è sicuro farlo, creando prima un backup con marca temporale, così le rotte pubbliche del CMS possono servire /
applica una patch a app/Models/User.php con WebBlocks\Cms\Auth\Concerns\HasWebBlocksCmsAccess
crea un backup con marca temporale prima di modificare User.php
salta la patch quando il trait è già presente
fallisce in modo chiaro se User.php non è una classe App\Models\User extends Authenticatable riconoscibile
esegue il percorso di migrazione di installazione nuova del pacchetto per installazioni consumer pulite
rileva schemi CMS parziali prima di eseguire le migrazioni di installazione nuova e segnala le tabelle CMS esistenti, i conteggi delle righe, le righe di migrazione correlate e i conflitti noti di chiavi esterne
ripara gli schemi CMS parziali vuoti solo quando viene fornito --repair-partial, rinominando le tabelle CMS vuote con un suffisso _before_cms_install_... con marca temporale prima di proseguire
rifiuta la riparazione automatica quando una tabella CMS parziale contiene righe
evita di rieseguire quello schema nuovo quando le tabelle del CMS esistono già
crea le tabelle di supporto di Laravel senza eseguire le migrazioni dell'applicazione ospite; attualmente copre i token di reimpostazione password del CMS e sessions, cache e cache_locks quando quei driver basati su database sono configurati
non esegue il normale insieme di migrazioni Laravel dell'applicazione ospite come parte dell'installazione del pacchetto, evitando così conflitti con la tabella users compatibile con il CMS già creata
prepara la root del disco filesystem backups usata da Backup / Restore
installa gli asset CMS di proprietà del pacchetto in public/cms
crea public/storage quando manca e l'ambiente lo consente
carica in modo idempotente lingue, siti, tipi di slot, layout e tipi di blocco principali
carica l'intero catalogo icone WebBlocks UI dal manifest del pacchetto; i campi funzionano senza rete esterna né sincronizzazione manuale
crea la home pubblicata su /, inclusi gli slot del layout
riempie la home con il contenuto iniziale incluso, salvo disattivazione
registra la versione installata e il marcatore di completamento dell'installazione in system_settings
crea il primo super_admin attivo solo quando non ne esiste già uno

L'autenticazione del pacchetto è nativa di Laravel e non richiede Breeze, Jetstream, Laravel UI o Fortify. Dopo l'installazione, accedete da /webadmin/login quando le rotte di autenticazione del pacchetto CMS sono attive. Le viste di autenticazione di proprietà del CMS e i redirect per gli ospiti nell'amministrazione usano nomi di rotta del pacchetto come webblocks.auth.login e webblocks.auth.logout, così un prodotto ospite può mantenere la propria rotta globale login, per esempio /quiztem/login, senza sottrarre le azioni dei form del CMS o i redirect verso /webadmin.

Nel modello attuale di installazione del pacchetto, App\Models\User dell'applicazione ospitante resta il modello di autenticazione e il destinatario della modifica durante l'installazione.

Recupero di un'installazione parziale

Se webblocks:install si arresta dopo un'esecuzione precedente fallita o interrotta, rieseguitelo prima senza riparazione e leggete la diagnostica dell'installazione parziale. Le tabelle CMS vuote possono essere spostate da parte in modo esplicito:

php artisan webblocks:install --repair-partial --name="Admin User" --email="admin@example.com" --password="secret-password"

La modalità di riparazione rinomina soltanto le tabelle candidate vuote di proprietà del CMS. Non elimina tabelle, non altera automaticamente le tabelle non vuote e non presume che il CMS sia proprietario dell'applicazione ospite.

Notifiche del pannello senza pianificatore (CMS 1.96.0)

Per i gestori delle operazioni del sito, il campanello di notifica dell'intestazione dell'amministratore si collega a Dashboard → Notifiche del pannello. Il pannello legge i messaggi di contatto salvati ogni volta che viene caricata una pagina del pannello, anche quando la posta elettronica è disabilitata o lo scheduler non è mai stato eseguito. Mostra i messaggi non letti e i messaggi in attesa di risposta per sito accessibile, con collegamenti alla casella di posta dei contatti filtrata. I messaggi non letti vengono inclusi nel conteggio dei messaggi in attesa di risposta. Il badge campanello conta solo i messaggi di contatto non letti; i messaggi letti in attesa di risposta e gli avvisi di sistema rimangono separati nella Dashboard. In assenza di messaggi non letti, il campanello è nascosto; il pannello delle notifiche della Dashboard rimane disponibile. L'icona Azioni apre la posta in arrivo del sito selezionato per rivedere i messaggi in attesa di risposta, che possono includere messaggi già letti. I conteggi e i collegamenti non includono mai siti inaccessibili e il riepilogo non mostra i dettagli dei visitatori.

L'apertura del pannello non contrassegna i messaggi letti, l'invio di e-mail in sospeso, i tentativi di consegna non riuscita o l'integrità dello scheduler di produzione. La lettura di un messaggio di contatto riduce il lavoro non letto ma lo lascia in attesa di risposta; contrassegnarlo come risposto o archiviato lo rimuove da questo riepilogo. I messaggi di spam e in quarantena rimangono nella casella di posta di moderazione anziché nel conteggio dei lavori in sospeso. Si tratta dello stato della posta in arrivo condivisa, aggiornato al caricamento della pagina, non della cronologia delle notifiche personali. La Live Chat mantiene il proprio indicatore del pannello autorizzato, indipendentemente dall'e-mail pianificata.

La posta elettronica solo immediata con i riepiloghi giornalieri disabilitati funziona anche senza una pianificazione, a condizione che sia configurata la posta in uscita. Le e-mail batch/giornaliere e i promemoria e-mail giornalieri richiedono ancora la pianificazione in background: l'accesso a CMS non può garantire la consegna all'orario selezionato quando nessuno visita il pannello.

Notifiche pianificate e integrità dello scheduler

I nuovi siti da CMS 1.95.0 utilizzano batch di messaggi di dieci minuti e un riepilogo giornaliero dei messaggi in sospeso per impostazione predefinita. Prima di abilitare queste funzionalità in produzione, l'amministratore del server o il provider di hosting deve configurare lo scheduler di Laravel in modo che venga eseguito ogni minuto. Gli aggiornamenti registrano i lavori CMS senza installare automaticamente una voce del server cron. CMS 1.105.25 offre anche la configurazione opzionale CLI esplicitamente confermata di seguito. La persona che gestisce CMS seleziona la politica di notifica; l'amministratore del server possiede il runtime in background.

Aggiungi una voce al crontab dell'utente dell'applicazione o al servizio di attività pianificate di hosting equivalente:

* * * * * cd /path/to/laravel-app && /path/to/php artisan schedule:run >> /dev/null 2>&1

Sostituisci entrambi i percorsi di esempio con la directory host effettiva Laravel contenente artisan e l'eseguibile CLI PHP appropriato. Web e CLI PHP devono soddisfare i requisiti CMS. Se questa applicazione dispone già di uno scheduler Laravel funzionante, mantieni quella voce; il nuovo lavoro si unisce alla pianificazione esistente. Un operatore della coda permanente non è richiesto da questa implementazione di notifica sincrona.

Da CMS 1.105.25, aprire Pulizia → Conservazione e automazione → Configurazione e verifica dello scheduler o il collegamento di configurazione in Integrità del sistema. La schermata di sola lettura mostra i comandi per questa installazione, lo stato effettivo dell'heartbeat e un collegamento di aggiornamento. Verificare con il proprio provider il percorso CLI PHP visualizzato; se necessario configurare WEBBLOCKS_CMS_SCHEDULER_PHP_BINARY e aggiornare la configurazione dell'applicazione. Herne non è richiesta. Qualsiasi pannello di hosting che supporti un comando ogni minuto può utilizzare il comando standard cron sopra.

Su un host Unix supportato con accesso CLI, eseguire i comandi con l’account del sistema operativo proprietario di artisan, che possa leggere l’applicazione e scrivere nelle directory di esecuzione. Non usare mai root:

php artisan webblocks:scheduler:setup
php artisan webblocks:scheduler:setup --install

Il primo comando esegue soltanto un’ispezione. Il secondo richiede conferma dopo aver controllato le attività cron, systemd e del pannello di hosting; per un’installazione non interattiva già verificata, usare --install --yes. --json restituisce un risultato privo di dati sensibili senza porre domande. Il programma conserva il contenuto del crontab, aggiunge una voce contrassegnata eseguita ogni minuto e la rilegge. Voci esistenti o ambigue, attività reale recente, definizioni esterne leggibili, shell non supportate, account errati ed errori di accesso impediscono l’installazione. Non può rilevare ogni definizione del provider o non leggibile: verificarle prima di confermare. Senza accesso CLI/crontab, usare il pannello di hosting o chiedere al provider di aggiungere il comando. Un aggiornamento del CMS non può garantire i permessi del sistema operativo in ogni ambiente.

Una voce cron installata resta non verificata finché non viene eseguita l’attività effettivamente pianificata. Attendere 1–2 minuti, aggiornare l’attività registrata e controllare il comando di stato seguente. La schermata di configurazione mostra il segnale di attività; il comando completo di salute/stato verifica anche l’esecuzione delle notifiche. Non aggiungere un altro pianificatore solo perché la pulizia attende l’orario giornaliero. Gli aggiornamenti conservano i criteri salvati e le categorie automatiche selezionate di ogni installazione; verificarli e salvarli separatamente.

Configura inoltre un vero e proprio trasporto di posta in uscita, il canonico HTTPS APP_URL, e una cache condivisa che supporta i blocchi atomici quando più lavoratori possono elaborare le notifiche. L'aggiornamento del sito esistente conserva le notifiche complete/immediate con promemoria giornalieri disabilitati; tali impostazioni di notifica non richiedono pianificazione finché non vengono modificate.

CMS 1.95.1 aggiunge l'integrità registrata alla Dashboard e Siti → Modifica → Contatto e Live Chat 0.7.1 la espone nelle sue impostazioni e integrità del plugin. L'API di notifica del sito include scheduler_health. Controllare le attività registrate e quindi le prove di runtime registrate:

php artisan schedule:list
php artisan webblocks:scheduler:status --json

Gli utenti con accesso all'integrità del sistema esaminano l'avviso completo della pianificazione in Manutenzione → Integrità del sistema → Notifiche pianificate; la loro Dashboard mostra un riepilogo compatto della salute. I gestori delle operazioni del sito senza tale accesso conservano la scheda Pianificazione dettagliata sulla propria dashboard, anche quando tutti i siti accessibili utilizzano notifiche solo immediate con i riepiloghi giornalieri disabilitati. In tal caso la scheda è informativa e spiega che tali notifiche non richiedono pianificazione. Se un sito accessibile consente il batching, la consegna giornaliera o i riepiloghi giornalieri, lo stato di salute non verificato o ritardato solleva l'avviso; i siti inaccessibili non influenzano mai l'avviso.

L'elenco dei lavori conferma solo la registrazione. Running richiede un heartbeat pianificato recente e un'esecuzione di notifica completata recente. Non ancora verificato significa che non è stata registrata alcuna prova affidabile dell'esecuzione. Delayed significa che un battito cardiaco o una corsa completata risalgono a più di cinque minuti fa. Un errore di elaborazione o uno schema di notifica mancante vengono visualizzati separatamente. Un'esecuzione corrente potrebbe mostrare brevemente In progress. Il comando status termina con successo solo in caso di integrità di esecuzione verificata; altri stati restituiscono uno stato diverso da zero.

L'heartbeat è prodotto da una richiamata effettivamente pianificata. L'esecuzione manuale di php artisan webblocks:notifications:dispatch può elaborare la posta in scadenza ma non stabilisce l'integrità dello scheduler. Le letture sulla salute non creano un battito cardiaco. Le prove vengono archiviate nel database CMS e rimangono visibili attraverso i processi Web e CLI. I timestamp vengono restituiti in UTC; gli orari di riepilogo giornalieri seguono ancora il fuso orario di ciascun sito. Nessun contenuto del cliente, segreto o testo di eccezione non inserito viene inserito in questo record sanitario.

Ie la pianificazione non è verificata o viene ritardata mentre sono abilitati i batch o i riepiloghi giornalieri, il pannello avvisa che le notifiche potrebbero rimanere in sospeso e identifica l'amministratore/provider del server come proprietario della configurazione. Chiedi al proprietario di controllare cron o lo scheduler dell'hosting, il percorso dell'applicazione, la CLI PHP, le autorizzazioni di processo e gli errori di runtime. Quindi conferma un nuovo battito cardiaco e l'esecuzione della notifica completata. Questi controlli confermano l'esecuzione registrata su questa installazione; non garantiscono la consegna della posta in arrivo del destinatario né certificano in modo indipendente ogni nodo del server.

Aggiornare le installazioni esistenti

Consultare Aggiornamenti per flusso, backup e compatibilità. Le installazioni Publisher precedenti a 1.89.1 devono applicare il ponte per la licenza 1.89.1 prima di 1.89.2 o successivi. Ricontrollare dopo; i client recenti lo fanno automaticamente. Le installazioni Composer si aggiornano direttamente senza questo ponte Publisher.

La documentazione utente è mantenuta separatamente in docs/ del repository webblocks-cms-docs; non viene installata col CMS. Il pacchetto conserva il contratto di authoring resources/contracts/inventory.md, disponibile anche tramite GET /webadmin/api/inventory. Documentazione e guide pubbliche sono destinazioni di pubblicazione; la separazione non ha introdotto un motore di sincronizzazione.

Migrazione dei dati di esecuzione a tabelle relazionali in CMS 1.98.5

L'aggiornamento del pacchetto aggiunge spazio di archiviazione relazionale per layout di pagina e riferimenti a slot condivisi, aggiornamento graduale e indicatori di ripristino, metadati di sincronizzazione dell'origine e slot gestiti, riferimenti ad applicazioni di blocco, elenchi di accesso token API, criteri di notifica del sito e integrità dello scheduler. I valori esistenti vengono copiati in batch limitati; API i payload e i campi di esportazione/importazione mantengono la struttura esistente.

I valori mappati vengono letti da SQL. I campi JSON esistenti rimangono copie temporanee di compatibilità di rollback e sono sincronizzati sulle scritture supportate. Le impostazioni non mappate e gli snapshot di revisione completa mantengono il formato di archiviazione esistente in questa fase. Vengono conservati i campi storici sconosciuti, i valori non corretti e i riferimenti non risolti. La migrazione dell'aggiornamento è ripetibile e il ripristino non elimina i nuovi dati. Se un pacchetto più vecchio scrive quelle copie dopo un rollback, riconciliare tale deriva prima di tornare alla versione SQL-autorevole.

Migrazione delle impostazioni di blocchi e applicazioni in CMS 1.98.6

Il successivo aggiornamento del pacchetto sposta le restanti impostazioni di blocco e Embedded Application elenchi di risorse/supporto/schema nei record relazionali. I campi del blocco principale hanno schemi di aspetto, media, navigazione e contenuto digitati. Le associazioni, le impostazioni della raccolta e i valori delle istanze dell'applicazione hanno record separati; i nodi digitati preservano la struttura nidificata e le estensioni storiche/plugin. Gli elenchi di risorse ed enumerazioni mantengono l'ordine e i duplicati, mentre le definizioni delle impostazioni mantengono i tipi e i valori predefiniti.

La migrazione legge un payload legacy alla volta in batch limitati ID ed è ripetibile. I campi esistenti API, renderer, locale, esportazione/importazione e revisione completa mantengono le loro strutture compatibili. SQL è autorevole; le colonne JSON esistenti rimangono copie di rollback sincronizzate. Un rollback dell'aggiornamento conserva i dati SQL, quindi rivedi eventuali scritture effettuate da un pacchetto precedente prima di riapplicare la nuova versione. Lo snapshot completo e altri contenuti/runtime legacy JSON rappresentano un lavoro di migrazione successivo.

Preparazione della migrazione relazionale restante in CMS 1.98.7

La migrazione nativa del pacchetto prepara le impostazioni di pagina, slot e layout, metadati dei blocchi, istantanee cronologiche complete, record di trasferimento, mappe di continuazione dell'importazione, dati di ripristino, ricevute di aggiornamento, elenchi di icone e motivi di moderazione in SQL. I nomi e le strutture esistenti API rimangono compatibili. Lo stato del ciclo di vita del plug-in e i piani di promozione ora scrivono SQL; i vecchi file modificabili vengono conservati fino al cutover. La preparazione è idempotente e non sostituisce lo stato del plugin più recente SQL nelle repliche.

Il bridge conserva le vecchie colonne per un programma di aggiornamento che sta già eseguendo il pacchetto precedente. Conserva il backup completo automatico durante l'installazione del cutover successivo: il solo ripristino del codice precedente non può ripristinare le colonne o i file di dati rimossi. CMS i backup completi contengono il database, i caricamenti pubblici e i file pubblici del sito; conservare separatamente il pacchetto corrispondente e qualsiasi plug-in privato/archiviazione locale richiesto.

Passaggio finale a SQL in CMS 1.98.8

Il cutover rimuove i campi temporanei e i file di stato modificabili importati dopo la preparazione/rilettura. SQL è la fonte per tutte le strutture persistenti di proprietà di CMS, inclusi gli snapshot completi indipendenti. I formati esistenti API, il pacchetto firmato, il backup immutabile e l'esportazione continuano a utilizzare la serializzazione stabilita. Publisher offre 1.98.7 prima ai client in-app precedenti; ricontrolla dopo quel ponte per applicare 1.98.8. Conserva il backup completo per tornare al codice precedente.

Installazioni precedenti mantenute da sorgente

I flussi browser e CLI seguenti valgono solo per installazioni storiche da sorgente o repository di manutenzione già dotate di un'applicazione Laravel completa. Non sono alternative all'installazione del solo repository attuale del pacchetto. Per nuove installazioni usare il flusso Composer sopra.

Procedura guidata di installazione nel browser

Usate la procedura guidata del browser per un'installazione nuova.

Quando il codice sorgente è presente in locale, iniziate con:

composer install
cp .env.example .env
php artisan serve

Poi aprite http://127.0.0.1:8000/install.

La procedura guidata copre:

controlli di prontezza dell'ambiente
configurazione del database e convalida della connessione
installazione del nucleo del CMS
creazione del primo super_admin
blocco dell'installazione al completamento

Note:

l'installer è pensato per installazioni nuove
se la configurazione è incompleta, la procedura guidata può essere riaperta e ripresa in sicurezza
al termine, le rotte di installazione vengono bloccate e subentra il normale flusso di autenticazione/amministrazione
l'installer scrive la configurazione del database selezionata in .env

Installazione manuale da CLI

Usate il flusso da CLI quando preferite un percorso di configurazione Laravel standard per un'installazione nuova.

composer install
cp .env.example .env
php artisan key:generate
php artisan migrate
php artisan db:seed
php artisan storage:link
php artisan serve

Note:

php artisan db:seed carica i cataloghi principali, crea la home con contenuto iniziale e registra la versione corrente come installata per una nuova installazione
php artisan storage:link è necessario se la distribuzione pubblica dei file deve usare storage/app/public
le cartelle di runtime sotto storage/framework, storage/logs e bootstrap/cache vengono create automaticamente alla prima esecuzione
Backup / Restore memorizza gli archivi sul disco filesystem backups, per impostazione predefinita storage/app/backups. L'utente del runtime PHP dovrebbe essere proprietario di quella cartella o condividere un gruppo di deployment con accesso in lettura/scrittura; evitate modalità 777 troppo ampie.

Installazione locale nativa

Per un progetto Laravel nuovo eseguito con PHP e Composer installati localmente:

composer require fklavyenet/webblocks-cms
php artisan webblocks:install --name="Admin User" --email="admin@example.com" --password="secret-password"

Poi aprite:

sito pubblico: /
login amministrativo: /webadmin/login
amministrazione: /webadmin

Quando il codice sorgente è presente in locale:

composer install
cp .env.example .env
php artisan key:generate

Note:

lo sviluppo locale attendibile dovrebbe usare domini .test e HTTPS, con https://webblocks-cms.test come URL canonico di sviluppo del CMS
php artisan serve resta utile per controlli rapidi solo da CLI, ma i flussi di lavoro attendibili nel browser dovrebbero usare la configurazione nativa Nginx/PHP-FPM documentata in docs/native-local-development.md
le notifiche e-mail del modulo di contatto in locale dovrebbero usare un catcher SMTP locale o un account SMTP di prova attendibile; i valori SMTP locali abituali dipendono dallo strumento installato
i destinatari delle notifiche di Contact Form si risolvono in questo ordine: recipient_email a livello di blocco, il destinatario di contatto predefinito del sito corrente, CONTACT_RECIPIENT_EMAIL e infine MAIL_FROM_ADDRESS come ultimo fallback sicuro
gli invii di contatto vengono memorizzati indipendentemente dalla consegna della notifica, quindi una risposta pubblica Message sent conferma il successo dell'archiviazione anche se in seguito l'amministrazione mostra la notifica come Failed, Skipped o Not configured
MAIL_MAILER=log, MAIL_MAILER=array e MAIL_MAILER=null non costituiscono una consegna in uscita reale e vengono mostrati come non configurati per la notifica di Contact Message
I blocchi modulo generano un wrapper nascosto con wb-sr-only, inert, aria-hidden="true", campo form_check_{token}, tabindex="-1", autocomplete="off" e timestamp firmato legato al modulo. Prova non valida o campo di controllo compilato producono lo stesso reindirizzamento di successo senza salvare messaggi né tentare notifiche.
Gli invii validi sono valutati localmente per contenuto, ripetizioni esatte o simili, IP esatto, indirizzo mittente, rete /24 o /64, raffiche del modulo e reputazione appresa del sito. Consentito, quarantena e spam restano classificazioni amministrative persistenti indipendenti dalle notifiche.
La protezione non richiede CAPTCHA né servizi esterni; le chiavi cache usano hash con chiave e le metriche di 30 giorni contengono decisioni aggregate, non i contenuti inviati.
quando la consegna della notifica fallisce, gli amministratori possono ispezionare il messaggio salvato in Admin -> Contact Messages per vedere lo stato di errore compatto nell'elenco e il dettaglio dell'errore memorizzato nella schermata di dettaglio del messaggio

Poi aprite:

sito pubblico: https://webblocks-cms.test
amministrazione: https://webblocks-cms.test/webadmin
installer in un'installazione nuova: https://webblocks-cms.test/install

Completate l'installazione nuova nella procedura guidata del browser dopo aver eseguito quei passaggi di configurazione.

Sviluppo del pacchetto e contributi

Clonare il repository non è il normale percorso di installazione per gli utenti.

Clonare il repository solo per sviluppare WebBlocks CMS o contribuire al progetto:

git clone https://github.com/fklavyenet/webblocks-cms.git
cd webblocks-cms
composer install --no-interaction --prefer-dist
composer validate --strict
composer format:test
composer test

Il repository contiene sorgenti del pacchetto, non un'applicazione Laravel distribuibile. Per il flusso di sviluppo consultare le istruzioni per contribuire e la strategia di test.

Accedere alla procedura guidata di installazione

le installazioni nuove reindirizzano automaticamente a /install
potete anche aprire manualmente la procedura guidata su /install
potete aprire /install/core per passare direttamente al passaggio di installazione del nucleo quando i requisiti precedenti sono già soddisfatti
la procedura guidata può avanzare automaticamente tra i passaggi man mano che i requisiti vengono soddisfatti
aprire / e /install in più schede del browser può mostrare passaggi diversi della procedura guidata; è previsto, perché l'installer tiene traccia dell'avanzamento e instrada di conseguenza

Creazione del primo super admin

Il primo super_admin è necessario perché un'installazione sia completa.

nella procedura guidata del browser, create il primo amministratore durante il passaggio finale di configurazione
nel flusso da CLI come pacchetto consumer, fornite --name, --email e --password a webblocks:install
in un'installazione manuale, assicuratevi che esista almeno un account super_admin attivo prima di considerare il CMS completamente installato

super_admin è il ruolo a livello di installazione che può accedere a Users, siti, lingue, impostazioni, aggiornamenti, backup, esportazione/importazione e a tutti i contenuti dei siti.

Contenuto iniziale

Una nuova installazione pubblica su / una home con marchio accanto al titolo, breve griglia di funzionalità e invito finale all'azione. Sono blocchi normali, non una schermata fissa: il nuovo amministratore trova una pagina funzionante da riscrivere, riordinare o eliminare.

Il logo viene importato nella libreria media del sito durante l'installazione e collegato al blocco come ogni immagine. È servito dall'origine del sito e può essere sostituito o eliminato. Non usa collegamenti diretti remoti, che imporrebbero richieste a terzi a ogni visitatore e dipendenza dalla disponibilità altrui. Se l'importazione è impossibile per disco in sola lettura o file assente, il blocco resta senza media senza interrompere l'installazione.

Regole per distribuirlo in sicurezza in ogni installazione:

il contenuto iniziale si scrive solo in pagine prive di blocchi, senza sovrascrivere contenuti esistenti
solo durante l'installazione; gli aggiornamenti non lo aggiungono né ripristinano
un modello assente o illeggibile viene segnalato e saltato senza interrompere l'installazione
un tipo di blocco sconosciuto viene saltato con i figli, senza errori fatali

Controlli:

WEBBLOCKS_CMS_STARTER_CONTENT=true
WEBBLOCKS_CMS_STARTER_CONTENT_PATH=
WEBBLOCKS_CMS_SEND_POWERED_BY_HEADER=true

WEBBLOCKS_CMS_STARTER_CONTENT=false installa una home pubblicata vuota. php artisan webblocks:install --skip-starter-content fa lo stesso per una singola esecuzione.
WEBBLOCKS_CMS_STARTER_CONTENT_PATH indica la directory dei modelli personalizzati quando un prodotto deve includere la propria pagina iniziale.
WEBBLOCKS_CMS_SEND_POWERED_BY_HEADER=true aggiunge X-Powered-By: WebBlocks CMS alle risposte pubbliche per identificare il prodotto senza rivelarne la versione. Impostare false se la politica dell'installazione vieta l'identificazione.

Aggiungere contenuto iniziale a un'installazione esistente

Le installazioni precedenti conservano la home vuota; gli aggiornamenti non aggiungono contenuti. Per riempirla una volta:

php artisan webblocks:starter-content

In multisito, --site=handle seleziona il sito; senza, si usa quello principale.

Crea la pagina su / se manca e scrive i blocchi solo se la pagina non ne contiene. Se esiste contenuto non interviene e ne spiega il motivo. Non tocca altre pagine; eseguirlo due volte è sicuro.

Il comando non richiede classe né conferma di produzione, perché entrambe ostacolano i runner previsti. Il pannello Artisan non può rispondere alla conferma di db:seed; un pannello ha rimosso le barre inverse da --class, facendo risolvere a Laravel Database\Seeders\WebBlocksCmsDatabaseSeedersStarterContentSeeder. La garanzia è strutturale: i contenuti iniziali si scrivono solo in pagine senza blocchi.

La stessa operazione è disponibile come seeder, eseguito da db:seed in una nuova installazione:

php artisan db:seed --class="WebBlocks\Cms\Database\Seeders\StarterContentSeeder" --force

I modelli sono file JSON in database/content/starter, con schema webblocks.cms.starter-content.v1 e vocabolario della Guida alla creazione con IA. home.json è il predefinito; la variante home.{locale}.json ha priorità se corrisponde alla lingua predefinita dell'installazione. README.md documenta il formato.

Note di configurazione comuni

l'installer viene bloccato al termine
/webadmin è il punto di ingresso amministrativo canonico del CMS
le installazioni come pacchetto consumer possono accedere tramite /webadmin/login; le app coinstallate possono mantenere il /login di proprietà dell'host
/webadmin/dashboard reindirizza a /webadmin
gli asset del CMS restano sotto /cms, per esempio /cms/css, /cms/js e /cms/brand
il /webadmin/login di proprietà del pacchetto usa viste Blade del pacchetto, lo shell di autenticazione guest di WebBlocks UI, asset di WebBlocks UI fissati, /cms/css/guest.css e gli asset di marchio del prodotto CMS da /cms/brand, comprese le varianti di favicon e scheda del browser normale, per superficie scura, su colore d'accento/inversa e ad alto contrasto
/cms è riservato agli asset pubblici statici di proprietà del CMS e non deve essere usato come prefisso, alias o redirect delle rotte amministrative del CMS
/admin non è di proprietà del CMS e non deve essere ripristinato come rotta amministrativa del CMS
le pagine nuove partono in draft
se funzionalità a livello di installazione come revisioni, backup o aggiornamenti segnalano tabelle mancanti, eseguite php artisan migrate

La separazione tra /webadmin e /cms evita la collisione di try_files in Nginx in cui /cms/ può essere risolto come la cartella fisica di asset public/cms/ prima che Laravel gestisca una rotta. Non risolvete l'accesso amministrativo aggiungendo un passaggio public/cms/index.php; quel ponte di front controller deve restare assente dagli asset pubblici della root e del pacchetto.

Preparazione di e-mail e modulo di contatto

Configurate la consegna della posta di Laravel prima di pubblicare una pagina di contatto pubblica. Una tipica configurazione SMTP in .env ha questo aspetto:

MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=no-reply@example.com
MAIL_FROM_NAME="Site Name"

CONTACT_RECIPIENT_EMAIL=contact@example.com

MAIL_* controlla la consegna della posta di Laravel per i tentativi di notifica di Contact Form. MAIL_FROM_ADDRESS è l'indirizzo mittente sicuro di fallback ed è anche l'ultimo destinatario sicuro di fallback di Contact Form quando non è configurato un destinatario più specifico. CONTACT_RECIPIENT_EMAIL è opzionale e funge da destinatario di fallback a livello di ambiente. Preferite configurare il destinatario di contatto a livello di sito in Site -> Edit -> Contact quando è disponibile, così l'instradamento dei contatti risiede con il sito e non solo in .env.

Dopo aver modificato le impostazioni di posta in .env in produzione o in un'installazione da pacchetto, svuotate la configurazione in cache se l'installazione usa la cache di configurazione:

php artisan optimize:clear

Le notifiche di Contact Form risolvono i destinatari in questo ordine:

recipient_email del blocco Contact Form
destinatario di contatto predefinito del sito, da Site -> Edit -> Contact
CONTACT_RECIPIENT_EMAIL in .env
fallback sicuro MAIL_FROM_ADDRESS

Gli invii reali accettati di Contact Form vengono memorizzati prima di tentare la notifica e-mail. Un errore di notifica non significa che l'invio pubblico del modulo sia fallito. Gli amministratori dovrebbero controllare /webadmin/contact-messages per i messaggi memorizzati, lo stato della notifica e i dettagli sicuri dell'errore. I visitatori pubblici dovrebbero vedere solo il normale riscontro di successo o di convalida, non le diagnostiche di posta.

Sent significa che il CMS ha consegnato la notifica al trasporto di posta configurato senza eccezioni; non garantisce la consegna nella casella di posta. Skipped o Not configured significano che non è stato tentato alcun invio reale della notifica.

Usate il blocco nativo contact_form per le pagine di contatto. Non sostituitelo con Trusted HTML, con markup <form> grezzo o con fallback mailto:. Il renderer del CMS genera automaticamente il campo nascosto di controllo antispam; non createlo manualmente. Il vecchio campo honeypot website non è più il contratto pubblico.

Smoke test pratico di Contact Form:

Pubblicate o visualizzate in anteprima una pagina che contiene il blocco nativo contact_form.
Inviate un messaggio di prova con nome, e-mail, oggetto e messaggio.
Aprite /webadmin/contact-messages.
Verificate che il messaggio sia stato memorizzato.
Esaminate lo stato della notifica.
Se l'e-mail non è arrivata, ispezionate i dettagli sicuri dell'errore ed eseguite le diagnostiche di posta.

Comandi di diagnostica:

php artisan contact:mail-diagnose
php artisan contact:mail-diagnose --block=ID
php artisan contact:mail-diagnose --send-test=you@example.com

Il comando di diagnostica non deve stampare password, token o segreti di posta. Usate --block=ID per ispezionare la catena di fallback dei destinatari di un singolo blocco Contact Form. Usate --send-test= solo per un controllo di invio SMTP controllato verso un indirizzo di prova intenzionale.

Passaggi successivi dopo l'installazione

Accedete a /webadmin.
Verificate la configurazione del vostro sito e delle lingue (locale).
Configurate l'identità del sito e i domini.
Configurate le impostazioni di posta di Laravel oppure le impostazioni di posta di sistema approvate.
Configurate un destinatario per il Contact Form, preferibilmente in Site -> Edit -> Contact.
Eseguite php artisan contact:mail-diagnose.
Inviate un Contact Form nativo di prova e verificate che venga salvato un Contact Message.
Controllate lo stato della notifica e-mail per quel messaggio di prova.
Aprire la home iniziale nell'editor e personalizzarla.
Create la vostra prima pagina.
Aggiungete media, navigazione e blocchi.
Pubblicate i contenuti attraverso il flusso di lavoro editoriale.

Montaggio dei contenuti pubblici

La modalità integrata conserva gli URL pubblici radice. Per affiancare un prodotto Laravel, configurare WEBBLOCKS_CMS_PUBLIC_MOUNT=wb prima di installazione/distribuzione: contenuti, ricerca e sitemap usano /wb; amministrazione/API/risorse/moduli conservano le proprie aree. Resta la rotta di benvenuto dell'host. È una configurazione globale, non del pannello o sito. Leggere Routing pubblico prima delle modifiche, soprattutto per cache, catch-all dell'host, robots e migrazione URL.