fina / structured-content
Generic, reusable block-based structured content system for Laravel applications.
Requires
- php: ^8.1
- illuminate/database: ^10.0|^11.0|^12.0|^13.0
- illuminate/routing: ^10.0|^11.0|^12.0|^13.0
- illuminate/support: ^10.0|^11.0|^12.0|^13.0
Requires (Dev)
- orchestra/testbench: ^8.0|^9.0|^10.0|^11.0
- pestphp/pest: ^2.0|^3.0
- pestphp/pest-plugin-laravel: ^2.0|^3.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Infrastructure générique pour du contenu structuré en blocs dans une application Laravel — un équivalent simplifié de Strapi, distribué sous forme de package Composer privé et réutilisable entre plusieurs projets.
Le package fournit :
- le stockage (table
block+ modèleBlock, association polymorphique), - le CRUD générique + réordonnancement (
BlockController), - l'autorisation (Gate
manageBlocks, fail-closed par défaut), - les points d'extension (
BlockTypeRegistry,BlocksRegistrar).
Il ne contient aucune logique métier : aucun type de bloc concret propre à un projet, aucun rôle/permission, aucun instanceof sur un modèle applicatif. Tout ce qui est spécifique à un projet est enregistré par ce projet lui-même, jamais par le package.
Installation
composer require fina/structured-content
Le ServiceProvider est auto-découvert via la clé extra.laravel.providers du composer.json du package — rien à ajouter manuellement dans bootstrap/providers.php pour le package lui-même.
Publier la configuration
php artisan vendor:publish --tag=blocks-config
Publie config/blocks.php, qui expose notamment route_prefix (défaut api, configurable aussi via BLOCKS_ROUTE_PREFIX).
Publier et exécuter la migration
php artisan vendor:publish --tag=blocks-migrations php artisan migrate
Crée la table block (blockableId/blockableType polymorphiques, type, data JSON, position, createdAt/updatedAt).
Conventions de nommage BDD
- noms de table au singulier et en camelCase (
block, pasblocksniBlocks), - noms de colonne en camelCase (
blockableId,blockableType,createdAt,updatedAt), - le
_est réservé aux tables d'association (pivots) — le package n'en a aucune, la relation polymorphique tenant sur deux colonnes de la tableblockelle-même.
Ces conventions ne concernent que le schéma (tables/colonnes) : les routes HTTP (/structuredContents/{blockableType}/{blockableId}/blocks) et les clés de configuration (route_prefix) restent en anglais/snake_case ou pluriel là où c'est l'usage REST habituel, sans lien avec le nommage BDD.
Routes exposées
Toutes préfixées par config('blocks.route_prefix') :
| Méthode | URI | Action |
|---|---|---|
| GET | /structuredContents/{blockableType}/{blockableId}/blocks |
index |
| POST | /structuredContents/{blockableType}/{blockableId}/blocks |
store |
| POST | /structuredContents/blocks/{block}/up |
up |
| POST | /structuredContents/blocks/{block}/down |
down |
| POST | /structuredContents/blocks/{block} |
update |
| DELETE | /structuredContents/blocks/{block} |
destroy |
{blockableType} est une clé arbitraire (ex. articles), résolue via BlocksRegistrar — jamais un nom de classe.
API segmentée par guard (/admin, /healthFacility, ...)
Le groupe de routes ci-dessus est enregistré automatiquement par BlocksServiceProvider, sans middleware d'authentification — adapté à une API avec un seul guard. Si ton API est découpée en plusieurs segments fonctionnels ayant chacun leur propre guard, ce groupe unique et non protégé ne convient plus : il faut monter les routes une fois par segment, chacune derrière son propre middleware auth:<guard>.
Pour ça, désactive l'auto-registration et monte les routes toi-même via Fina\StructuredContent\StructuredContent::routes() (même pattern que Sanctum::routes()) :
// config/blocks.php ou .env 'register_routes' => false, // ou BLOCKS_REGISTER_ROUTES=false
// routes/admin.php use Fina\StructuredContent\StructuredContent; use Illuminate\Support\Facades\Route; Route::prefix('admin')->middleware('auth:admin')->group(function () { StructuredContent::routes(); }); // routes/healthFacility.php Route::prefix('healthFacility')->middleware('auth:healthFacility')->group(function () { StructuredContent::routes(); });
StructuredContent::routes() applique lui-même le middleware SubstituteBindings nécessaire au model binding implicite (Block $block) — pas besoin de le rajouter. Le Gate manageBlocks n'a rien à changer : Auth::user()/Gate::denies() résolvent déjà le bon guard, puisque le middleware auth:<guard> appelle Auth::shouldUse($guard) avant d'atteindre le contrôleur. Il suffit donc de faire varier la logique du Gate selon la classe de $user (Admin vs HealthFacilityUser) :
Gate::define('manageBlocks', function (?Authenticatable $user, $blockable) { return match (true) { $user instanceof \App\Models\Admin => true, $user instanceof \App\Models\HealthFacilityUser => $user->facility->owns($blockable), default => false, }; });
Upload de fichiers pour le bloc image — pas de media library
Contrairement à Strapi, ce package ne fournit pas de media library partagée : chaque bloc qui a besoin d'un fichier gère le sien directement, en une seule requête, sans endpoint d'upload séparé ni ressource réutilisable entre blocs.
# Création : le fichier est envoyé dans la même requête que le bloc (multipart/form-data) POST /api/structuredContents/articles/1/blocks Content-Type: multipart/form-data type: image file: <binaire> alt: Description de l'image # → { "id": 12, "type": "image", "position": 1, "url": "https://.../storage/blocks/images/xxxx.jpg", "alt": "Description de l'image" } # Mise à jour sans remplacer le fichier : omettre "file" conserve l'existant POST /api/structuredContents/blocks/12 { "alt": "Nouvelle description" } # Mise à jour en remplaçant le fichier : l'ancien est supprimé du disque POST /api/structuredContents/blocks/12 Content-Type: multipart/form-data file: <nouveau binaire>
Le fichier est supprimé du disque automatiquement quand le bloc est supprimé (DELETE /api/structuredContents/blocks/12), ou remplacé (ancien fichier effacé) si un nouveau fichier est envoyé lors d'un update.
Le disque de stockage (config('blocks.media_disk'), défaut public) et la taille max en Ko (config('blocks.media_max_size'), défaut 10240) sont configurables via BLOCKS_MEDIA_DISK/BLOCKS_MEDIA_MAX_SIZE.
Ce comportement repose sur trois hooks optionnels du contrat BlockType (no-op par défaut dans AbstractBlockType), que tout type de bloc métier possédant sa propre ressource externe peut surcharger de la même façon :
rulesForUpdate()— règles de validation à l'update, différentes derules()(ex : fichier optionnel plutôt que requis) ;prepareForStorage(array $validated, Request $request, array $previousData)— transforme le payload validé juste avant persistance (déplace le fichier uploadé vers le disque, gère le remplacement) ;afterDelete(array $data)— nettoyage (suppression du fichier) juste avant la suppression du bloc.
Ce que le projet consommateur doit fournir
Le package ne présume rien sur les modèles ou les rôles de l'application hôte. Trois choses sont à la charge du projet, typiquement dans un provider applicatif (voir examples/BlocksServiceProvider.php) :
- enregistrer ses blockables,
- enregistrer ses types de blocs métier,
- surcharger le Gate
manageBlocksavec la vraie logique d'autorisation.
⚠️ Ordre de déclaration des providers
Ce provider applicatif doit être déclaré après Fina\StructuredContent\BlocksServiceProvider dans bootstrap/providers.php :
return [ Fina\StructuredContent\BlocksServiceProvider::class, // ajouté par l'auto-discovery Composer App\Providers\BlocksServiceProvider::class, // le vôtre, listé explicitement, APRÈS ];
L'auto-discovery Composer charge le provider du package avant tout provider listé explicitement. Comme le package définit un Gate fermé et n'enregistre que ses types génériques dans son propre boot(), le provider applicatif doit s'exécuter ensuite pour que sa surcharge du Gate et ses enregistrements dans les registres prennent effet.
1. Enregistrer un blockable
use Fina\StructuredContent\BlocksRegistrar; public function boot(BlocksRegistrar $blockables): void { $blockables->registerBlockable('articles', \App\Models\Article::class); }
Le modèle blockable n'a besoin d'aucune interface particulière côté package.
Relation blocks (optionnel)
Pour lire les blocs directement depuis le modèle, sans passer par l'API, ajouter le trait HasBlocks :
use Fina\StructuredContent\Concerns\HasBlocks; class Article extends Model { use HasBlocks; } Article::with('blocks')->get(); // relation morphMany triée par position, eager-loadable $article->blocks; // Collection de Block (->data brut accessible) $article->blocks->toArray(); // sérialisé comme l'API (toArray() de chaque type de bloc) return $article->load('blocks'); // idem dans le JSON de la réponse
La sérialisation d'un Block (toArray()/JSON) reprend le format de l'API ; createdAt/updatedAt n'y figurent pas.
Le trait supprime aussi les blocs du modèle (et appelle afterDelete() de chaque type, ex. suppression des fichiers) quand il est supprimé — définitivement, un soft delete les conserve. Il est compatible avec une morph map : blockableType est écrit via getMorphClass().
Pour lister les blockables enregistrés :
php artisan blocks:blockables
Affiche la clé et la classe de chaque blockable whitelisté dans BlocksRegistrar — pratique pour vérifier quels {blockableType} sont réellement accessibles sans relire tous les boot() des providers.
2. Enregistrer un type de bloc métier
Étendre Fina\StructuredContent\AbstractBlockType (qui implémente authorizeSave() en retournant true par défaut) :
use Fina\StructuredContent\AbstractBlockType; class CalloutBlockType extends AbstractBlockType { public static function key(): string { return 'callout'; } public function rules(): array { return [ 'title' => ['required', 'string', 'max:120'], 'body' => ['required', 'string'], 'style' => ['required', 'in:info,warning,danger'], ]; } public function toArray(array $data): array { return [ 'title' => $data['title'], 'body' => $data['body'], 'style' => $data['style'], ]; } }
Puis l'enregistrer :
use Fina\StructuredContent\BlockTypeRegistry; public function boot(BlockTypeRegistry $blockTypes): void { $blockTypes->register(CalloutBlockType::class); }
Le package enregistre déjà trois types génériques par défaut :
| Clé | Classe | Champs |
|---|---|---|
text |
Fina\StructuredContent\BlockTypes\TextBlockType |
content (string, requis) |
image |
Fina\StructuredContent\BlockTypes\ImageBlockType |
file (upload, requis à la création, optionnel à l'update), alt (string) — url est résolue et ajoutée en lecture |
heading |
Fina\StructuredContent\BlockTypes\HeadingBlockType |
text (string, requis), level (1-6, défaut 2) |
TextBlockType sert d'exemple concret d'implémentation de AbstractBlockType. HeadingBlockType (le bloc "Titre") porte un niveau sémantique H1-H6 afin que le front consommateur puisse générer un balisage de titre correct (hiérarchie des <h1>-<h6>).
Pour restreindre un type précis (ex. réservé aux admins), surcharger authorizeSave() — voir examples/CalloutBlockType.php.
Lister les types de blocs enregistrés
php artisan blocks:types
Affiche la clé et la classe de chaque type enregistré dans BlockTypeRegistry (les trois types par défaut du package + tous les types métier enregistrés par le projet consommateur). Pratique pour vérifier, dans un environnement donné, quels type sont réellement acceptés par les endpoints sans avoir à relire tous les boot() des providers.
3. Surcharger le Gate manageBlocks
Le package définit manageBlocks fermé par défaut (return false) : sans surcharge, toutes les routes du contrôleur répondent 403. C'est un choix fail-closed délibéré — le package n'a aucune idée des rôles/permissions de l'application hôte, et un Gate ouvert par défaut serait une faille de sécurité pour tout projet qui oublierait de le configurer.
use Illuminate\Contracts\Auth\Authenticatable; use Illuminate\Support\Facades\Gate; Gate::define('manageBlocks', function (?Authenticatable $user, $blockable) { return match (true) { $blockable instanceof \App\Models\Article => $user?->can('update', $blockable) ?? false, $blockable instanceof \App\Models\Page => $user?->hasRole('editor') ?? false, default => false, }; });
Ce Gate contrôle l'accès général au blockable. BlockType::authorizeSave() s'ajoute en complément pour une restriction fine par type de bloc, indépendante du Gate général.
⚠️ Piège Laravel non évident : le premier paramètre
$userd'une closureGate::definedoit impérativement être typé nullable (?Authenticatable). Laravel inspecte la signature de la closure et, pour une requête non authentifiée (guest), ignore silencieusement le callback si son premier paramètre n'accepte pasnull— retombant alors sur un refus implicite, sans jamais exécuter votre logique. Omettre ce type nullable donne l'impression que la surcharge du Gate "ne marche pas" alors qu'elle n'est simplement jamais appelée pour les visiteurs non connectés.
Tests
composer install vendor/bin/pest
Utilise Orchestra Testbench ; voir tests/TestCase.php et les fixtures dans tests/Fixtures/.
Playground de dev
Le package n'a pas d'application Laravel hôte : les tests tournent contre Testbench (tests/TestCase.php), sans jamais exposer un vrai serveur HTTP. Pour tester manuellement les routes contre une vraie DB (SQLite) sans créer de projet séparé, le package utilise Workbench, inclus dans orchestra/testbench (pas de dépendance supplémentaire).
composer run build # (re)crée workbench/database/database.sqlite et rejoue les migrations composer run serve # démarre le serveur sur http://127.0.0.1:8000
workbench/ joue le rôle du provider applicatif que fournirait un vrai projet consommateur (voir examples/BlocksServiceProvider.php) :
workbench/app/Models/Post.php— blockable de test, whitelisté sous la cléposts,workbench/app/Blocks/CalloutBlockType.php— type de bloc métier d'exemple (au-delà des trois types par défaut du package),workbench/app/Providers/WorkbenchServiceProvider.php— enregistre les deux ci-dessus et surcharge le GatemanageBlocksen tout-ouvert (sandbox uniquement, ne pas reproduire tel quel côté projet réel).
# Post#1 existe déjà après `composer run build` (seedé via workbench/database/seeders) curl http://127.0.0.1:8000/api/structuredContents/posts/1/blocks curl -X POST http://127.0.0.1:8000/api/structuredContents/posts/1/blocks \ -H "Content-Type: application/json" -H "Accept: application/json" \ -d '{"type":"text","content":"Bonjour"}'
testbench.yaml liste les providers dans l'ordre attendu (BlocksServiceProvider du package, puis WorkbenchServiceProvider) et ajoute database/migrations (celles du package, normalement publish-only) en plus de workbench/database/migrations.