Quill Editor Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Run composer require eductool/quill-editor-bundle and register the bundle in config/bundles.php if not using Symfony Flex. Execute php bin/console assets:install --symlink --relative to ensure assets are symlinked.

2. First Use Case Add the quill_editor field type to a form:

   use Eductool\QuillEditorBundle\Form\Type\QuillEditorType;
   
   $builder->add('content', QuillEditorType::class);
   

   The editor will render automatically with default options (Snow theme, placeholder, etc.).

3. Where to Look First

   • Check config/packages/quill_editor.yaml for default configurations.
   • Review the Quill.js documentation for editor capabilities.
   • Inspect the generated HTML in public/build/quill-editor/ for asset paths.

Implementation Patterns

Usage Patterns

1. Basic Form Integration Use the QuillEditorType in Symfony forms to replace standard textareas:

   $builder->add('description', QuillEditorType::class, [
       'label' => 'Rich Text Description',
       'default_options' => [
           'theme' => 'bubble',
           'modules' => [
               'toolbar' => [
                   ['bold', 'italic', 'underline'],
                   [{ 'list': 'ordered' }, { 'list': 'bullet' }],
               ],
           ],
       ],
   ]);
   

2. Dynamic Initialization Disable auto_initialize in config and initialize via JavaScript:

   quill_editor:
       default_options:
           auto_initialize: false
   

   document.addEventListener('DOMContentLoaded', () => {
       const editor = new Quill('#quill-editor', {
           theme: 'snow',
           modules: { toolbar: [] }
       });
   });
   

3. Custom Themes/Modules Override CDN assets or bundle them manually:

   quill_editor:
       include_cdn: false
       cdn:
           stylesheets:
               snow: '/path/to/custom/snow.css'
   

4. Data Handling Quill stores content in HTML format. Sanitize output before saving:

   $content = $form->get('content')->getData();
   $sanitized = filter_var($content, FILTER_SANITIZE_FULL_SPECIAL_CHARS);
   

Workflows

• Editor Customization: Extend the toolbar or themes via default_options in forms or config.
• Asset Management: Use assets:install to update assets after Quill.js version changes.
• Validation: Validate rich text content length or allowed HTML tags:

  $builder->add('content', QuillEditorType::class)
      ->addModelTransformer(new CallbackTransformer(
          function ($html) { return strlen($html) <= 5000; },
          function ($plain) { return $plain; }
      ));
  

Integration Tips

• Symfony UX: Combine with Symfony UX Turbo for live updates or Stimulus for dynamic interactions.
• APIs: Serialize Quill’s Delta format for APIs:

  $delta = json_decode($form->get('content')->getData(), true);
  

• Testing: Use Quill’s getContents() method in JavaScript tests to verify editor state.

Gotchas and Tips

Pitfalls

1. Asset Loading

   • Forgetting assets:install after updates may break the editor.
   • Fix: Run assets:install post-installation or use include_cdn: true (default).

2. Content Sanitization

   • Quill outputs raw HTML; unsanitized content risks XSS.
   • Fix: Use filter_var() or libraries like HTML Purifier.

3. Module Conflicts

   • Overriding modules in config may break default toolbar functionality.
   • Fix: Merge with defaults:

     modules:
         toolbar:
             - [bold, italic] # Extends, not replaces
     

4. Auto-Initialization

   • Setting auto_initialize: false requires manual JS initialization.
   • Fix: Ensure #quill-editor IDs match form field names.

5. CDN Dependencies

   • include_cdn: true adds latency. Disable for offline use or custom hosting.
   • Fix: Set include_cdn: false and host Quill assets manually.

Debugging

• Console Errors: Check for missing assets or JS errors in browser dev tools.
• Editor Not Rendering: Verify quill-editor class exists on the <div> and assets are loaded.
• Delta Format: Use console.log(editor.getContents()) to inspect raw content.

Config Quirks

• Theme Overrides: Custom themes must be loaded before Quill initializes.
• Module Order: Toolbar modules appear in the order defined; reorder as needed.
• Height Units: height in default_options uses pixels (not rem/em).

Extension Points

1. Custom Field Types Extend QuillEditorType to add validation or transformers:

   class CustomQuillType extends QuillEditorType {
       public function configureOptions(OptionsResolver $resolver) {
           $resolver->setDefaults(['custom_option' => true]);
       }
   }
   

2. Event Listeners Hook into Quill’s events via JavaScript:

   document.querySelector('.quill-editor').addEventListener('text-change', (delta) => {
       console.log('Content changed:', delta);
   });
   

3. Asset Bundling Override default assets by creating a custom bundle or using Webpack Encore:

   // webpack.config.js
   Encore
       .addEntry('quill-custom', './assets/quill-custom.js')
       .copyFiles({
           from: './vendor/quill/dist/',
           to: 'build/quill-custom/[name].[ext]'
       });
   

4. Symfony Forms Use quill_editor with form themes or custom templates:

   {% block quill_editor_widget %}
       {{ form_widget(form) }}
       <script>
           // Custom init logic
       </script>
   {% endblock %}