Block Bundle I18N Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require arkounay/block-bundle-i18n
   

   Ensure your composer.json aligns with the package's Symfony 3.x constraints.

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

   Arkounay\BlockBundleI18n\BlockBundleI18n::class => ['all' => true],
   

3. Database Setup: Run migrations (if using Doctrine) to enable multilingual fields:

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

4. First Use Case: Create a block entity with translatable content:

   php bin/console make:entity Block
   

   Add fields like content (type: text) and mark them for translation via A2lix\TranslationFormBundle annotations.

Implementation Patterns

Core Workflows

1. Block Creation & Management:

   • Use BlockManager to create, update, or fetch blocks:

     $block = $blockManager->create('page_header', ['content' => 'Hello']);
     $blockManager->save($block);
     

   • Inject BlockManager into controllers/services via dependency injection.

2. Multilingual Content Handling:

   • Leverage a2lix/translation-form-bundle for form translations:

     {{ form_start(form) }}
       {{ form_row(form.content) }} {# Translatable field #}
     {{ form_end(form) }}
     

   • Fetch translated content by locale:

     $content = $block->getTranslation('content', 'en');
     

3. TinyMCE Integration:

   • Configure TinyMCE in your Twig templates:

     {{ block('tinymce') }}
     

   • Customize toolbar/buttons via config/packages/arkounay_block_i18n.yaml:

     arkounay_block_i18n:
         tinymce:
             toolbar: bold italic | link unlink
     

4. Inline Editing:

   • Enable inline editing for blocks in templates:

     {# Render block with editable content #}
     {{ block_content(block, { editable: true }) }}
     

Integration Tips

• Symfony Forms: Extend BlockType to customize block fields:

  class CustomBlockType extends AbstractBlockType {
      public function buildForm(FormBuilderInterface $builder, array $options) {
          $builder->add('custom_field', TextType::class);
      }
  }
  

• Event Listeners: Hook into block events (e.g., BlockEvents::PRE_SAVE) for pre-processing:

  $eventDispatcher->addListener(BlockEvents::PRE_SAVE, function (BlockEvent $event) {
      $block = $event->getBlock();
      // Sanitize or modify block data
  });
  

Gotchas and Tips

Common Pitfalls

1. Locale Mismatches:

   • Ensure a2lix/translation-form-bundle is configured with supported locales in config/packages/a2lix_translation_form.yaml:

     a2lix_translation_form:
         default_locale: en
         supported_locales: [en, fr, es]
     

   • Fix: Clear cache after adding new locales:

     php bin/console cache:clear
     

2. TinyMCE Assets Not Loading:

   • Verify assets/install was run post-installation:

     php bin/console assets:install
     

   • Fix: Manually link TinyMCE CSS/JS in your base template if auto-install fails.

3. Doctrine Behaviors Conflicts:

   • The bundle uses knplabs/doctrine-behaviors for timestamps. Ensure no duplicate behaviors are applied to the same entity.

4. Deprecated Symfony 3.x:

   • Avoid using Symfony 4/5 features (e.g., AbstractController). Stick to Symfony 3.x patterns.

Debugging Tips

• Check Block Existence:

  if (!$blockManager->exists('page_header', ['id' => 123])) {
      throw new \RuntimeException('Block not found');
  }
  

• Log Translations: Enable debug mode to inspect translation data:

  # config/packages/dev/arkounay_block_i18n.yaml
  arkounay_block_i18n:
      debug: true
  

Extension Points

1. Custom Block Types:
   • Create subclasses of Block and register them via services:

     services:
         App\Entity\CustomBlock:
             tags: ['arkounay.block.type']
     

2. Override Templates:
   • Copy templates from vendor/arkounay/block-bundle-i18n/Resources/views/ to templates/arkounay_block_i18n/ to customize rendering.
3. Add Validation:
   • Extend BlockValidator to add custom rules:

     class CustomBlockValidator extends BlockValidator {
         public function validate($block, Constraint $constraint) {
             // Custom logic
         }
     }
     

     Register it in services.yaml:

     services:
         App\Validator\CustomBlockValidator:
             tags: ['validator.constraint_validator']
     

```markdown
### Configuration Quirks
- **Default Locale Fallback**: The bundle defaults to `en` if no locale is specified. Override in `config/packages/arkounay_block_i18n.yaml`:
  ```yaml
  arkounay_block_i18n:
      default_locale: fr

• Translation Storage: Translations are stored in a separate table (e.g., block_translation). Ensure your Doctrine schema reflects this.