Installation

Vue d'ensemble

WebBlocks CMS est distribué sous forme de package Composer installé dans une application hôte Laravel. L'application hôte reste responsable de son démarrage, de son environnement, de sa base de données, de ses files d'attente, de sa messagerie, de son planificateur, de son déploiement, de ses sauvegardes et de la racine des documents publics. Les notifications par e-mail par lots/quotidiennes et les résumés quotidiens par e-mail nécessitent le planificateur toutes les minutes ; les nouveaux sites activent ces politiques par défaut. L'affichage des messages enregistrés et des notifications du panneau ne nécessite aucune planification ni courrier sortant.

Avant de préparer un serveur de production, consultez les Exigences d'hébergement, évaluez la charge avec la Validation de capacité, comparez-la aux Résultats de capacité, explicitement provisoires, et complétez la Liste de préparation. Ces pages distinguent le contrat d'installation des dépendances facultatives d'images, courriels, planification, sauvegarde et mise à jour du paquet ; les mesures partielles ne constituent pas une certification de production.

Pour une installation normale, partez d'une application Laravel 12.55+ ou Laravel 13 nouvelle ou existante, avec sa clé et sa base de données configurées. Installez le paquet avec Composer, puis exécutez l'installateur CMS.

Une installation est considérée comme terminée lorsque l'application dispose d'une base CMS fonctionnelle :

une clé d'application existe
la base de données est accessible
les tables requises existent
les données de départ essentielles existent
le premier super_admin actif existe
un marqueur de fin d'installation est enregistré dans system_settings

Installation en tant que package consommé

Depuis la racine de l'application Laravel hôte, exécutez :

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

Ouvrez ensuite /webadmin/login. C'est la procédure principale et prise en charge pour les utilisateurs du CMS. Cloner ce dépôt ne crée pas d'application Laravel autonome.

Options prises en charge :

--name= nom d'affichage du premier super admin
--email= adresse e-mail du premier super admin
--password= mot de passe du premier super admin
--site-name= nom du premier site ; si omis, utilise WEBBLOCKS_CMS_DEFAULT_SITE_NAME lorsqu'il est configuré, sinon l'hôte normalisé de APP_URL
--site-handle= handle du site par défaut
--repair-partial renomme les tables CMS partielles vides avant les migrations d'installation neuve
--skip-starter-content publie une page d'accueil vide au lieu de la page initiale fournie
--force écrase les assets CMS appartenant au package ou les fichiers de configuration publiés lorsque c'est nécessaire

Ce que fait webblocks:install :

nomme le premier site d'après l'hôte normalisé de APP_URL, avec l'identifiant interne default ; omet www., conserve les sous-domaines significatifs et utilise Default Site pour les hôtes locaux ou IP
publie config/webblocks-cms.php lorsque l'application hôte ne le possède pas déjà
supprime de routes/web.php la route welcome intacte d'un Laravel neuf lorsque cela est sûr, après avoir créé une sauvegarde horodatée, afin que les routes publiques du CMS puissent servir /
applique un correctif à app/Models/User.php avec WebBlocks\Cms\Auth\Concerns\HasWebBlocksCmsAccess
crée une sauvegarde horodatée avant de modifier User.php
n'applique pas le correctif lorsque le trait est déjà présent
échoue clairement si User.php n'est pas une classe App\Models\User extends Authenticatable reconnaissable
exécute le chemin de migration d'installation neuve du package pour les installations consommatrices propres
détecte les schémas CMS partiels avant d'exécuter les migrations d'installation neuve et signale les tables CMS existantes, le nombre de lignes, les lignes de migration associées et les conflits de clés étrangères connus
répare les schémas CMS partiels vides uniquement lorsque --repair-partial est fourni, en renommant les tables CMS vides avec un suffixe horodaté _before_cms_install_... avant de continuer
refuse la réparation automatique lorsqu'une table CMS partielle contient des lignes
n'exécute pas de nouveau ce schéma neuf lorsque les tables CMS existent déjà
crée les tables de support Laravel sans exécuter les migrations de l'application hôte ; cela couvre actuellement les jetons de réinitialisation de mot de passe du CMS ainsi que sessions, cache et cache_locks lorsque ces pilotes adossés à la base de données sont configurés
n'exécute pas l'ensemble normal de migrations Laravel de l'application hôte dans le cadre de l'installation du package, ce qui évite les conflits avec la table users compatible CMS déjà créée
prépare la racine du disque de système de fichiers backups utilisé par Backup / Restore
installe les assets CMS appartenant au package dans public/cms
crée public/storage lorsqu'il est absent et que l'environnement le permet
initialise de façon idempotente les langues, sites, types d'emplacement, mises en page et types de bloc principaux
charge tout le catalogue d'icônes WebBlocks UI depuis le manifeste du paquet ; les champs fonctionnent sans réseau externe ni synchronisation manuelle
crée la page d'accueil publiée à /, avec ses emplacements de mise en page
remplit cette page avec le contenu initial fourni, sauf désactivation
enregistre la version installée et le marqueur de fin d'installation dans system_settings
crée le premier super_admin actif uniquement lorsqu'il n'en existe pas déjà un

L'authentification du package est native à Laravel et ne nécessite ni Breeze, ni Jetstream, ni Laravel UI, ni Fortify. Après l'installation, connectez-vous sur /webadmin/login lorsque les routes d'authentification du package CMS sont actives. Les vues d'authentification appartenant au CMS et les redirections d'invité dans l'administration utilisent des noms de routes du package tels que webblocks.auth.login et webblocks.auth.logout, si bien qu'un produit hôte peut conserver sa propre route globale login, par exemple /quiztem/login, sans accaparer les actions de formulaire du CMS ni les redirections vers /webadmin.

Dans le modèle actuel d'installation du paquet, App\Models\User de l'application hôte reste le modèle d'authentification et la cible de modification à l'installation.

Récupération d'une installation partielle

Si webblocks:install s'arrête après une exécution précédente échouée ou interrompue, relancez-le d'abord sans réparation et lisez le diagnostic d'installation partielle. Les tables CMS vides peuvent être écartées explicitement :

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

Le mode réparation se contente de renommer les tables candidates vides appartenant au CMS. Il ne supprime aucune table, ne modifie pas automatiquement les tables non vides et ne présume pas que le CMS est propriétaire de l'application hôte.

Notifications du panneau sans planificateur (CMS 1.96.0)

Pour les responsables des opérations du site, la cloche de notification de l'en-tête d'administrateur renvoie à Tableau de bord → Notifications du panneau. Le panneau lit les messages de contact enregistrés à chaque chargement d'une page du panneau, même lorsque la messagerie électronique est désactivée ou que le planificateur n'a jamais été exécuté. Il affiche les messages non lus et les messages en attente de réponse par site accessible, avec des liens vers la boîte de réception des contacts filtrés. Les messages non lus sont inclus dans le nombre de réponses en attente. Le badge cloche compte uniquement les messages de contact non lus ; Les messages lus en attente de réponse et les avertissements du système restent séparés sur le tableau de bord. Sans messages non lus, la cloche est masquée ; le panneau de notification du tableau de bord reste disponible. L'icône Actions ouvre la boîte de réception du site sélectionné pour examiner les messages en attente de réponse, qui peuvent inclure des messages déjà lus. Les décomptes et les liens n'incluent jamais les sites inaccessibles et le résumé n'affiche pas les détails des visiteurs.

L'ouverture du panneau ne marque pas les messages comme lus, n'envoie pas d'e-mails en attente, ne réessaye pas la livraison ayant échoué ou ne fabrique pas l'état du planificateur. La lecture d'un message de contact réduit le travail non lu mais le laisse en attente de réponse ; le marquer comme ayant répondu ou comme archivé le supprime de ce résumé. Le spam et les messages mis en quarantaine restent dans la boîte de réception de modération plutôt que dans le nombre de travaux en attente. Il s’agit d’un état de boîte de réception partagée, actualisé lors du chargement des pages, et non d’un historique de notifications personnel. Live Chat conserve son propre indicateur de panneau autorisé, indépendant des e-mails programmés.

La messagerie immédiate uniquement avec les résumés quotidiens désactivés fonctionne également sans planificateur, à condition que le courrier sortant soit configuré. Les e-mails groupés/quotidiens et les rappels quotidiens par e-mail nécessitent toujours une planification en arrière-plan : la connexion au CMS ne peut pas garantir la livraison à l'heure sélectionnée lorsque personne ne visite le panneau.

Notifications planifiées et santé du planificateur

Les nouveaux sites de CMS 1.95.0 utilisent par défaut des lots de messages de dix minutes et un résumé quotidien des messages en attente. Avant d'activer ces fonctionnalités en production, l'administrateur du serveur ou le fournisseur d'hébergement doit configurer le planificateur de Laravel pour qu'il s'exécute toutes les minutes. Les mises à jour enregistrent les tâches CMS sans installer silencieusement une entrée de serveur cron. CMS 1.105.25 propose également la configuration facultative et explicitement confirmée CLI ci-dessous. La personne qui exploite le CMS sélectionne la politique de notification ; l'administrateur du serveur est propriétaire du runtime en arrière-plan.

Ajoutez une entrée à la crontab de l'utilisateur de l'application ou au service d'hébergement de tâches planifiées équivalent :

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

Remplacez les deux exemples de chemins par le répertoire hôte Laravel réel contenant artisan et l'exécutable CLI PHP approprié. Web et CLI PHP doivent satisfaire aux exigences du CMS. Si cette application dispose déjà d'un planificateur Laravel fonctionnel, conservez cette entrée ; le nouveau travail rejoint le planning existant. Un agent de file d'attente permanent n'est pas requis par cette implémentation de notification synchrone.

À partir de CMS 1.105.25, ouvrez Nettoyage → Rétention et automatisation → Configuration et vérification du planificateur , ou le lien de configuration dans System Health. L'écran en lecture seule affiche les commandes pour cette installation, l'état réel du battement de cœur et un lien d'actualisation. Vérifiez le chemin CLI PHP affiché auprès de votre fournisseur ; si nécessaire, configurez WEBBLOCKS_CMS_SCHEDULER_PHP_BINARY et actualisez la configuration de l'application. Herne n’est pas obligatoire. Tout panneau d'hébergement prenant en charge une commande toutes les minutes peut utiliser la commande standard cron ci-dessus.

Sur un hôte Unix pris en charge avec accès CLI, exécutez les commandes avec le compte système propriétaire d’artisan, capable de lire l’application et d’écrire dans ses répertoires d’exécution. N’utilisez jamais root :

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

La première commande effectue uniquement une inspection. La seconde exige une confirmation après examen des tâches cron, systemd et du panneau d’hébergement ; pour une installation non interactive déjà vérifiée, utilisez --install --yes. --json fournit un résultat sans données sensibles et sans question interactive. L’installation conserve le contenu du crontab, ajoute une entrée marquée exécutée chaque minute et la relit. Les entrées existantes ou ambiguës, une activité réelle récente, les définitions externes lisibles, les shells non pris en charge, les comptes incorrects et les erreurs d’accès empêchent l’installation. Toutes les définitions du fournisseur ou illisibles ne peuvent pas être détectées : examinez-les avant de confirmer. Sans accès CLI/crontab, utilisez le panneau d’hébergement ou demandez au fournisseur d’ajouter la commande. Une mise à jour du CMS ne peut garantir les permissions système dans tous les hébergements.

Une entrée cron installée reste non vérifiée jusqu’à l’exécution de la tâche réellement planifiée. Attendez 1–2 minutes, actualisez l’activité enregistrée et consultez la commande d’état ci-dessous. L’écran de configuration indique le signal d’activité ; la commande complète de santé/état vérifie aussi l’exécution des notifications. N’ajoutez pas un autre planificateur simplement parce que le nettoyage attend son heure quotidienne. Les mises à jour conservent la politique enregistrée et les catégories automatiques sélectionnées de chaque installation ; examinez-les et enregistrez-les séparément.

Configurez également un véritable transport de courrier sortant, le HTTPS canonique APP_URL et un cache partagé prenant en charge les verrous atomiques lorsque plusieurs travailleurs peuvent traiter les notifications. La mise à niveau du site existant préserve les notifications complètes/immédiates avec les rappels quotidiens désactivés ; ces paramètres de notification ne nécessitent pas de planification jusqu'à ce qu'ils soient modifiés.

CMS 1.95.1 ajoute la santé enregistrée au tableau de bord et Sites → Modifier → Contact, et Live Chat 0.7.1 l'expose dans ses paramètres et la santé du plugin. L'API de notification de site inclut scheduler_health. Vérifiez les tâches enregistrées, puis les preuves d'exécution enregistrées :

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

Les utilisateurs disposant d'un accès à l'intégrité du système consultent l'avis complet du planificateur dans Maintenance → Intégrité du système → Notifications planifiées ; leur tableau de bord affiche un résumé compact de la santé. Les responsables des opérations de site sans cet accès conservent la carte de planification détaillée sur leur tableau de bord, même lorsque tous les sites accessibles utilisent des notifications immédiates uniquement avec les résumés quotidiens désactivés. Dans ce cas, la carte est informative et explique que ces notifications ne nécessitent pas de planification. Si un site accessible permet le groupage, la livraison quotidienne ou les résumés quotidiens, un état de santé non vérifié ou retardé déclenche l'avertissement ; les sites inaccessibles n’influencent jamais l’avis.

La liste des tâches confirme uniquement l'inscription. Running nécessite un battement de cœur programmé récent et une exécution de notification récemment terminée. Pas encore vérifié signifie qu'aucune preuve d'exécution fiable n'a été enregistrée. Delayed signifie qu’un battement de cœur ou une exécution terminée date de plus de cinq minutes. Un échec de traitement ou un schéma de notification manquant est affiché séparément. Une exécution en cours peut afficher brièvement In progress. La commande status se termine avec succès uniquement si l'état d'exécution est vérifié ; d'autres États renvoient un statut différent de zéro.

Le battement de cœur est produit par un rappel planifié réel. L’exécution manuelle de php artisan webblocks:notifications:dispatch peut traiter le courrier dû, mais n’établit pas l’état du planificateur. Les lectures de santé ne créent pas de battement de cœur. Les preuves sont stockées dans la base de données CMS et restent visibles dans les processus Web et CLI. Les horodatages sont renvoyés au format UTC ; les heures de résumé quotidien suivent toujours le fuseau horaire de chaque site. Aucun contenu client, secret ou texte d'exception brut n'entre dans ce dossier de santé.

Si la planification n'est pas vérifiée ou est retardée alors que les lots ou les résumés quotidiens sont activés, le panneau avertit que les notifications peuvent rester en attente et identifie l'administrateur/fournisseur du serveur comme propriétaire de la configuration. Demandez à ce propriétaire d'inspecter cron ou le planificateur d'hébergement, le chemin de l'application, la CLI PHP, les autorisations de processus et les erreurs d'exécution. Confirmez ensuite un nouveau battement de cœur et une exécution de notification terminée. Ces contrôles confirment l'exécution enregistrée sur cette installation ; ils ne garantissent pas la livraison dans la boîte de réception du destinataire ni ne certifient indépendamment chaque nœud de serveur.

Mettre à jour les installations existantes

Consultez Mises à jour pour le processus, les sauvegardes et la compatibilité. Les installations Publisher antérieures à 1.89.1 doivent appliquer la version de transition de licence 1.89.1 avant 1.89.2 ou ultérieure. Vérifiez ensuite à nouveau ; les clients récents le font automatiquement. Les installations Composer peuvent se mettre à jour directement sans cette transition Publisher.

La documentation utilisateur est maintenue séparément dans docs/ du dépôt webblocks-cms-docs ; elle n'est pas installée avec le CMS. Le paquet conserve le contrat de création resources/contracts/inventory.md, également accessible via GET /webadmin/api/inventory. Les docs et guides publics sont des destinations de publication ; la séparation n'a pas introduit de moteur de synchronisation.

Migration des données d’exécution vers des tables relationnelles dans CMS 1.98.5

La mise à jour du package ajoute un stockage relationnel pour la mise en page et les références d'emplacement partagé, les marqueurs de mise à jour et de restauration par étapes, les métadonnées de synchronisation source et les emplacements gérés, les références d'application de blocage, les listes d'accès aux jetons API, les politiques de notification de site et l'état du planificateur. Les valeurs existantes sont copiées par lots délimités ; API Les charges utiles et les champs d'exportation/importation conservent leur structure existante.

Les valeurs mappées sont lues à partir de SQL. Les champs JSON existants restent des copies de compatibilité de restauration temporaires et sont synchronisés sur les écritures prises en charge. Les paramètres non mappés et les instantanés de révision complète conservent leur format de stockage existant au cours de cette phase. Les champs historiques inconnus, les valeurs mal formées et les références non résolues sont préservés. La migration de mise à jour est reproductible et sa restauration ne supprime pas les nouvelles données. Si un package plus ancien écrit ces copies après une restauration, réconciliez cette dérive avant de revenir à la version faisant autorité SQL.

Migration des paramètres des blocs et des applications dans CMS 1.98.6

La prochaine mise à jour du package déplace les paramètres de bloc restants et les listes d'actifs/support/schéma Embedded Application dans des enregistrements relationnels. Les champs des blocs de base ont des schémas d'apparence, de média, de navigation et de contenu typés. Les liaisons, les paramètres de collection et les valeurs d'instance d'application ont des enregistrements distincts ; les nœuds typés préservent la structure imbriquée et les extensions historiques/plugin. Les listes d'actifs et d'énumérations conservent l'ordre et les doublons, et les définitions de paramètres conservent leurs types et leurs valeurs par défaut.

La migration lit une charge utile héritée à la fois dans des lots limités de ID et est reproductible. Les champs existants API, moteur de rendu, paramètres régionaux, export/importation et révision complète conservent leurs structures compatibles. SQL fait autorité ; les colonnes JSON existantes restent des copies de restauration synchronisées. Une restauration de mise à jour conserve les données SQL, donc examinez toutes les écritures effectuées par un ancien package avant de réappliquer la nouvelle version. L'instantané complet et d'autres contenus/environnements d'exécution hérités JSON sont des travaux de migration ultérieurs.

Préparation de la migration relationnelle restante dans CMS 1.98.7

La migration native du package prépare les paramètres de page, d'emplacement et de mise en page, les métadonnées de bloc, les instantanés historiques complets, les enregistrements de transfert, les cartes de continuation d'importation, les données de récupération, les reçus de mise à jour, les listes d'icônes et les raisons de modération dans SQL. Les noms et structures API existants restent compatibles. L'état du cycle de vie du plugin et les plans de promotion sont désormais écrits SQL ; les anciens fichiers mutables sont conservés jusqu'au basculement. La préparation est idempotente et ne remplace pas l'état du plugin SQL plus récent lors des réexécutions.

Le pont conserve les anciennes colonnes pour un programme de mise à jour exécutant déjà le package précédent. Conservez la sauvegarde complète automatique lors de l'installation du basculement suivant : la restauration seule du code plus ancien ne peut pas restaurer les colonnes ou les fichiers de données supprimés. CMS les sauvegardes complètes contiennent la base de données, les téléchargements publics et les fichiers publics du site ; conservez séparément le package correspondant et tout plugin privé/stockage local requis.

Basculement final vers SQL dans CMS 1.98.8

Le basculement supprime les champs temporaires et les fichiers d'état mutables importés après préparation/relecture. SQL est la source de toutes les structures persistantes appartenant à CMS, y compris les instantanés complets indépendants. Les formats de sauvegarde et d'exportation immuables existants API, packages signés, continuent d'utiliser leur sérialisation établie. Publisher propose 1.98.7 d'abord aux clients intégrés à l'application antérieurs ; vérifiez à nouveau après ce pont pour appliquer 1.98.8. Conservez la sauvegarde complète pour un retour à l'ancien code.

Anciennes installations maintenues depuis les sources

Les procédures navigateur et CLI suivantes concernent uniquement les anciennes installations depuis les sources ou un dépôt de maintenance contenant déjà une application Laravel complète. Elles ne remplacent pas l'installation du seul dépôt actuel du paquet. Pour une nouvelle installation, utilisez Composer comme indiqué ci-dessus.

Assistant d'installation dans le navigateur

Utilisez l'assistant du navigateur pour une installation neuve.

Une fois le code source présent en local, commencez par :

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

Ouvrez ensuite http://127.0.0.1:8000/install.

L'assistant couvre :

vérifications de préparation de l'environnement
configuration de la base de données et validation de la connexion
installation du cœur du CMS
création du premier super_admin
verrouillage de l'installation une fois terminée

Remarques :

l'installateur est destiné aux installations neuves
si la configuration est incomplète, l'assistant peut être rouvert et repris en toute sécurité
une fois terminé, les routes d'installation sont verrouillées et le flux normal d'authentification/administration prend le relais
l'installateur écrit la configuration de base de données sélectionnée dans .env

Installation manuelle en CLI

Utilisez le flux CLI lorsque vous préférez un chemin de configuration Laravel standard pour une installation neuve.

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

Remarques :

php artisan db:seed initialise les catalogues principaux, crée la page d'accueil avec son contenu initial et enregistre la version courante comme version installée lors d'une nouvelle installation
php artisan storage:link est nécessaire si la diffusion publique des fichiers doit utiliser storage/app/public
les répertoires de runtime sous storage/framework, storage/logs et bootstrap/cache sont créés automatiquement au premier lancement
Backup / Restore stocke les archives sur le disque de système de fichiers backups, par défaut storage/app/backups. L'utilisateur du runtime PHP devrait posséder ce répertoire ou partager un groupe de déploiement disposant d'un accès en lecture/écriture ; évitez les modes 777 trop larges.

Installation locale native

Pour un projet Laravel neuf exécuté avec PHP et Composer installés localement :

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

Ouvrez ensuite :

site public : /
connexion à l'administration : /webadmin/login
administration : /webadmin

Une fois le code source présent en local :

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

Remarques :

le développement local de confiance devrait utiliser des domaines .test et HTTPS, avec https://webblocks-cms.test comme URL de développement canonique du CMS
php artisan serve reste utile pour des vérifications rapides en CLI uniquement, mais les flux de travail de confiance dans le navigateur devraient utiliser la configuration native Nginx/PHP-FPM documentée dans docs/native-local-development.md
les notifications par e-mail du formulaire de contact en local devraient utiliser un collecteur SMTP local ou un compte SMTP de test de confiance ; les valeurs SMTP locales habituelles dépendent de l'outil installé
les destinataires des notifications de Contact Form sont résolus dans cet ordre : recipient_email au niveau du bloc, le destinataire de contact par défaut du site courant, CONTACT_RECIPIENT_EMAIL, puis MAIL_FROM_ADDRESS comme dernier repli sûr
les soumissions de contact sont enregistrées indépendamment de la remise de la notification : une réponse publique Message sent confirme donc la réussite de l'enregistrement même si l'administration affiche ensuite la notification comme Failed, Skipped ou Not configured
MAIL_MAILER=log, MAIL_MAILER=array et MAIL_MAILER=null ne constituent pas une remise sortante réelle et sont affichés comme non configurés pour la notification de Contact Message
Les blocs de formulaire génèrent un conteneur masqué avec wb-sr-only, inert, aria-hidden="true", le champ form_check_{token}, tabindex="-1", autocomplete="off" et un horodatage signé lié au formulaire. Une preuve invalide ou un champ de contrôle rempli produit la même redirection de succès sans enregistrer de message ni tenter de notification.
Les envois valides sont évalués localement selon le contenu, les répétitions exactes ou proches, l'IP exacte, l'adresse de l'expéditeur, le réseau /24 ou /64, les rafales du formulaire et la réputation apprise du site. Autorisé, quarantaine et spam restent des classifications durables indépendantes des notifications.
La protection ne nécessite ni CAPTCHA ni service externe ; les clés de cache utilisent des hachages à clé et les métriques sur 30 jours contiennent des décisions agrégées plutôt que le contenu envoyé.
lorsque la remise de la notification échoue, les administrateurs peuvent consulter le message enregistré sous Admin -> Contact Messages pour voir l'état d'échec compact dans la liste et le détail de l'échec enregistré sur l'écran de détail du message

Ouvrez ensuite :

site public : https://webblocks-cms.test
administration : https://webblocks-cms.test/webadmin
installateur lors d'une installation neuve : https://webblocks-cms.test/install

Terminez l'installation neuve dans l'assistant du navigateur une fois ces étapes de configuration effectuées.

Développement du paquet et contributions

Cloner le dépôt n'est pas la procédure d'installation normale pour les utilisateurs.

Clonez le dépôt uniquement pour développer WebBlocks CMS ou y contribuer :

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

Le dépôt contient les sources du paquet, pas une application Laravel déployable. Consultez les instructions de contribution au produit et la stratégie de test pour le développement.

Accéder à l'assistant d'installation

les installations neuves redirigent automatiquement vers /install
vous pouvez aussi ouvrir l'assistant manuellement sur /install
vous pouvez ouvrir /install/core pour accéder directement à l'étape d'installation du cœur lorsque les prérequis antérieurs sont déjà satisfaits
l'assistant peut passer automatiquement aux étapes suivantes à mesure que les prérequis sont satisfaits
ouvrir / et /install dans plusieurs onglets du navigateur peut afficher des étapes différentes de l'assistant ; c'est attendu, car l'installateur suit la progression et achemine en conséquence

Création du premier super admin

Le premier super_admin est requis pour qu'une installation soit terminée.

dans l'assistant du navigateur, créez le premier administrateur lors de l'étape finale de configuration
dans le flux CLI en tant que package consommé, fournissez --name, --email et --password à webblocks:install
dans une installation manuelle, assurez-vous qu'au moins un compte super_admin actif existe avant de considérer le CMS comme entièrement installé

super_admin est le rôle au niveau de l'installation qui peut accéder à Users, aux sites, aux langues, aux paramètres, aux mises à jour, aux sauvegardes, à l'export/import et à tout le contenu des sites.

Contenu initial

Une nouvelle installation publie à / une page d'accueil avec la marque à côté du titre, une courte grille de fonctionnalités et un appel final à l'action. Ce sont des blocs ordinaires, pas un écran d'accueil figé : le nouvel administrateur peut les réécrire, réordonner ou supprimer.

Le logo est importé dans la médiathèque du site à l'installation et lié au bloc comme toute image. Il est servi depuis l'origine du site et peut être remplacé ou supprimé. Aucun lien direct distant : cela imposerait une requête tierce à chaque visiteur et une dépendance à un autre serveur. Si l'import échoue, par disque en lecture seule ou fichier absent, le bloc reste sans média et l'installation continue.

Règles garantissant la sécurité pour tous les modes d'installation :

le contenu initial est écrit uniquement sur une page sans aucun bloc ; il n'écrase jamais de contenu existant
uniquement à l'installation ; les mises à jour ne l'ajoutent ni ne le restaurent
un modèle absent ou illisible est signalé puis ignoré, sans interrompre l'installation
un type de bloc inconnu est ignoré avec ses enfants, sans faire échouer l'installation

Contrôles :

WEBBLOCKS_CMS_STARTER_CONTENT=true
WEBBLOCKS_CMS_STARTER_CONTENT_PATH=
WEBBLOCKS_CMS_SEND_POWERED_BY_HEADER=true

WEBBLOCKS_CMS_STARTER_CONTENT=false installe une page d'accueil publiée vide. php artisan webblocks:install --skip-starter-content fait de même pour une seule exécution.
WEBBLOCKS_CMS_STARTER_CONTENT_PATH désigne votre répertoire de modèles lorsqu'un produit doit fournir sa propre page initiale.
WEBBLOCKS_CMS_SEND_POWERED_BY_HEADER=true ajoute X-Powered-By: WebBlocks CMS aux réponses publiques pour identifier le produit sans révéler sa version. Utilisez false si la politique d'installation exige de masquer cette identification.

Ajouter du contenu initial à une installation existante

Les installations antérieures conservent leur page vide ; les mises à jour n'ajoutent pas de contenu. Pour la remplir une fois :

php artisan webblocks:starter-content

En multisite, --site=handle sélectionne le site ; sinon, le site principal est utilisé.

Crée la page à / si elle manque et écrit les blocs seulement si elle n'en contient aucun. En présence de contenu, ne fait rien et explique pourquoi. Ne touche à aucune autre page ; deux exécutions sont sûres.

La commande ne demande ni classe ni confirmation de production, incompatibles avec les exécuteurs visés. Le panneau Artisan ne peut répondre à l'invite de db:seed ; un panneau a supprimé les antislashs de --class, faisant résoudre Database\Seeders\WebBlocksCmsDatabaseSeedersStarterContentSeeder par Laravel. La garantie est structurelle : le contenu initial est écrit uniquement sur une page sans blocs.

La même opération est disponible comme seeder, exécuté par db:seed lors d'une nouvelle installation :

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

Les modèles sont des fichiers JSON dans database/content/starter, utilisant le schéma webblocks.cms.starter-content.v1 et les blocs du Guide de création avec l'IA. home.json est le modèle par défaut ; home.{locale}.json est prioritaire si sa langue correspond à celle de l'installation. README.md décrit le format.

Remarques de configuration courantes

l'installateur est verrouillé une fois terminé
/webadmin est le point d'entrée d'administration canonique du CMS
les installations en tant que package consommé peuvent se connecter via /webadmin/login ; les applications co-installées peuvent conserver leur /login appartenant à l'hôte
/webadmin/dashboard redirige vers /webadmin
les assets du CMS restent sous /cms, par exemple /cms/css, /cms/js et /cms/brand
le /webadmin/login appartenant au package utilise les vues Blade du package, la coque d'authentification invité de WebBlocks UI, des assets WebBlocks UI épinglés, /cms/css/guest.css et les assets de marque du produit CMS depuis /cms/brand, y compris les variantes de favicon et d'onglet de navigateur normale, pour surface sombre, sur couleur d'accent/inversée et à contraste élevé
/cms est réservé aux assets publics statiques appartenant au CMS et ne doit pas servir de préfixe, d'alias ou de redirection pour les routes d'administration du CMS
/admin n'appartient pas au CMS et ne doit pas être rétabli comme route d'administration du CMS
les nouvelles pages démarrent en draft
si des fonctionnalités au niveau de l'installation comme les révisions, les sauvegardes ou les mises à jour signalent des tables manquantes, exécutez php artisan migrate

La séparation entre /webadmin et /cms évite la collision try_files de Nginx où /cms/ peut être résolu comme le répertoire d'assets physique public/cms/ avant que Laravel ne traite une route. Ne résolvez pas l'accès à l'administration en ajoutant un relais public/cms/index.php ; ce pont de contrôleur frontal doit rester absent des assets publics de la racine et du package.

Préparation de la messagerie et du formulaire de contact

Configurez la remise du courrier Laravel avant de publier une page de contact publique. Une configuration SMTP typique dans .env ressemble à ceci :

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_* contrôle la remise du courrier Laravel pour les tentatives de notification de Contact Form. MAIL_FROM_ADDRESS est l'adresse d'expéditeur sûre de repli et constitue aussi le dernier destinataire de repli sûr de Contact Form lorsqu'aucun destinataire plus spécifique n'est configuré. CONTACT_RECIPIENT_EMAIL est facultatif et joue le rôle de destinataire de repli au niveau de l'environnement. Préférez configurer le destinataire de contact au niveau du site dans Site -> Edit -> Contact lorsque c'est possible, afin que l'acheminement des contacts vive avec le site et non uniquement dans .env.

Après avoir modifié les paramètres de messagerie de .env en production ou dans une installation par package, videz la configuration mise en cache si l'installation utilise la mise en cache de configuration :

php artisan optimize:clear

Les notifications de Contact Form résolvent les destinataires dans cet ordre :

recipient_email du bloc Contact Form
destinataire de contact par défaut du site, depuis Site -> Edit -> Contact
CONTACT_RECIPIENT_EMAIL dans .env
repli sûr MAIL_FROM_ADDRESS

Les soumissions réelles acceptées de Contact Form sont enregistrées avant toute tentative de notification par e-mail. Un échec de notification ne signifie pas que la soumission publique du formulaire a échoué. Les administrateurs devraient consulter /webadmin/contact-messages pour les messages enregistrés, l'état de la notification et les détails d'échec sûrs. Les visiteurs publics ne devraient voir que le retour normal de succès ou de validation, et non des diagnostics de messagerie.

Sent signifie que le CMS a remis la notification au transport de messagerie configuré sans exception ; cela ne garantit pas la remise dans la boîte de réception. Skipped ou Not configured signifient qu'aucun envoi réel de notification n'a été tenté.

Utilisez le bloc natif contact_form pour les pages de contact. Ne le remplacez pas par Trusted HTML, par du balisage <form> brut ni par des replis mailto:. Le moteur de rendu du CMS génère automatiquement le champ masqué de contrôle anti-spam ; ne le créez pas manuellement. L'ancien champ honeypot website n'est plus le contrat public.

Test de fumée pratique de Contact Form :

Publiez ou prévisualisez une page contenant le bloc natif contact_form.
Envoyez un message de test avec nom, e-mail, objet et message.
Ouvrez /webadmin/contact-messages.
Vérifiez que le message a bien été enregistré.
Examinez l'état de la notification.
Si l'e-mail n'est pas arrivé, examinez les détails d'échec sûrs et exécutez les diagnostics de messagerie.

Commandes de diagnostic :

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

La commande de diagnostic ne doit afficher ni mots de passe, ni jetons, ni secrets de messagerie. Utilisez --block=ID pour inspecter la chaîne de repli des destinataires d'un bloc Contact Form. Utilisez --send-test= uniquement pour une vérification d'envoi SMTP contrôlée vers une adresse de test intentionnelle.

Étapes suivantes après l'installation

Connectez-vous à /webadmin.
Vérifiez la configuration de votre site et des langues (locales).
Configurez l'identité du site et les domaines.
Configurez les paramètres de messagerie de Laravel ou les paramètres de messagerie système approuvés.
Configurez un destinataire pour le Contact Form, de préférence dans Site -> Edit -> Contact.
Exécutez php artisan contact:mail-diagnose.
Envoyez un Contact Form natif de test et vérifiez qu'un Contact Message est bien enregistré.
Consultez l'état de la notification par e-mail de ce message de test.
Ouvrez la page initiale dans l'éditeur et personnalisez-la.
Créez votre première page.
Ajoutez des médias, la navigation et des blocs.
Publiez le contenu via le flux de travail éditorial.

Point de montage du contenu public

Le mode intégré conserve les URL publiques racine. Pour cohabiter avec un produit Laravel, configurez WEBBLOCKS_CMS_PUBLIC_MOUNT=wb avant installation/déploiement : contenu, recherche et sitemap utilisent /wb ; administration/API/ressources/formulaires gardent leurs espaces. La route d'accueil hôte est conservée. C'est une configuration globale, pas du panneau ou du site. Consultez Routage public avant toute modification, notamment pour le cache, les routes générales hôtes, robots et la migration d'URL.