Configuration manuelle

Cette section explique comment le fichier de configuration principal app/conf/config.yml fonctionne. C’est beaucoup plus pratique que de lancer le thème d’installation pour chaque mise à jour de configuration.

Votre fichier app/conf/config.yml est construit en utilisant la syntaxe YAML. Chaque partie correspond à la configuration d’un service de Roadiz.

Note

Par défaut, chaque environnement Roadiz lit le fichier de configuration app/conf/config.yml. Mais vous pouvez spécifier différents fichiers pour les environnements dev et test. Il suffit de créer un fichier app/conf/config_dev.yml ou app/conf/config_test.yml pour remplacer les paramètres par défaut. Vous pourrez utiliser une base de données différente, un mailer ou une instance Solr pour ne pas polluer votre environnement de production.

Source Edition

Roadiz Source edition stocke les fichiers de configuration dans le dossier conf/.

DotEnv

app/conf/config.yml can resolve .env variables if you want to add this file to your Git repository or Docker images. For example:

doctrine:
    driver: "pdo_mysql"
    host: '%env(string:MYSQL_HOST)%'
    user: '%env(string:MYSQL_USER)%'
    password: '%env(string:MYSQL_PASSWORD)%'
    dbname: '%env(string:MYSQL_DATABASE)%'
    server_version: '%env(string:MYSQL_VERSION)%'
    # "utf8mb4" charset requires at least mysql 5.7
    # due to large index requirement.
    # otherwise change it to "utf8"
    charset: utf8mb4
    default_table_options:
        charset: utf8mb4
        collate: utf8mb4_unicode_ci

This configuration will be resolved against .env:

# MySQL
MYSQL_ROOT_PASSWORD=root
MYSQL_HOST=db
MYSQL_DATABASE=roadiz
MYSQL_USER=roadiz
MYSQL_PASSWORD=roadiz
MYSQL_VERSION=8.0

Doctrine

La section de configuration la plus importante traite de la connexion à la base de données qui est gérée par Doctrine :

doctrine:
    driver: "pdo_mysql"
    host: "localhost"
    user: ""
    password: ""
    dbname: ""

Roadiz utilise Doctrine ORM pour stocker vos données. Il passera directement cette configuration YAML à Doctrine afin que vous puissiez utiliser tous les pilotes et options disponibles que vous trouverez dans la documentation officielle : http://doctrine-dbal.readthedocs.org/en/latest/reference/configuration.html

Choisissez votre modèle d’héritage

La caractéristique principale de Roadiz concerne son modèle de données polymorphique qui est stocké sur une base de données relationnelle. Cela nécessite une structure complexe qui peut conduire à des soucis de performance lorsque vous créez plus de 20-30 types de nœuds. Nous avons donc rendu le modèle d’héritage de données configurable pour permettre le passage au schéma single_table qui sera plus performant si vous avez besoin de beaucoup de types de nœuds. Cependant ce modèle de classe unique désactivera le support des champs indexables et vous ne pourrez pas créer de champs avec le même nom mais pas le même type car tous les champs de type de nœud seront créés dans la même table SQL.

Si vous avez vraiment besoin de créer des champs indexables et de mélanger les types de champs, nous vous conseillons de conserver le type d’héritage original joined table qui crée une table SQL dédiée pour chaque type de nœud. L’héritage basé sur des tables jointes peut être très utile avec un petit nombre de types de nœud (max. 20) et des champs très différents. Mais son principal inconvénient est que Roadiz a besoin de LEFT JOIN chaque table de type de nœud pour chaque requête générique avec les node-source, sauf si vous spécifiez un critère de type de nœud.

Vous pouvez configurer la stratégie Doctrine pour les classes d’héritage NodesSources dans app/conf/config.yml :

inheritance:
    # type: joined
    type: single_table
  • Héritage par tables jointes : joined
  • Héritage à l’aide d’une seule table : single_table

Avertissement

Si vous modifiez ce paramètre après avoir créé du contenu dans votre site Web, toutes les données des sources de nœud seront perdues.

Thèmes

Depuis Roadiz v1.0, les thèmes sont statiquement enregistrés dans la configuration de Roadiz pour de meilleures performances et retarder au maximum la connexion à la base de données. Vous pouvez enregistrer n’importe quel thème front-end dans votre fichier app/conf/config.yml. La priorité du thème n’est pas gérée ici mais dans chacun de vos thèmes en écrasant la valeur statique $priority;

themes:
    -
        classname: \Themes\DefaultTheme\DefaultThemeApp
        hostname: '*'
        routePrefix: ''
    -
        classname: \Themes\FooBarTheme\FooBarThemeApp
        hostname: 'foobar.test'
        routePrefix: ''

Vous pouvez définir des thèmes spécifiques au nom d’hôte et ajouter un préfixe de routage. Les valeurs par défaut sont '*' pour hostname et '' (chaîne vide) pour le préfixe de route.

Avertissement

Si vous ne configurez aucun thème, cela mènera à une erreur 404 sur la page d’accueil de votre site. Mais vous aurez toujours accès au back-office qui est enregistré en dur dans la configuration de Roadiz.

Pilotes de cache

Lorsqu’il est défini en tant que null, les pilotes de cache seront automatiquement choisis par Roadiz en fonction de votre configuration PHP et des extensions disponibles.

Parfois, si une extension de cache est disponible mais que vous ne voulez pas l’utiliser, vous devrez spécifier un autre type de pilote de cache (utilisez array pour désactiver les caches). C’est un cas connu lorsque vous utilisez des plans d’hébergement mutualisé OVH qui fournissent une extension PHP memcached mais ne vous permet pas de vous y connecter.

cacheDriver:
    type: null
    host: null
    port: null

Les types de cache disponibles sont :

  • apc
  • xcache
  • memcache (nécessite la configuration host et port)
  • memcached (nécessite la configuration host et port)
  • redis (nécessite la configuration host et port)
  • array

Gestionnaires Monolog

Par défaut, Roadiz écrit ses logs dans le dossier app/logs/ dans un fichier nommé d’après votre environnement d’exécution (par exemple. roadiz_prod.log). Mais vous pouvez aussi personnaliser Monolog pour utiliser trois gestionnaires différents. Attention : l’utilisation de gestionnaires de logs personnalisés désactivera la journalisation Roadiz par défaut (sauf pour la journalisation via Doctrine), il est donc préférable d’utiliser toujours le gestionnaire default en plus de votre gestionnaire personnalisé.

Types de gestionnaire disponibles :

  • default : gestionnaire par défaut de Roadiz qui écrit dans le dossier app/logs/ dans un fichier nommé d’après votre environnement en cours d’exécution
  • stream: Définit un flux de fichiers journaux sur votre système. Votre chemin doit être accessible en écriture !
  • rotating_file: Defines a log file stream on your local system which will be rotated to avoid large files. Your path must be writable!
  • syslog : Écrit dans le système syslog.
  • gelf : Envoie des messages formatés GELF à un point d’entrée externe défini par la valeur url. Roadiz utilise un gestionnaire qui ne déclenchera aucune erreur si votre point d’entrée externe n’est pas joignable, assurez-vous qu’il est correct. C’est une bonne idée de combiner le gestionnaire gelf avec un système de journalisation local si votre point d’entrée externe est en panne.
  • sentry: Envoyer les logs à votre instance Sentry. Nécessite une bibliothèque PHP sentry/sentry : composer require sentry/sentry php-http/curl-client guzzlehttp/psr7. C’est une bonne idée de combiner un gestionnaire sentry avec un système de journalisation local si votre point d’entrée externe est en panne.

Les valeurs type et level sont obligatoires pour chaque gestionnaire.

Voici un exemple de configuration :

monolog:
    handlers:
        default:
            type: default
            level: INFO
        file:
            type: stream
            # Be careful path must be writable by PHP
            path: '%kernel.log_dir%/roadiz.log'
            level: INFO
            level: INFO
        rotate:
            type: rotating_file
            path: '%kernel.log_dir%/roadiz.log'
            level: DEBUG
        syslog:
            type: syslog
            # Use a custom identifier
            ident: my_roadiz
            level: WARNING
        graylog:
            type: gelf
            # Gelf HTTP entry point url (with optional user:passwd authentication)
            url: http://graylog.local:12202/gelf
            level: WARNING
        sentry:
            type: sentry
            level: WARNING
            url: https://xxxxxx:xxxxxx@sentry.io/1

Point d’entrée Solr

Roadiz peut utiliser un moteur de recherche Apache Solr pour indexer les nodes-sources. Ajoutez-le à votre config.yml pour lier votre CMS à votre serveur Solr :

solr:
    endpoint:
        localhost:
            host: "localhost"
            port: "8983"
            path: "/"
            core: "mycore"
            timeout: 3
            username: ""
            password: ""

La commande CLI Roadiz peut facilement gérer l’index Solr. Il suffit de taper bin/roadiz solr:check pour obtenir plus d’informations.

Invalidation du cache des reverse-proxies

Roadiz peut demander l’invalidation du cache à des reverse-proxies externes et internes tels que Symfony AppCache ou bien une instance Varnish. Si configuré, Roadiz créera une requête BAN pour chaque proxy configuré quand l’utilisateur efface les caches depuis le back-office, et il va créer une requête PURGE sur chaque node-source mis-à-jour en utilisant la première URL de node-source accessible.

reverseProxyCache:
    frontend:
        localhost:
            host: localhost
            domainName: myapp.test
        external:
            host: varnish
            domainName: myapp.test

Note

Assurez-vous que vous avez configuré votre reverse-proxy externe pour recevoir et gérer les requêtes HTTP BAN et PURGE.

Cache proxy Cloudflare

Si vous utilisez Cloudflare comme un reverse-proxy cache, vous pouvez configurer Roadiz pour envoyer des requêtes à Cloudflare pour purger tous les éléments ou fichiers (lors de l’édition d’un node-source). Vous devez renseignez les informations suivantes :

  • Identifiant de la zone Cloudflare
  • Identifiants de l’API Cloudflare (Bearer token ou email + clé d’identification)

Ensuite, vous pouvez configurer Roadiz avec le Bearer token :

reverseProxyCache:
    frontend: []
    cloudflare:
        zone: cloudflare-zone
        bearer: ~

Ou avec votre E-mail et votre AuthKey :

reverseProxyCache:
    frontend: []
    cloudflare:
        zone: cloudflare-zone
        email: ~
        key: ~

Note

Roadiz utilise les points d’entrée Purge all files et Purge Files by URL : https://api.cloudflare.com/#zone-purge-all-files qui sont disponibles sur tous les plans Cloudflare.

Chemins des entités

Roadiz utilise Doctrine pour synchroniser les entités aux tables de votre base de données. Afin de rendre Roadiz extensible, vous pouvez ajouter vos propres chemins à la section entities.

entities:
    - "../vendor/roadiz/roadiz/src/Roadiz/Core/Entities"
    - "../vendor/roadiz/models/src/Roadiz/Core/AbstractEntities"
    - "gen-src/GeneratedNodeSources"

Configurer le mailer

Roadiz utilise Swift Mailer pour envoyer des emails. Cette bibliothèque géniale est construite pour gérer différents types de transports de courrier et de protocoles. Par défaut, Roadiz utilise votre configuration locale avec sendmail mais il est fortement recommandé d’utiliser un autre transport (comme un serveur SMTP externe) dans votre fichier app/conf/config.yml.

Vous pouvez utiliser SSL, TLS ou aucun chiffrement.

mailer:
    type: "smtp"
    host: "localhost"
    port: 25
    encryption: false
    username: ""
    password: ""

Note

Faites attention au fait que de nombreux services SMTP externes (Mandrill, Mailjet…) n’acceptent que les emails provenant de domaines validés. Assurez-vous donc que votre application utilise un expéditeur connu d’email From: pour ne pas être blacklisté ou bloqué par ces services. Si vous avez besoin de répondre à vos e-mails à une adresse anonyme, utilisez plutôt l’en-tête ReplyTo:.

Traitement des images

Roadiz utilise la bibliothèque Image Intervention pour créer automatiquement une version optimisée de votre image si elle est trop grande. Vous pouvez définir les seuils dans la section assetsProcessing. driver et defaultQuality seront également utilisés pour le traitement d’images à la volée avec la bibliothèque Intervention Request.

assetsProcessing:
    # gd or imagick (gd does not support TIFF and PSD formats)
    driver: gd
    defaultQuality: 90
    # pixel size limit () after roadiz
    # should create a smaller copy.
    maxPixelSize: 1280
    # Path to jpegoptim binary to enable jpeg optimization
    jpegoptimPath: ~
    # Path to pngquant binary to enable png optimization (3x less space)
    pngquantPath: ~
    # List additionnal Intervention Request subscribers
    subcribers: []

Extensions supplémentaires Intervention Request

N’importe quelle extension Intervention Request peut être ajoutée à la configuration avec l’aide de son classname et ses arguments constructeurs. Voici un exemple avec WatermarkListener qui imprimera du texte sur toutes vos images.

assetsProcessing:
    # List additionnal Intervention Request subscribers
    subcribers:
        - class: "AM\\InterventionRequest\\Listener\\WatermarkListener"
          args:
               - 'Copyright 2017'
               - 3
               - 50
               - "#FF0000"

Utilisez kraken.io pour réduire considérablement la taille des images

Puisque vous pouvez ajouter des extension à Intervention Request, nous avons créé une qui envoie toutes vos images au service kraken.io pour les optimiser. Une fois que vous l’avez configuré, n’oubliez pas de vider vos caches pour voir les changements.

assetsProcessing:
    # List additionnal Intervention Request subscribers
    subcribers:
        - class: "AM\\InterventionRequest\\Listener\\KrakenListener"
          args:
               - "your-api-key"
               - "your-api-secret"
               - true

Avertissement

Notez que chaque image générée est envoyée aux serveurs kraken.io. Cela peut prendre du temps pour la première génération d’image.

Commandes de console

Roadiz peut être exécuté comme un simple outil CLI en utilisant votre connexion SSH. Ceci est utile pour gérer les tâches d’administration de base sans avoir besoin d’une administration graphique.

./bin/roadiz

Si votre système n’est pas configuré pour avoir php situé dans /usr/bin/php utilisez-le de cette façon :

php ./bin/roadiz

La commande par défaut sans argument vous montrera la liste des commandes disponibles. Chaque commande a ses propres paramètres. Vous pouvez utiliser l’argument --help pour obtenir plus d’informations sur chaque outil :

./bin/roadiz install --help

Nous avons même rendu les outils CLI Doctrine directement disponibles à partir de Roadiz Console. Attention, ce sont des commandes puissantes qui peuvent modifier votre base de données et vous faire perdre des données précieuses. Surtout lorsque vous aurez besoin de mettre à jour votre schéma de base de données auprès d’un thème ou suite à une mise à jour du noyau. Faites toujours une sauvegarde de la base de données avant toute opération Doctrine.

Commandes supplémentaires

Si vous développez votre propre thème, vous devrez peut-être créer des commandes CLI personnalisées. Roadiz peut gérer des commandes supplémentaires si vous les ajoutez dans votre app/conf/config.yml comme vous le feriez pour n’importe quelle entités additionnelle. Assurez-vous que toutes les commandes supplémentaires étendent la classe Symfony\Component\Console\Command\Command.

additionalCommands:
    - \Themes\DefaultTheme\Commands\DefaultThemeCommand