Référence de la configuration

La configuration du bundle se trouve sous phil_content. Chaque clé est facultative. Une configuration vide construit un conteneur dans lequel aucune locale n'est servie, aucune racine n'est déclarée et aucune route ne sert de contenu.

Exemple complet

# config/packages/phil_content.yaml
phil_content:
    # The served locales, each with the locales tried after it, in order.
    # A fallback must itself be a served locale; a chain never repeats a locale.
    locales:
        fr_CA: [fr]          # a reader of fr_CA gets fr_CA, then fr
        fr: []               # a reader of fr gets fr only
        en: []

    # The content root classes; each names its row class.
    roots:
        - App\Content\News
        - App\Content\StaticPage

    # Service id of the entity manager the Doctrine adapters write through (the default).
    entity_manager: doctrine.orm.entity_manager

    # The Symfony routes that mount ContentController for each resource key.
    # The first route of a kind is the one its URLs are generated on, and takes a {slug} parameter.
    routes:
        news: news_show
        static_page: [page_show, privacy]

    # The Twig template of each template key.
    templates:
        news: content/news.html.twig

    # The template of a row whose template key is absent or not declared.
    default_template: content/page.html.twig

    # The trusted role whose holders write raw HTML; without it, raw HTML is shown and published as text.
    raw_html_role: ROLE_EDITOR

    # The kinds that have a single content: created once, found without an identifier.
    singles: [home_page, contact]

    # The kinds whose every publication stays readable, dated.
    archives: [now_page]

    # The index of phil/search-bundle the published contents are fed to (the default).
    search_index: content

    # The administration, linked from an EasyAdmin back office.
    admin:
        enabled: true
        role: ROLE_EDITOR
        layout: admin/content_layout.html.twig
        timezone: America/Toronto

Les clés

locales

Chaque clé est une locale servie ; sa valeur est la liste des locales essayées après elle, dans l'ordre. La locale demandée est toujours essayée en premier : fr_CA: [fr] déclare donc la chaîne fr_CA → fr.

Contraintes, vérifiées à la construction du conteneur (une InvalidLocaleDimension est levée par la validation de la configuration) :

• une locale a une seule graphie : deux ou trois lettres minuscules, suivies au besoin d'un trait de soulignement et de deux lettres majuscules (fr, fra, fr_CA). Les clés ne sont pas normalisées : fr-CA est donc refusée au lieu d'être lue comme fr_CA ;
• chaque locale de repli doit elle-même être une clé de locales : une chaîne ne se termine jamais sur une locale que l'application ne sert pas ;
• une chaîne ne nomme jamais deux fois une locale, y compris la sienne (fr: [fr] est refusée).

Rien ne déduit une locale de repli : retirer la région ou se replier sur une langue par défaut n'est jamais fait à votre place (dimensions.md). Une locale qui n'est pas une clé ici est refusée par chaque méthode d'écriture de ContentManager, répond 404 dans le contrôleur et fait répondre null aux fonctions Twig.

roots

Chaque classe doit être une sous-classe de Phil\ContentBundle\Domain\Content\AbstractContentRoot. La liste est validée par ContentRoots::fromClassNames(), que DoctrineBundle soit installé ou non. Une InvalidContentMapping est levée quand :

• une classe n'est pas une sous-classe de AbstractContentRoot ;
• deux racines nomment la même classe de ligne (dimensionContentClass()) ;
• la clé de ressource d'une racine (resourceKey()) n'est pas une lettre minuscule suivie d'au plus 63 lettres minuscules, chiffres ou traits de soulignement ;
• deux racines ont la même clé de ressource.

Une classe de ligne qu'aucune racine déclarée ne nomme est refusée quand Doctrine charge ses métadonnées.

entity_manager

Elle ne peut pas être vide. Une valeur qui n'est pas une chaîne est refusée par une InvalidConfigurationException quand le conteneur est construit avec DoctrineBundle. Sans DoctrineBundle, la clé ne sert pas.

Les mappages ORM des classes de base du bundle et de la table de routes sont ajoutés en tête de la configuration doctrine sous sa forme à un seul gestionnaire, que DoctrineBundle applique au gestionnaire d'entités nommé default. Une application qui fait pointer entity_manager vers un autre gestionnaire mappe elle-même les deux dossiers du bundle sur ce gestionnaire (src/Domain/Content sous le préfixe Phil\ContentBundle\Domain\Content, et src/Domain/Routing sous Phil\ContentBundle\Domain\Routing, tous deux de type attribute).

routes

Les routes sont des routes Symfony que déclare l'application, dont le contrôleur est Phil\ContentBundle\Infrastructure\Http\ContentController. Une chaîne seule est lue comme une liste d'un élément. La première route d'un genre est celle sur laquelle ses URL sont générées, et elle prend un paramètre {slug}. Les routes qui la suivent servent le même genre à leurs propres adresses, d'habitude avec le slug comme valeur par défaut de la route (routing.md).

Contraintes, vérifiées à la construction du conteneur :

• les clés ne sont pas normalisées (static_page reste static_page) ;
• un genre liste au moins une route, et aucun nom de route n'est vide ;
• une route sert un seul genre : une route listée sous deux clés, ou deux fois, est refusée par une InvalidArgumentException.

Les clés ne sont pas comparées aux racines déclarées : une clé qu'aucune racine ne déclare échoue à la première requête qui correspond à sa route.

templates

La clé de gabarit est le templateKey de la ligne (TemplateCapable). Les clés ne sont pas normalisées ; un nom de gabarit ne peut pas être vide.

default_template

Le gabarit d'une ligne sans clé de gabarit, d'une ligne dont la clé n'est pas sous templates, et d'une classe de ligne qui n'est pas TemplateCapable. Sans lui, une telle ligne fait lever une LogicException à TemplateResolver::resolve() : une clé que personne n'a déclarée est une erreur de la configuration, pas de la requête.

preview

Ce avec quoi les liens d'aperçu sont signés, et combien de secondes ils restent valides (sitemap-feeds-previews.md).

feed_limit

Le nombre d'entrées que contient un flux.

raw_html_role

Le rôle de confiance dont les titulaires écrivent du HTML brut. Le rôle est vérifié sur l'auteur de chaque révision d'un corps, jamais sur la personne qui le publie : le corps retient si le rédacteur qui a écrit sa source avait le rôle, et son HTML brut — écrit en Markdown, BBCode, MediaWiki, DokuWiki, Creole ou un format qu'apporte un module complémentaire, ou un bloc raw d'UJO — est alors publié comme bloc raw, gardé comme le permet le profil raw de phil/ujo, par n'importe quel rédacteur ; le HTML du brouillon, que montre son aperçu, en produit le rendu de la même façon. Le HTML brut d'un auteur sans le rôle s'affiche et se publie comme du texte, même par un publieur qui l'a. Une copie de travail garde le rôle du rédacteur qui l'a enregistrée, qui que ce soit qui l'applique (capabilities.md).

singles

Les genres qui n'ont qu'un seul contenu : la page d'accueil, les coordonnées, la page « à propos ». ContentManager::create() refuse une seconde racine d'un tel genre, ContentManager::single() trouve sa racine, et la fonction Twig content_single() la lit (content-manager.md, rendering.md). Une clé qui n'est pas une clé de ressource — une lettre minuscule, puis jusqu'à 63 lettres minuscules, chiffres ou _ — est refusée.

archives

Les genres dont chaque publication reste lisible à sa version, avec sa date : une page « maintenant », un journal des changements, une déclaration qui change avec le temps (publication.md). Tout autre genre garde son historique pour ses rédacteurs.

search_index

L'index auquel les contenus publiés sont fournis (search.md).

admin

L'administration des contenus (administration.md).

Services et conditions

Les services sont enregistrés sous leur nom de classe et sont privés, sauf les contrôleurs — ContentController, FeedController, PreviewController, ArchiveController et ContentAdminController —, étiquetés controller.service_arguments, et le workflow phil_content.publication_workflow, que PublicationWorkflowPass ajoute à workflow.registry. Injectez-les automatiquement par leur classe.

Avec DoctrineBundle, le bundle ajoute aussi en tête de la configuration doctrine les types DBAL phil_content_dimension_content_id, phil_content_locale, phil_content_route_id, phil_content_stage, phil_content_version et phil_content_working_copy_id, et les mappages PhilContentBundle, PhilContentBundleRouting et PhilContentBundleDraft.

Chaque classe est listée avec son espace de noms dans reference.md.