Configuration

Tous les fichiers de configuration Grav sont écrits en syntaxe YAML avec une extension de fichier .yaml. YAML est très intuitif, ce qui le rend très facile à lire et à écrire, cependant, vous pouvez consulter la page YAML dans le chapitre Avancé pour avoir une compréhension complète de la syntaxe disponible.

Configuration du système

Grav s'attache à rendre les choses aussi simples que possible pour l'utilisateur, et il en va de même pour la configuration. Grav est livré avec quelques options par défaut, et celles-ci sont contenues dans un fichier qui réside dans le fichier system/config/system.yaml.

Cependant, vous ne devez jamais modifier ce fichier, à la place, toutes les modifications de configuration que vous devez apporter doivent être stockées dans un fichier appelé user/config/system.yaml. Tout paramètre de ce fichier ayant la même structure et le même nom remplacera le paramètre fourni dans le fichier de configuration système par défaut.

Voici les variables présentes dans le fichier par défaut system/config/system.yaml :

Options de base

1  | absolute_urls: false
2  | timezone: ''
3  | default_locale:
4  | param_sep: ':'
5  | wrapped_site: false
6  | reverse_proxy_setup: false
7  | force_ssl: false
8  | force_lowercase_urls: true
9  | custom_base_url: ''
10 | username_regex: '^[a-z0-9_-]{3,16}$'
11 | pwd_regex: '(?=.*\d)(?=.*[a-z])(?=.*[A-Z]).{8,}'
12 | intl_enabled: true
13 | http_x_forwarded:
14 |    protocol: true
15 |    host: false
16 |    port: true
17 |    ip: true

Ces options de configuration n'apparaissent pas dans leurs propres sections enfant. Ce sont des options générales qui affectent le fonctionnement du site, son fuseau horaire et son URL de base.

Langues

1  | languages:
2  |   supported: []
3  |   default_lang:
4  |   include_default_lang: true
5  |   include_default_lang_file_extension: true
6  |   pages_fallback_only: false
7  |   translations: true
8  |   translations_fallback: true
9  |   session_store_active: false
10 |   http_accept_language: false
11 |   override_locale: false
12 |   content_fallback: {}

La zone Langues du fichier établit les paramètres de langue du site. Cela inclut les langues prises en charge, la désignation de la langue par défaut dans les URL et les traductions. Voici la répartition de la zone Langues du fichier de configuration système :

Home

1 | home:
2 |   alias : '/home'
3 |   hide_in_urls : false

La section Home est l'endroit où vous définissez le chemin par défaut pour la page d'accueil du site. Vous pouvez également choisir de masquer la route d'accueil dans les URL.

Pages

1  | pages:
2  |   type: regular
3  |   theme: quark
4  |   order:
5  |     by: default
6  |     dir: asc
7  |   list:
8  |     count: 20
9  |   dateformat:
10 |     default:
11 |     short: 'jS M Y'
12 |     long: 'F jS \a\t g:ia'
13 |   publish_dates: true
14 |   process:
15 |     markdown: true
16 |     twig: false
17 |   twig_first: false
18 |   never_cache_twig: false
19 |   events:
20 |     page: true
21 |     twig: true
22 |   markdown:
23 |     extra: false
24 |     auto_line_breaks: false
25 |     auto_url_links: false
26 |     escape_markup: false
27 |     special_chars:
28 |       '>': 'gt'
29 |       '<': 'lt'
30 |     valid_link_attributes:
31 |       - rel
32 |       - target
33 |       - id
34 |       - class
35 |       - classes
36 |   types: [html,htm,xml,txt,json,rss,atom]
37 |   append_url_extension: ''
38 |   expires: 604800
39 |   cache_control:
40 |   last_modified: false
41 |   etag: false
42 |   vary_accept_encoding: false
43 |   redirect_default_route: false
44 |   redirect_default_code: 302
45 |   redirect_trailing_slash: true
46 |   ignore_files: [.DS_Store]
47 |   ignore_folders: [.git, .idea]
48 |   ignore_hidden: true
49 |   hide_empty_folders: false
50 |   url_taxonomy_filters: true
51 |   frontmatter:
52 |     process_twig: false
53 |     ignore_fields: ['form','forms']

La section Pages du fichier system/config/system.yaml est l'endroit où vous définissez un grand nombre des principaux paramètres liés au thème. Par exemple, c'est ici que vous définissez le thème utilisé pour afficher le site, l'ordre des pages, le traitement par défaut de twig et markdown, etc. C'est là que la plupart des décisions qui affectent la façon dont vos pages sont rendues sont prises.

Cache

1  | cache:
2  |   enabled: true
3  |   check:
4  |     method: file
5  |   driver: auto
6  |   prefix: 'g'
7  |   purge_at: '0 4 * * *'
8  |   clear_at: '0 3 * * *'
9  |   clear_job_type: 'standard'
10 |   clear_images_by_default: false
11 |   cli_compatibility: false
12 |   lifetime: 604800
13 |   gzip: false
14 |   allow_webserver_gzip: false
15 |   redis:
16 |     socket: false
17 |     password:
18 |     database:

La section Cache est l'endroit où vous pouvez configurer les paramètres de mise en cache du site. Vous pouvez activer, désactiver, choisir la méthode, etc.

Twig

1 | twig:
2 |   cache: true
3 |   debug: true
4 |   auto_reload: true
5 |   autoescape: false
6 |   0ndefined_functions: true
7 |   undefined_filters: true
8 |  umask_fix: false

La section Twig vous donne un ensemble rapide d'outils avec lesquels configurer Twig sur votre site pour le débogage, la mise en cache et l'optimisation.

Assets

1  | assets:
2  |    css_pipeline: false
3  |    css_pipeline_include_externals: true
4  |    css_pipeline_before_excludes: true
5  |    css_minify: true
6  |    css_minify_windows: false
7  |    css_rewrite: true
8  |    js_pipeline: false
9  |    js_pipeline_include_externals: true
10 |    js_pipeline_before_excludes: true
11 |    js_module_pipeline: false
12 |    s_module_pipeline_include_externals: true
13 |    js_module_pipeline_before_excludes: true
14 |    js_minify: true
15 |    enable_asset_timestamp: false
16 |    enable_asset_sri: false
17 |    collections:
18 |       jquery: system://assets/jquery/jquery-2.x.min.js

La section Assets permet de paramétrer les options liées aux Assets Manager (JS, CSS).

Errors

1 | errors:
2 |   display: 0
3 |   log: true

La section Errors détermine comment Grav gère l'affichage et la journalisation des erreurs.

Log

1 | log:
2 |   handler: file
3 |   syslog:
4 |     facility: local6

La section Log vous permet de configurer d'autres capacités de journalisation pour Grav.

Debugger

1 | debugger:
2 |   enabled: false
3 |   provider: clockwork
4 |   censored: false
5 |   shutdown:
6 |     close_connection: true

La section Debugger vous donne la possibilité d'activer le débogueur de Grav. Un outil utile lors du développement.

Images

1  | images:
2  |   default_image_quality: 85
3  |   cache_all: false
4  |   cache_perms: '0755'
5  |   debug: false
6  |   auto_fix_orientation: false
7  |   seofriendly: false
8  |   cls:
9  |     auto_sizes: false
10 |     aspect_ratio: false
11 |     retina_scale: 1
12 |   defaults:
13 |     loading: auto

La section Images vous permet de définir la qualité d'image par défaut pour laquelle les images sont rééchantillonnées, ainsi que de contrôler les fonctionnalités de mise en cache et de débogage des images.

Média

1 | media:
2 |   enable_media_timestamp: false
3 |   unsupported_inline_types: []
4 |   allowed_fallback_types: []
5 |   auto_metadata_exif: false

La section Média gère les options de configuration pour les paramètres liés à la gestion des fichiers multimédias. Cela inclut l'affichage de l'horodatage, la taille du téléchargement, etc.

Session

1  | session:
2  |   enabled: true
3  |   initialize: true
4  |   timeout: 1800
5  |   name: grav-site
6  |   uniqueness: path
7  |   secure: false
8  |   httponly: true
9  |   samesite: Lax
10 |   split: true
11 |   domain:
12 |   path:

Ces options déterminent les propriétés de session pour votre site.

GPM

1 | gpm:
2 |   releases: stable
3 |   proxy_url:
4 |   method: 'auto'
5 |   verify_peer: true
6 |   official_gpm_only: true

Les options de la section GPM contrôlent le GPM de Grav (Grav Package Manager). Par exemple, vous pouvez limiter GPM à l'utilisation de sources officielles et sélectionner la méthode utilisée par GPM pour récupérer les packages. Vous pouvez également choisir entre des versions stables et de test, ainsi que configurer une URL proxy.

Accounts

1 | accounts:
2 |   type: regular
3 |   storage: file

Les paramètres de compte vous permettent d'essayer les nouveaux utilisateurs Flex expérimentaux. Cela signifie essentiellement que les utilisateurs sont stockés sous forme d'objets Flex permettant plus de puissance et de performances.

Flex

1  | flex:
2  |   cache:
3  |     index:
4  |       enabled: true
5  |       lifetime: 60
6  |     object:
7  |       enabled: true
8  |       lifetime: 600
9  |     render:
10 |       enabled: true
11 |       lifetime: 600

Les paramètres de configuration du cache Flex Objects sont nouveaux dans Grav 1.7. Il s'agit de paramètres par défaut pour tous les types Flex, mais ils peuvent être remplacés pour chaque Flex Directory.

Strict Mode

1 | strict_mode:
2 |   yaml_compat: true
3 |   twig_compat: true
4 |   blueprint_compat: false

Le mode strict permet une migration plus propre vers les futures versions de Grav en passant aux nouvelles versions des processeurs YAML et Twig. Celles-ci peuvent ne pas être compatibles avec toutes les extensions tierces.

Configuration du site

En plus du fichier system.yaml, Grav fournit également un fichier de configuration site.yaml par défaut qui est utilisé pour définir certaines configurations spécifiques au front-end telles que le nom de l'auteur, l'adresse e-mail de l'auteur, ainsi que certains paramètres de taxonomie clés. Vous pouvez les remplacer de la même manière que vous le feriez pour system.yaml en fournissant votre propre fichier de configuration dans user/config/site.yaml. Vous pouvez également utiliser ce fichier pour définir des options de configuration arbitraires que vous souhaiterez peut-être référencer à partir de votre contenu ou de vos modèles.

Le fichier system/config/site.yaml par défaut fourni avec Grav ressemble à ceci :

1  | title : Grav                    # Nom du site.
2  | default_lang : en               # Langue par défaut pour le site (potentiellement 
   |                                 # utilisée par le thème).
3  |
4  | author:
5  |   name: John Appleseed          # Nom d'auteur par défaut.
6  |   email: 'john@example.com'     # E-mail de l'auteur par défaut.
7  |
8  | taxonomies : [category,tag]     # Liste arbitraire de types de taxonomie.
9  |
10 | metadata :
11 |   description: 'Mon site Grav'  # Description du site
12 |
13 | summary:
14 |   enabled : true                # activer ou désactiver le résumé de la page
15 |   format : short                # long = le délimiteur de résumé sera ignoré ; short = 
   |                                 # utiliser la première occurrence du délimiteur ou de la taille
16 |   size : 300                    # Longueur maximale du résumé (caractères)
17 |   délimiter : ===               # Le délimiteur récapitulatif
18 |
19 | redirects :
20 | # '/redirect-test': '/'         # Le test de redirection va à la page d'accueil
21 | # '/old/(.*)': '/new/$1'        # Redirigerait /old/ma-page vers /new/ma-page
22 |
23 | routes :
24 | # '/quelque chose/autre' : '/blog/sample-3'    # Alias ​​pour /blog/sample-3
25 | # '/new/(.*)': '/blog/$1'                      # Regex any /new/my-page URL
26 | to /blog/my-page Route
27 |
18 | blog:
29 |   route : '/blog'               # Valeur ajoutée personnalisée (accessible 
   | via site.blog.route)
30 |
31 | #menu :                         # Exemple de menu
32 | #     - text : Source
33 | #       icon : github
34 | #       url : https://github.com/getgrav/grav
34 | #     - icon : twitter
35 | #       url : http://twitter.com/getgrav

Décomposons les éléments de cet exemple de fichier :

Securité

Pour une sécurité accrue, il existe un fichier system/config/security.yaml qui définit des valeurs par défaut sensibles et est utilisé par le plugin Admin lors de l'enregistrement du contenu, ainsi que dans la nouvelle section Rapports des Outils.

La configuration par défaut ressemble à ceci :

1  | xss_whitelist: [admin.super]
2  | xss_enabled:
3  |     on_events: true
4  |     invalid_protocols: true
5  |     moz_binding: true
6  |     html_inline_styles: true
7  |     dangerous_tags: true
8  | xss_invalid_protocols:
9  |     - javascript
10 |     - livescript
11 |     - vbscript
12 |     - mocha
13 |     - feed
14 |     - data
15 | xss_dangerous_tags:
16 |     - applet
17 |      - meta
18 |     - xml
19 |     - blink
20 |     - link
21 |     - style
22 |     - script
23 |     - embed
24 |     - object
25 |     - iframe
26 |     - frame
27 |     - frameset
28 |     - ilayer
39 |     - layer
30 |     - bgsound
31 |     - title
32 |     - base
33 | uploads_dangerous_extensions:
34 |     - php
35 |     - html
36 |     - htm
37 |     - js
38 |    - exe
39 | sanitize_svg: true

Si vous souhaitez apporter des modifications à ces paramètres, vous devez copier ce fichier dans user/config/security.yaml et y apporter des modifications.

Autres paramètres et fichiers de configuration

La configuration de l'utilisateur est entièrement facultative. Vous pouvez remplacer autant ou peu de paramètres par défaut que vous le souhaitez. Cela s'applique à la fois au système, au site et à toutes les configurations de plug-in de votre site.

Vous n'êtes pas non plus limité aux fichiers user/config/system.yaml ou user/config/site.yaml comme décrit ci-dessus. Vous pouvez créer n'importe quel fichier de configuration .yaml arbitraire dans le dossier user/config que vous souhaitez et il sera automatiquement récupéré par Grav.

Par exemple, si le nouveau fichier de configuration est nommé user/config/data.yaml et qu'une variable yaml dans ce fichier est appelée count :

compte: 39

La variable serait accessible dans votre modèle Twig en utilisant la syntaxe suivante :

{{ config.data.count }}

Il serait également accessible via PHP depuis n'importe quel plugin avec le code :

$ count_var = Grav::instance()['config']->get('data.count');

Espaces de nom des variables de configuration

Les chemins d'accès aux fichiers de configuration seront utilisés comme espace de noms pour vos options de configuration.

Vous pouvez également placer toutes les options dans un seul fichier et utiliser des structures YAML pour spécifier la hiérarchie de vos options de configuration. Cet espacement de noms est construit à partir d'une combinaison du path + filename + option name.

Par exemple : Une option telle que author: Frank Smith dans le fichier plugins/myplugin.yaml pourrait être accessible via : plugins.myplugin.author. Cependant, vous pourriez également avoir un fichier plugins.yaml et dans ce fichier avoir un nom d'option appelé myplugin: author: Frank Smith et il serait toujours accessible par le même espace de noms plugins.myplugin.author.

Certains exemples de fichiers de configuration pourraient être structurés :

Configuration de plugins

La plupart des plugins sont livrés avec leur propre fichier de configuration YAML. Nous vous recommandons de copier ce fichier dans le répertoire user/config/plugins/ plutôt que de modifier les options de configuration directement dans le fichier situé dans le répertoire du plugin. Cela garantira qu'une mise à jour du plug-in n'écrasera pas vos paramètres et conservera toutes vos options configurables en un seul endroit pratique.

Si vous avez un plugin appelé user/plugins/myplugin qui a un fichier de configuration appelé user/plugins/myplugin/myplugin.yaml alors vous devez copier ce fichier dans user/config/plugins/myplugin.yaml et y modifier le fichier.

Le fichier YAML qui existe dans le répertoire principal du plugin agira comme une solution de secours. Tous les paramètres répertoriés ici et non dans la copie du dossier utilisateur seront récupérés et utilisés par Grav.

Configuration des thèmes

Les mêmes règles pour les thèmes s'appliquent que pour les plugins. Donc, si vous avez un thème appelé user/themes/mytheme qui a un fichier de configuration appelé user/themes/mytheme/mytheme.yaml, vous devez alors copier ce fichier dans user/config/themes/mytheme.yaml et y modifier le fichier.