Scarepiceditor Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer

   composer require benjaminlazarecki/scarepiceditor-bundle
   

   Ensure the bundle is enabled in config/bundles.php:

   return [
       // ...
       BenjaminLazarecki\ScarEpicEditorBundle\ScarEpicEditorBundle::class => ['all' => true],
   ];
   

2. Basic Form Integration Register the epic_editor type in your form builder:

   use BenjaminLazarecki\ScarEpicEditorBundle\Form\Type\EpicEditorType;
   
   $builder->add('content', EpicEditorType::class);
   

3. First Use Case Render the editor in a Twig template:

   {{ form_start(form) }}
       {{ form_row(form.content) }}
       <button type="submit">Save</button>
   {{ form_end(form) }}
   

   The editor will auto-initialize with default EpicEditor settings.

Implementation Patterns

Workflows

1. Dynamic Configuration Override default EpicEditor options via form options:

   $builder->add('content', EpicEditorType::class, [
       'options' => [
           'editor_options' => [
               'basePath' => '/path/to/epic-editor',
               'toolbar' => ['bold', 'italic', 'image'],
           ],
       ],
   ]);
   

2. Asset Management

   • Ensure EpicEditor JS/CSS assets are loaded in your base template:

     {{ encore_entry_link_tags('app') }} {# or manually include #}
     <link rel="stylesheet" href="{{ asset('path/to/epic-editor/epiceditor.css') }}">
     

   • Use Symfony’s asset pipeline (Webpack Encore) to bundle EpicEditor if needed.

3. Form Handling

   • Data is submitted as HTML (default) or Markdown (if configured).
   • Sanitize output server-side (e.g., with HTML Purifier) to prevent XSS.

4. Reusable Components Create a base form type for common use cases:

   class RichTextFormType extends AbstractType {
       public function buildForm(FormBuilderInterface $builder, array $options) {
           $builder->add('body', EpicEditorType::class, [
               'editor_options' => $options['editor_config'] ?? [],
           ]);
       }
   }
   

Integration Tips

• Symfony UX/Twig Bridge: If using Symfony UX, merge with Stimulus controllers for dynamic updates.
• API Projects: Return sanitized HTML in JSON responses for API endpoints.
• Testing: Mock EpicEditor in PHPUnit by overriding the form type’s getConfig() method.

Gotchas and Tips

Pitfalls

1. Asset Paths

   • EpicEditor requires absolute paths for assets (e.g., basePath). Use asset() in Twig or url() in PHP:

     'basePath' => $this->container->get('router')->generate('asset', ['path' => 'path/to/epic-editor']),
     

   • Fix: Configure basePath in config/packages/scare_epic_editor.yaml:

     scare_epic_editor:
         base_path: '%kernel.project_dir%/vendor/oscargodson/epiceditor'
     

2. CSRF Token Conflicts

   • EpicEditor’s AJAX submissions may conflict with Symfony’s CSRF protection.
   • Solution: Exclude the form from CSRF in config/packages/security.yaml:

     enable_csrf: true
     ignore_csrf: true # For AJAX-only forms (use cautiously)
     

3. Markdown Support

   • The bundle defaults to HTML output. To enable Markdown:

     $builder->add('content', EpicEditorType::class, [
         'editor_options' => ['outputFormat' => 'markdown'],
     ]);
     

   • Note: Client-side Markdown rendering requires additional JS (e.g., marked.js).

4. Form Theming

   • Override the epic_editor_widget.html.twig template to customize the editor container:

     {% block epic_editor_widget %}
         <div class="custom-editor">
             {{ parent() }}
         </div>
     {% endblock %}
     

Debugging

• Console Errors: Check for missing assets or JS errors in the browser console.
• Form Data: Verify submitted data with dump($form->getData()) in your controller.
• Configuration: Validate scare_epic_editor.yaml settings with:

  php bin/console debug:config scare_epic_editor
  

Extension Points

1. Custom Toolbars Extend the form type to add dynamic toolbars:

   class CustomEpicEditorType extends EpicEditorType {
       public function configureOptions(OptionsResolver $resolver) {
           $resolver->setDefaults([
               'editor_options' => [
                   'toolbar' => ['bold', 'custom_button'],
               ],
           ]);
       }
   }
   

2. Event Listeners Hook into form events to modify editor behavior:

   $form->addEventListener(FormEvents::PRE_SET_DATA, function (FormEvent $event) {
       $event->getForm()->add('content', EpicEditorType::class, [
           'editor_options' => ['readOnly' => true], // Conditional config
       ]);
   });
   

3. Asset Versioning Append a query string to EpicEditor assets to bypass cache:

   <script src="{{ asset('path/to/epic-editor/epiceditor.js?v=' ~ '1.0') }}"></script>