Aller au contenu

Sources de découverte logique

Blockstudio découvre normalement les fichiers dans les répertoires physiques des thèmes. Les outils d’exécution peuvent remplacer ces répertoires par un inventaire logique. Cette approche est utile pour les aperçus, les superpositions, les thèmes générés, les montages distants et d’autres environnements où les fichiers associés ne partagent pas de racine physique.

Blockstudio continue d’analyser et d’enregistrer les blocs, les pages, les collections, les compositions, les champs, les modèles et les parties de modèle. La source détermine uniquement quels fichiers logiques sont visibles et où chaque fichier visible peut être lu.

Sources d’inventaire

Utilisez le filtre blockstudio/discovery/sources pour remplacer les objets Filesystem_Discovery_Source par défaut :

PHP
use Blockstudio\Inventory_Discovery_Source;

add_filter(
    'blockstudio/discovery/sources',
    function (array $sources, string $context, array $paths): array {
        if ('blocks' !== $context) {
            return $sources;
        }

        return [
            new Inventory_Discovery_Source(
                'preview:feature-card',
                '/runtime-preview/feature-card/blockstudio',
                [
                    'card/block.json' => [
                        'path' => '/theme/blockstudio/card/block.json',
                        'provenance' => [
                            'layer' => 'parent',
                            'inherited' => true,
                        ],
                    ],
                    'card/index.php' => [
                        'path' => '/runtime-preview/feature-card/blockstudio/card/index.php',
                        'provenance' => [
                            'layer' => 'preview',
                        ],
                    ],
                ],
                'parent-and-preview-fingerprint',
                ['/theme/blockstudio', '/runtime-preview/feature-card/blockstudio']
            ),
        ];
    },
    10,
    3
);

Les contextes disponibles sont :

  • blocks
  • fields
  • pages
  • patterns
  • site-templates
  • site-template-parts

Un inventaire est l’arborescence finale visible. Composez les couches avant de la renvoyer :

  • Utilisez une entrée pour chaque chemin logique visible.
  • Laissez la couche sélectionnée fournir le chemin physique.
  • Omettez les chemins logiques supprimés.
  • Renvoyez les entrées dans n’importe quel ordre. Blockstudio les trie par chemin logique.
  • Incluez les répertoires logiques vides dans le sixième argument facultatif du constructeur lorsque leur visibilité compte.

Inventory_Discovery_Source est pratique pour les inventaires stockés dans des tableaux. Les intégrations peuvent implémenter l’interface Discovery_Source lorsque les entrées sont résolues à la demande ou proviennent d’un autre système de stockage.

Résolution des éléments frères

Les éléments logiques frères peuvent être résolus dans différents répertoires physiques. Un block.json parent peut utiliser un index.php de superposition, et une page de superposition peut hériter du pages.json, du chargeur ou de la mise en page de son parent. Blockstudio résout ces relations par chemin logique avant de lire les fichiers physiques sélectionnés.

Les chemins du chargeur situés hors d’une collection conservent la limite de sécurité existante de blockstudio/pages/allow_external_loader_path.

Identité et invalidation

Chaque source fournit :

  • Un identifiant de source stable pour l’environnement d’exécution sélectionné.
  • Une empreinte qui change avec l’inventaire visible.
  • Les entrées physiques à surveiller pour le rechargement à chaud et la validation du cache.
  • La provenance et les métadonnées de chaque entrée.

Blockstudio inclut les identifiants et empreintes de source dans les identités des caches d’exécution, de manifeste de page, de modèle de l’éditeur de site, de Canevas et Tailwind.

Utilisez blockstudio/cache/context lorsque la même sélection de sources peut être rendue dans plusieurs variantes d’exécution :

PHP
add_filter(
    'blockstudio/cache/context',
    fn ($context, string $scope) => [
        'preview' => 'feature-card',
        'site' => get_current_blog_id(),
    ],
    10,
    2
);

La valeur de contexte doit être sérialisable et stable pour des requêtes équivalentes. Tailwind conserve le dernier CSS valide dans un espace de noms propre au contexte, afin qu’un aperçu ne reçoive pas le CSS de secours d’un autre aperçu.

Ressources générées

Marquez les entrées héritées ou en lecture seule avec inherited: true, readOnly: true ou writable: false dans leur provenance ou leurs métadonnées. Blockstudio écrit alors les ressources compilées dans une portée generated propre au contexte, sous la racine de cache Blockstudio configurée, plutôt qu’à côté de la source parente. Les ressources générées, la sortie Tailwind, les documents de rendu et les pré-rendus statiques partagent ainsi la même limite d’écriture de l’hôte.

Deux filtres permettent de personnaliser le routage d’exécution :

PHP
add_filter(
    'blockstudio/generated_output/path',
    function (string $path, string $source, string $scope, array $metadata) {
        return $path;
    },
    10,
    4
);

add_filter(
    'blockstudio/files/url',
    function (string $url, string $path, string $scope) {
        return $url;
    },
    10,
    3
);

Utilisez le filtre URL lorsque les fichiers sélectionnés se trouvent hors de wp-content ou sont servis par un point de terminaison d’exécution.