Redactor Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require app-verk/redactor-bundle
   

   Ensure your composer.json includes "php": "^7.0||^8.0".

2. Enable the Bundle Add to config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3):

   return [
       // ...
       AppVerk\RedactorBundle\RedactorBundle::class => ['all' => true],
   ];
   

3. Configure Twig Add to config/packages/twig.yaml:

   twig:
       form:
           resources:
               - 'RedactorBundle:Redactor:fields.html.twig'
   

4. Basic Configuration Define Redactor settings in config/packages/redactor.yaml:

   redactor:
       basic:
           settings:
               lang: 'en'
               minHeight: 300
   

5. Include Assets Add to your base template (e.g., base.html.twig):

   <link rel="stylesheet" href="{{ asset('path/to/redactor.css') }}">
   <script src="{{ asset('path/to/redactor.js') }}"></script>
   <script src="{{ asset('bundles/redactor/js/symfony-script.js') }}"></script>
   

6. First Usage Use the RedactorType in a form:

   use AppVerk\RedactorBundle\Form\Type\RedactorType;
   
   $builder->add('content', RedactorType::class, [
       'redactor' => 'basic', // Matches config key
       'attr' => ['class' => 'redactor-field']
   ]);
   

Implementation Patterns

Form Integration

• Dynamic Configuration Override settings per field by passing a nested redactor option:

  $builder->add('description', RedactorType::class, [
      'redactor' => [
          'settings' => [
              'lang' => 'fr',
              'buttons' => ['formatting', '|', 'bold', 'italic']
          ]
      ]
  ]);
  

• Asset Management Use Symfony’s asset component to reference Redactor files:

  {% block stylesheets %}
      {{ parent() }}
      {{ encore_entry_link_tags('redactor') }} {# If using Webpack/Encore #}
  {% endblock %}
  

• Validation Combine with Symfony validators (e.g., NotBlank, Length):

  $builder->add('body', RedactorType::class, [
      'redactor' => 'basic',
      'constraints' => [new Length(['max' => 5000])]
  ]);
  

Advanced Workflows

• Custom Toolbars Extend Redactor’s toolbar via config:

  redactor:
      admin_panel:
          settings:
              buttons: ['html', '|', 'bold', 'italic', 'unorderedlist', 'orderedlist']
  

• Asset Uploads Integrate with VichUploaderBundle or custom upload handlers:

  // Example: Custom upload callback
  $builder->add('body', RedactorType::class, [
      'redactor' => [
          'settings' => [
              'plugins' => ['upload'],
              'upload' => [
                  'imageUpload' => '/api/upload',
                  'fileUpload' => '/api/upload'
              ]
          ]
      ]
  ]);
  

• Twig Extensions Pass Redactor instances to Twig for dynamic initialization:

  {{ redactor_init('editor_id', 'basic') }}
  

Gotchas and Tips

Common Pitfalls

1. Asset Paths

   • Ensure redactor.css/redactor.js paths are correct. Use asset() or encore_entry_link_tags().
   • Fix: Verify public/ or web/ directory structure matches your config.

2. Configuration Overrides

   • Field-level settings override global config. Test with dump($form->getConfig()) to debug.
   • Tip: Use debug:config redactor to inspect loaded settings.

3. JavaScript Conflicts

   • Redactor’s symfony-script.js relies on jQuery. Include it after Redactor’s core JS.
   • Fix: Add to your layout:

     <script src="{{ asset('path/to/jquery.js') }}"></script>
     <script src="{{ asset('path/to/redactor.js') }}"></script>
     <script src="{{ asset('bundles/redactor/js/symfony-script.js') }}"></script>
     

4. Deprecated Methods

   • The bundle assumes Symfony 3/4 patterns. For Symfony 5+, use config/packages/ instead of app/config.yml.
   • Tip: Check RedactorBundle::getPath() for template locations.

Debugging Tips

• Console Logs Enable Redactor’s debug mode via config:

  redactor:
      basic:
          settings:
              debug: true
  

  Check browser console for initialization errors.

• Form Theming Override fields.html.twig in your theme to customize rendering:

  {% extends 'RedactorBundle:Redactor:fields.html.twig' %}
  {% block redactor_widget %}
      {{ parent() }} {# Extend default behavior #}
      <div class="custom-tooltip">...</div>
  {% endblock %}
  

Extension Points

1. Custom Plugins Load additional Redactor plugins via config:

   redactor:
       basic:
           settings:
               plugins: ['spellcheck', 'table']
   

   Ensure plugins are included in your asset pipeline.

2. Event Listeners Attach to form events (e.g., PRE_SET_DATA) to modify Redactor settings dynamically:

   $form->addEventListener(FormEvents::PRE_SET_DATA, function (FormEvent $event) {
       $data = $event->getData();
       if ($data->isAdmin()) {
           $event->getForm()->add('content', RedactorType::class, [
               'redactor' => 'admin_panel'
           ]);
       }
   });
   

3. Symfony 5+ Adjustments

   • Replace AppKernel with config/bundles.php.
   • Use when@debug in Twig to conditionally load Redactor assets:

     {% if app.debug %}
         {{ encore_entry_link_tags('redactor') }}
     {% endif %}