Installation

WebBlocks CMS prend en charge un flux d'installation en tant que package consommé pour les applications Laravel neuves, un assistant d'installation dans le navigateur pour les installations neuves depuis le dépôt de maintenance, ainsi qu'un chemin d'installation manuel via la CLI Laravel.

Pour une installation neuve, commencez par récupérer le code source de WebBlocks CMS sur votre machine. Exécutez Composer, créez .env, utilisez Artisan et n'ouvrez l'assistant d'installation du navigateur qu'une fois le code source présent en local.

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

Avant d'exécuter la moindre commande d'installation, assurez-vous que le dépôt WebBlocks CMS est présent en local.

Cloner dans un nouveau répertoire :

Cloner dans un répertoire vide déjà créé :

Une fois le code source présent en local, poursuivez avec l'un des chemins d'installation neuve ci-dessous.

Les installations de WebBlocks CMS sont uniquement consommatrices de mises à jour. Elles peuvent récupérer, tirer ou télécharger les mises à jour du CMS, mais elles ne doivent pas pousser de commits ni de tags vers l'upstream canonique du CMS. Pour les clones d'installation locaux existants, exécutez git remote set-url --push origin DISABLED une fois dans la copie de travail de l'installation.

Utilisez ce flux lorsque WebBlocks CMS est installé dans une application Laravel neuve via Composer.

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 site par défaut
• --site-handle= handle du site par défaut
• --repair-partial renomme les tables CMS partielles vides avant les migrations d'installation neuve
• --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 :

• 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
• amorce de manière idempotente les langues, sites, types de slot, page layouts, icônes et types de blocs essentiels
• 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.

Pour la frontière consommateur actuelle du package v1.32.x, le App\Models\User de l'application hôte reste le modèle d'authentification et la cible du correctif appliqué à l'installation.

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 :

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.

Utilisez l'assistant du navigateur pour une installation neuve.

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

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

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

Remarques :

• php artisan db:seed installe les catalogues CMS essentiels et enregistre la version actuelle de l'application comme version installée lors d'une installation neuve
• 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.

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

Ouvrez ensuite :

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

Une fois le code source présent en local :

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 Contact Form restituent un conteneur masqué .wb-form-check appartenant au CMS avec inert, aria-hidden="true", un champ form_check_{token} généré par le moteur de rendu, tabindex="-1" et autocomplete="off" ; lorsque ce champ de contrôle généré est rempli, le serveur renvoie la même redirection générique de succès et n'enregistre aucun Contact Message ni ne tente de notification
• les soumissions qui passent le champ de contrôle généré peuvent tout de même être classées comme spam par des signaux enregistrés prudents, tels qu'un langage de démarchage commercial, une densité de liens, des soumissions répétées depuis la même IP ou un argumentaire de vente envoyé depuis une messagerie gratuite avec un objet générique ; ce statut est une classification administrative durable, distincte de l'état de la notification par e-mail
• 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.

• 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

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.

• 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.

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

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 :

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

1. recipient_email du bloc Contact Form
2. destinataire de contact par défaut du site, depuis Site -> Edit -> Contact
3. CONTACT_RECIPIENT_EMAIL dans .env
4. 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 :

1. Publiez ou prévisualisez une page contenant le bloc natif contact_form.
2. Envoyez un message de test avec nom, e-mail, objet et message.
3. Ouvrez /webadmin/contact-messages.
4. Vérifiez que le message a bien été enregistré.
5. Examinez l'état de la notification.
6. 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 :

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.

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