Easy Gutenberg Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require agence-adeliom/easy-gutenberg-bundle
   

   Ensure your composer.json includes the custom Flex endpoint:

   "extra": {
       "symfony": {
           "endpoint": [
               "https://api.github.com/repos/agence-adeliom/symfony-recipes/contents/index.json?ref=flex/main",
               ...
           ],
           "allow-contrib": true
       }
   }
   

2. Enable the Bundle: Add to config/bundles.php:

   return [
       // ...
       AgenceAdeliom\EasyGutenbergBundle\EasyGutenbergBundle::class => ['all' => true],
   ];
   

3. First Use Case: Modify a CRUD controller (e.g., PageCrudController) to use GutenbergField:

   use AgenceAdeliom\EasyAdminBundle\Field\GutenbergField;
   
   $this->crud->addField(GutenbergField::new('content')->setLabel('Gutenberg Content'));
   

Key Files to Review

• Bundle Config: config/packages/easy_gutenberg.yaml (if auto-generated).
• Field Documentation: Focus on GutenbergField in src/Field/GutenbergField.php.
• Demo: Check tests/ for usage examples (if available).

Implementation Patterns

Core Workflows

1. Basic Gutenberg Integration: Replace or extend existing TextField/HtmlField with GutenbergField for rich content editing:

   $this->crud->addField(
       GutenbergField::new('article_body')
           ->setLabel('Article Content')
           ->setRequired(true)
   );
   

2. Dynamic Configuration: Use setConfig() to customize Gutenberg editor behavior:

   ->setConfig([
       'allowedBlocks' => ['core/paragraph', 'core/image', 'core/heading'],
       'mediaUpload' => ['image', 'video'],
   ]);
   

3. Entity-Specific Setup: Override configureFields() in your CRUD controller to conditionally apply Gutenberg:

   public function configureFields(string $pageName): iterable {
       yield GutenbergField::new('description')
           ->setVisible($pageName === 'blog_post');
   }
   

4. Asset Management: Ensure easyadmin and easy-gutenberg assets are built:

   yarn encore dev --watch
   

   Or configure Symfony Encore to auto-load assets.

5. Form Integration: For non-CRUD forms, use GutenbergType in Symfony forms:

   use AgenceAdeliom\EasyGutenbergBundle\Form\Type\GutenbergType;
   
   $builder->add('content', GutenbergType::class, [
       'config' => ['allowedBlocks' => ['core/paragraph']],
   ]);
   

Integration Tips

• EasyAdmin Version: Ensure compatibility with easyadmin-bundle (tested with 3.x).
• PHP Version: Requires PHP 8.2+ for 3.x branch.
• Database: Store Gutenberg content as JSON in a TEXT column (default behavior).
• Localization: Use setTranslationDomain() for translated labels:

  ->setTranslationDomain('messages')
  

Gotchas and Tips

Pitfalls

1. Asset Loading:

   • Issue: Gutenberg editor may not load if assets aren’t built.
   • Fix: Run yarn encore dev or clear cache (php bin/console cache:clear).
   • Debug: Check browser console for 404 errors on /build/gutenberg-*.

2. Block Restrictions:

   • Issue: Disallowed blocks may break the editor UI.
   • Fix: Explicitly whitelist blocks in setConfig():

     ->setConfig(['allowedBlocks' => ['core/paragraph']])
     

3. Database Schema:

   • Issue: Existing TEXT columns may not handle Gutenberg JSON well.
   • Fix: Use json column type (MySQL 5.7+) or validate JSON with:

     ->setValidatorConstraints([
         new Assert\Json(),
     ]);
     

4. Symfony Cache:

   • Issue: Changes to GutenbergField config may not reflect immediately.
   • Fix: Clear the Symfony cache or use ->setCacheKey(null) to bypass caching.

5. Media Uploads:

   • Issue: Uploaded media may not persist or link correctly.
   • Fix: Configure mediaUpload in setConfig() and ensure easyadmin media handling is set up.

Debugging Tips

• Log Gutenberg Config: Override configureField() to log the final config:

  $field->addModelTransformer(new class implements FieldTransformer {
      public function transform($value, Field $field) {
          if ($field instanceof GutenbergField) {
              error_log('Gutenberg Config:', $field->getConfig());
          }
          return $value;
      }
  });
  

• Check Network Requests: Use browser dev tools to verify Gutenberg assets and API calls (e.g., /api/easyadmin/gutenberg/blocks).

Extension Points

1. Custom Blocks: Extend the editor with custom blocks by:

   • Adding a wp-block-* script to your assets.
   • Configuring setConfig(['allowedBlocks' => ['custom/block']]).

2. Field Transformers: Customize how data is saved/loaded:

   $field->setModelTransformer(new class implements FieldTransformer {
       public function transform($value, Field $field) {
           return json_encode($value, JSON_PRETTY_PRINT);
       }
       public function reverseTransform($value, Field $field) {
           return json_decode($value, true);
       }
   });
   

3. Event Listeners: Hook into Gutenberg events (e.g., block validation) via Symfony events:

   # config/services.yaml
   services:
       App\EventListener\GutenbergListener:
           tags:
               - { name: kernel.event_listener, event: easy_gutenberg.block_validate, method: onBlockValidate }
   

4. Override Templates: Customize the editor UI by overriding Twig templates in templates/easy_gutenberg/.

Configuration Quirks

• Default Config: The bundle provides sensible defaults, but explicitly set setConfig([]) to override all defaults.
• Lazy Loading: Gutenberg assets are lazy-loaded; ensure your base template includes:

  {{ easy_gutenberg_assets() }}
  

• Permissions: Media uploads require proper Symfony security roles (e.g., ROLE_ADMIN).