Ajout d'un collecteur de données personnalisé dans la barre de debug Symfony

Publié le 23/07/2020 • Actualisé le 23/07/2020

Dans cet article nous allons voir comment ajouter un collecteur de données personnalisé dans la barre de debug Symfony. La barre de debug aussi appelée profileur, est l'un des composants les plus utiles car elle est d'une grande aide pendant le développement. Nous allons voir un cas concret nous aidant à améliorer le SEO d'un site en affichant des métas informations à propos de la page courante. C'est parti ! 😎

» Publié dans "Une semaine Symfonique 708" (du 20 au 26 juillet 2020).

Prérequis

Je présumerai que vous avez les compétences de base concernant Symfony et que vous savez comment créer une application et y accéder avec l'environnement de debug activé.

Configuration

Rien de particulier ici, mais pour avoir le profileur, vous devez avoir la dépendance de développement composer symfony/profiler-pack installée.

• PHP 8.3
• Symfony 6.4.6
• "symfony/profiler-pack": "*" (composer)

Introduction

Le SEO (🇬🇧 Search Engine Optimization) est crucial de nos jours puisqu'il détermine la quantité de visiteurs arrivant sur un site par les moteurs de recherche comme Google. Être sur la première page de résultats pour des mots-clés donnés est quelque chose qui peut rendre une entreprise prospère ou pas. J'ai récemment été audité par les experts SEO Pragm et ils m'ont donné plusieurs conseils. L'un d'entre eux est de surveiller le contenu et la longueur du titre (le tag HTML <title>) et de la description de la page (le tag HTML <meta> ayant la valeur "description" pour l'attribut name).

But

Le but va être de récupérer le contenu du titre et de la description pour vérifier qu'ils respectent certaines règles :

• Le titre doit faire entre 30 et 65 caractères.
• La description doit faire entre 120 et 155 caractères.

Bien sûr, ces deux informations doivent être présentes. Une page sans titre ni description est le pire cas. Donc, le nouveau panneau que nous allons construire va nous indiquer la valeur du titre et de la description ainsi que leurs longueurs respectives.

Le layout

Tout d'abord, voyons comment est affiché le titre et la description dans le layout (🇫🇷 template de base de l'application) :

    <title>{% block title %}{{ 'head_meta_title'|trans({'%app_name%': app_name})|seo_title }}{% endblock title %}</title>

    <meta name="description" content="{% block description %}{{ 'head_meta_description'|trans({'%app_name%': app_name})|seo_description|raw }}{% endblock %}" />

Comme vous pouvez le voir, dans les deux cas, on définit un bloc, puis, on récupère une traduction, enfin; on applique un filtre Twig. Nous verrons ces filtres un peu plus tard. Donc, pour chaque page, on redéfinit le bloc en utilisant un contexte de traduction différent pour avoir les bonnes valeurs pour la page courante. Utiliser des blocs est très pratique puisque ça nous permet de les réutiliser à d'autres endroits pour d'autres tags métas, comme ici pour Open Graph et Twitter :

    <meta property="og:title" content="{{ block('title') }}" />
    <meta property="og:description" content="{{ block('description') }}" />

    <meta name="twitter:title" content="{{ block('title') }}" />
    <meta name="twitter:description" content="{{ block('description') }}" />

Le collecteur de données

La première étape est de créer un collecteur de données personnalisé. Si on utilise l'auto-wiring on a rien à faire et la classe sera automatiquement détectée par Symfony. Quelques explications après le code :

<?php

declare(strict_types=1);

// src/DataCollector/SeoCollector.php

namespace App\DataCollector;

use App\Twig\Extension\SeoExtension;
use Symfony\Component\DomCrawler\Crawler;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\DataCollector\DataCollector;

use function Symfony\Component\String\u;

final class SeoCollector extends DataCollector
{
    private const MAX_PANEL_WIDTH = 50;
    private const CLASS_ERROR = 'red';
    private const CLASS_WARNING = 'yellow';
    private const CLASS_OK = 'green';

    public function collect(Request $request, Response $response, ?\Throwable $exception = null): void
    {
        $crawler = new Crawler((string) $response->getContent());

        // Title ———————————————————————————————————————————————————————————————
        $titleTag = $crawler->filter('title');
        if ($titleTag->count() > 0) {
            $titleStr = u($titleTag->text());
            $titleSize = $titleStr->length();
            $titleInfo = [
                'value' => $titleStr->wordwrap(self::MAX_PANEL_WIDTH)->toString(),
                'size' => (string) $titleSize,
                'status' => $this->getTitleClass($titleSize),
            ];
            $this->data['title'] = $titleInfo;
        }

        // Description —————————————————————————————————————————————————————————
        $meta = $crawler->filterXPath('//meta[@name="description"]');
        if ($meta->count() > 0) {
            $descriptionStr = u((string) $meta->attr('content'));
            $descriptionLength = $descriptionStr->length();
            $descriptionInfo = [
                'value' => $descriptionStr->wordwrap(self::MAX_PANEL_WIDTH)->toString(),
                'size' => (string) $descriptionLength,
                'status' => $this->getDescriptionClass($descriptionLength),
            ];
            $this->data['description'] = $descriptionInfo;
        }
    }

    private function getTitleClass(int $size): string
    {
        if ($size === 0) {
            return self::CLASS_ERROR;
        }

        return $size >= SeoExtension::MIN_TITLE_LENGTH && $size <= SeoExtension::MAX_TITLE_LENGTH ? self::CLASS_OK : self::CLASS_WARNING;
    }

    private function getDescriptionClass(int $size): string
    {
        if ($size === 0) {
            return self::CLASS_ERROR;
        }

        return $size >= SeoExtension::MIN_DESCRITION_LENGTH && $size <= SeoExtension::MAX_DESCRITION_LENGTH ? self::CLASS_OK : self::CLASS_WARNING;
    }

    /**
     * @return array<string,string>
     */
    public function getTitle(): array
    {
        return $this->data['title'] ?? [];
    }

    /**
     * @return array<string,string>
     */
    public function getDescription(): array
    {
        return $this->data['description'] ?? [];
    }

    public function reset(): void
    {
        $this->data = [];
    }

    public function getName(): string
    {
        return self::class;
    }
}

La principale fonction de notre nouveau collecteur est collect(). Elle est responsable de rassembler les nouvelles données. Pour ce faire, on ajoute des clés / valeurs à l'attribut data.

Dans notre cas, nous ajoutons deux nouvelles clés : title et description. Pour chacune, nous avons trois informations :

• value : La valeur courante de la chaîne
• size : Sa longueur
• status : Le status de la longueur, on a trois cas; OK, avertissement ou erreur

Pour ces deux informations on applique le même procédé. D'abord, on récupère la chaîne à analyser à partir du contenu de la réponse grâce au crawler Symfony. Si elle existe, on calcule les différentes informations que nous avons à afficher dans le panneau de debug; sinon, la clé reste vide. Comme vous pouvez le voir, j'utilise massivement le nouveau composant string pour toutes les manipulations impliquant des chaînes de caractères; c'est tellement plus pratique que d'utiliser les fonctions PHP standards.

OK, maintenant que nous avons récupéré les nouvelles données, voyons comment afficher ces informations dans la barre de debug.

Le panneau de debug

Le panneau de debug est un template Twig qui étend le template Symfony WebProfiler/Profiler/layout.html.twig. Voici son contenu :

{% extends '@WebProfiler/Profiler/layout.html.twig' %}

{# templates/data_collector/seo_collector.html.twig #}

{% block toolbar %}
    {% set icon %}
        <span class="sf-toolbar-value"><i class="fad fa-vector-square"></i> SEO</span>
    {% endset %}

    {% set text %}
        <div class="sf-toolbar-info-piece">
            <b>Title length ({{ constant('App\\Twig\\Extension\\SeoExtension::MIN_TITLE_LENGTH') }} > {{ constant('App\\Twig\\Extension\\SeoExtension::MAX_TITLE_LENGTH') }})</b>
            {% set status = collector.title['status'] is defined ? collector.title['status'] : 'red' %}
            <span class="sf-toolbar-status sf-toolbar-status-{{ status }}">
                {% if collector.title is not empty %}
                    {{ collector.title['size'] }}
                {% else %}
                    <span>Title is empty.</span>
                {% endif %}
            </span>
        </div>

        {% if collector.title is not empty %}
            <div class="sf-toolbar-info-piece">
                <b>Title</b>
                <span>{{ collector.title['value']|nl2br|raw }}</span>
            </div>
        {% endif %}

        <div class="sf-toolbar-info-piece">
            <b>Description length ({{ constant('App\\Twig\\Extension\\SeoExtension::MIN_DESCRITION_LENGTH') }} > {{ constant('App\\Twig\\Extension\\SeoExtension::MAX_DESCRITION_LENGTH') }})</b>
            {% set status = collector.description['status'] is defined ? collector.description['status'] : 'red' %}
            <span class="sf-toolbar-status sf-toolbar-status-{{ status }}">
                {% if collector.description is not empty %}
                    {{ collector.description['size'] }}
                {% else %}
                    <span>Description is empty.</span>
                {% endif %}
            </span>
        </div>

        {% if collector.description is not empty %}
            <div class="sf-toolbar-info-piece">
                <b>Description</b>
                <span>{{ collector.description['value']|nl2br|raw }}</span>
            </div>
        {% endif %}
    {% endset %}

    {{ include('@WebProfiler/Profiler/toolbar_item.html.twig', { link: false }) }}
{% endblock %}

On doit associer ce template au tag data_collector. Pour ce faire, on ajoute l'entrée suivante dans le fichier services.yml. Veuillez noter qu'ici que j'utilise la FQCN de la classe du collecteur comme identifiant (id:), ça permet d'utiliser la constante self::class dans la fonction getName() et évite à la configuration de contenir des chaînes arbitraires comme identifiant.

    # add more service definitions when explicit configuration is needed
    # please note that last definitions always *replace* previous ones

    App\Log\Processor\EnvProcessor:
        tags:

Quelques explications à propos du template; on redéfinit le bloc toolbar dans lequel on définit deux variables : icon et text. text est l'icône qui est affichée dans la barre de debug et qu'il faut survoler avec la souris afin de voir le détail du panneau. text représente le contenu du panneau. Ces deux variables sont utilisées dans le template WebProfiler/Profiler/toolbar_item.html.twig qui est inclus tout en bas. On peut identifier dans le contenu de la variable text quatre éléments distincts :

• La longueur du titre avec la taille recommandée
• Le titre
• La longueur de la description avec la taille recommandée
• La description.

Pour les deux éléments correspondant aux longueurs, on remarque que l'on assigne un statut (sf-toolbar-status-{{ status }}). Il permet de spécifier la couleur de fond de la taille (il a été préparé dans le collecteur de données), rouge indique un texte manquant, jaune indique que la taille est soit trop courte soit trop longue. Finalement, vert indique que la longueur correspond bien aux recommandations. Voici à quoi ressemble la barre de debug avec la nouvelle entrée :

Une fois déplié, nous voyons le détail du panneau :

La couleur de fond de l'icône correspond au "pire" status des entrées que contient le panneau relatif. Si vous avez au moins une entrée de type erreur ce sera rouge. Si vous avez au moins une entrée de type avertissement ce sera jaune, sinon ce sera vert. Symfony gère cela de manière automatique. Veuillez noter que comme nous avons passé le paramètre { link: false } au template toolbar_item.html.twig, nous n'avons pas ce nouveau panneau quand on accède au profileur en pleine page (https://127.0.0.1:8000/_profiler/b8fbf5).

<div class="sf-toolbar-block sf-toolbar-block-{{ name }} sf-toolbar-status-{{ status|default('normal') }} {{ additional_classes|default('') }}" {{ block_attrs|default('')|raw }}>
    {% if link is not defined or link %}<a href="{{ url('_profiler', { token: token, panel: name }) }}">{% endif %}
        <div class="sf-toolbar-icon">{{ icon|default('') }}</div>
    {% if link|default(false) %}</a>{% endif %}
        <div class="sf-toolbar-info">{{ text|default('') }}</div>
</div>

{% extends '@WebProfiler/Profiler/base.html.twig' %}

{% block body %}
    <div class="container">
        {{ include('@WebProfiler/Profiler/header.html.twig', {profile_type: profile_type}, with_context = false) }}

        <div id="summary">
        {% block summary %}
            {% if profile is defined %}
                {% set request_collector = profile.collectors.request|default(false) %}

                {{ include('@WebProfiler/Profiler/_%s_summary.html.twig'|format(profile_type), {
                    profile: profile,
                    command_collector: profile.collectors.command|default(false) ,
                    request_collector: request_collector,
                    request: request,
                    token: token
                }, with_context=false) }}
            {% endif %}
        {% endblock %}
    </div>

        <div id="content">
            <div id="main">
                <div id="sidebar">
                    {% block sidebar %}
                        <div id="sidebar-contents">
                            <div id="sidebar-shortcuts">
                                {% block sidebar_shortcuts_links %}
                                    <div class="shortcuts">
                                        <a class="btn btn-link" href="{{ path('_profiler_search', { limit: 10, type: profile_type }) }}">Last 10</a>
                                        <a class="btn btn-link" href="{{ path('_profiler', { token: 'latest', type: profile_type }|merge(request.query.all)) }}">Latest</a>

                                        <a class="sf-toggle btn btn-link" data-toggle-selector="#sidebar-search" {% if tokens is defined or about is defined %}data-toggle-initial="display"{% endif %}>
                                            {{ source('@WebProfiler/Icon/search.svg') }} <span class="hidden-small">Search</span>
                                        </a>
                                    </div>
                                {% endblock sidebar_shortcuts_links %}

                                {{ render(controller('web_profiler.controller.profiler::searchBarAction', query={type: profile_type }|merge(request.query.all))) }}
                            </div>

                            {% if templates is defined %}
                                <ul id="menu-profiler">
                                    {% if 'request' is same as(profile_type) %}
                                        {% set excludes = ['command'] %}
                                    {% elseif 'command' is same as(profile_type) %}
                                        {% set excludes = ['request', 'router'] %}
                                    {% endif %}

                                    {% for name, template in templates|filter((t, n) => n not in excludes) %}
                                        {% set menu -%}
                                            {%- if block('menu', template) is defined -%}
                                                {% with { collector: profile.getcollector(name), profiler_markup_version: profiler_markup_version } %}
                                                    {{- block('menu', template) -}}
                                                {% endwith %}
                                            {%- endif -%}
                                        {%- endset %}
                                        {% if menu is not empty %}
                                            <li class="{{ name }} {{ name == panel ? 'selected' }}">
                                                <a href="{{ path('_profiler', { token: token, panel: name, type: profile_type }) }}">{{ menu|raw }}</a>
                                            </li>
                                        {% endif %}
                                    {% endfor %}
                                </ul>
                            {% endif %}
                        </div>

                        {{ include('@WebProfiler/Profiler/settings.html.twig') }}
                    {% endblock sidebar %}
                </div>

                <div id="collector-wrapper">
                    <div id="collector-content">
                        {{ include('@WebProfiler/Profiler/base_js.html.twig') }}
                        {% block panel '' %}
                    </div>
                </div>
            </div>
        </div>
    </div>
{% endblock %}

L'extension Twig SEO

Quand nous avons regardé le layout, nous avons vu que deux filtres Twig étaient utilisés. Ils permettent de s'assurer l'application de certaines règles. Ils coupent les chaînes si elles sont trop grandes. Pour le titre, il est vérifié si la chaîne de stratégie de marque (branding) peut être ajoutée sans dépasser la taille autorisée (on ajoute au titre " | Strangebuzz"). Voici le code:

<?php

declare(strict_types=1);

// src/Twig/Extension/SeoExtension.php

namespace App\Twig\Extension;

use Symfony\Component\String\AbstractString;
use Twig\Extension\AbstractExtension;
use Twig\TwigFilter;

use function Symfony\Component\String\u;

/**
 * SEO related Twig helpers.
 */
final class SeoExtension extends AbstractExtension
{
    public const MIN_TITLE_LENGTH = 30;
    public const MAX_TITLE_LENGTH = 65;

    public const MIN_DESCRITION_LENGTH = 120;
    public const MAX_DESCRITION_LENGTH = 155;

    private const BRANDING = ' | Strangebuzz';

    public function getFilters(): array
    {
        return [
            new TwigFilter('seo_title', [$this, 'processTitle']),
            new TwigFilter('seo_description', [$this, 'processDescription']),
        ];
    }

    private function prepareStr(string $str): AbstractString
    {
        return u(strip_tags($str))->trim();
    }

    public function processTitle(string $title): string
    {
        $str = $this->prepareStr($title);
        $brandingStr = u(self::BRANDING);
        $length = $str->length();

        // Nominal case
        if ($length >= self::MIN_TITLE_LENGTH && $length <= self::MAX_TITLE_LENGTH) {
            // Is there enough place for the branding?
            if (($length + $brandingStr->length()) <= self::MAX_TITLE_LENGTH) {
                $str = $str->ensureEnd($brandingStr->toString());
            }

            return $str->toString();
        }

        // Title too short, we add the branding
        if ($length < self::MIN_TITLE_LENGTH) {
            $str = $str->ensureEnd($brandingStr->toString());
        }

        // Title too long, we cup
        if ($length > self::MAX_TITLE_LENGTH) {
            $str = $str->truncate(self::MAX_TITLE_LENGTH);
        }

        return $str->toString();
    }

    public function processDescription(string $description): string
    {
        $str = $this->prepareStr($description);
        $length = $str->length();

        if ($length >= self::MIN_DESCRITION_LENGTH && $length <= self::MAX_DESCRITION_LENGTH) {
            return $str->toString();
        }

        // Description too long, we cut
        if ($length > self::MAX_DESCRITION_LENGTH) {
            $str = $str->truncate(self::MAX_DESCRITION_LENGTH);
        }

        return $str->toString();
    }
}

J'utilise ici également le composant string pour toutes les manipulations de chaîne à part pour la fonction strip_tags. J'ai ajouté cette extension assez récemment mais si j'avais à l'utiliser sur un nouveau projet, je lancerais une exception si le titre ou la description sont manquants ou incorrects. Ça contraindrait le développeur à ajouter ces textes. L'ajout de ces informations ferait donc parti du contrat quand on ajouterait de nouvelles pages publiques.

Conclusion

L'ajout d'un panneau de debug personnalisé n'est pas très difficile puisque le profileur a été conçu pour être étendu. Nous avons vu un cas concret ou il peut être utile et nous faciliter la vie en tant que développeur (🇬🇧 Developer Experience). J'espère que ça vous donnera des idées pour vos projets, n'hésitez pas à m'en faire part ! 😉

Et voilà ! J'espère que vous avez aimé. Découvrez d'autres informations en rapport à cet article avec les liens ci-dessous. Comme toujours, retours, likes et retweets sont les bienvenus. (voir la boîte ci-dessous) À tantôt ! COil. 😊

  Lire la doc

  Travaillez avec moi !

par COil

 Symfony  Debug  profiler  Expérience Développeur (DX)  dev