Ezplatform Richtext Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation Add the bundle to your Laravel project via Composer (if adapted for Laravel via a bridge like ezsystems/ezplatform-laravel-bridge):

   composer require ezsystems/ezplatform-richtext
   

   Register the bundle in config/app.php under providers (if using a Laravel bridge).

2. Configuration Publish the default configuration:

   php artisan vendor:publish --provider="EzSystems\EzPlatformRichText\EzPlatformRichTextBundle" --tag="config"
   

   Update config/ezplatform/richtext.yaml to define your rich text field types and toolbar configurations.

3. Basic Field Definition Define a rich text field in your content type (e.g., in a migration or content type service):

   # Example in a content type YAML (adapted for Laravel)
   fields:
       body:
           type: ezrichtext
           toolbar: full
   

4. First Usage in a Controller Inject the RichTextService and use it to render or process rich text:

   use EzSystems\EzPlatformRichText\API\RichTextService;
   
   public function show(RichTextService $richTextService, $contentId) {
       $content = $contentService->load($contentId);
       $richText = $content->getField('body')->value;
       $html = $richTextService->convertToHTML($richText);
       return view('content.show', ['html' => $html]);
   }
   

5. Toolbar Setup Define toolbars in config/ezplatform/richtext.yaml:

   toolbars:
       full:
           groups:
               - basic
               - text
               - lists
               - links
   

Implementation Patterns

Workflows

1. Content Creation/Editing

   • Use the RichTextService to validate and process rich text input from forms:

     $richTextInput = $request->input('body');
     $validated = $richTextService->validate($richTextInput, 'full');
     $content->setFieldValue('body', $validated);
     

   • Integrate with Laravel's form request validation by extending FormRequest:

     public function rules()
     {
         return [
             'body' => ['required', 'richtext:full'], // Custom validation rule
         ];
     }
     

2. API/Headless CMS

   • Serialize rich text for API responses:

     $data = [
         'title' => $content->getTitle(),
         'body' => $richTextService->convertToArray($content->getField('body')->value),
     ];
     return response()->json($data);
     

   • Deserialize rich text from API requests:

     $richTextInput = $request->input('body');
     $processed = $richTextService->convertFromArray($richTextInput);
     

3. Embedding in Blade Templates

   • Render rich text directly in views:

     {!! $richTextService->convertToHTML($content->body) !!}
     

   • Use partials for reusable rich text components (e.g., richtext/editor.blade.php).

Integration Tips

1. Laravel Form Integration

   • Use collective/html or Laravel's built-in form helpers with the rich text editor:

     {!! Form::textarea('body', old('body'), ['class' => 'richtext-editor']) !!}
     

   • Initialize the editor with JavaScript (e.g., TinyMCE or CKEditor via ezrichtext bundle assets).

2. Event Listeners

   • Listen to content updates to process rich text (e.g., sanitize or log changes):

     public function handle(ContentUpdateEvent $event)
     {
         $richText = $event->getContent()->getField('body')->value;
         $richTextService->sanitize($richText);
     }
     

3. Custom Field Types

   • Extend the rich text field type for custom logic:

     use EzSystems\EzPlatformRichText\FieldType\RichTextType;
     
     class CustomRichTextType extends RichTextType {
         public function getSettings() {
             return array_merge(parent::getSettings(), ['custom' => true]);
         }
     }
     

4. Asset Management

   • Configure asset uploads (images, files) in config/ezplatform/richtext.yaml:

     uploads:
         directory: public/uploads/richtext
         url: /uploads/richtext
     

Gotchas and Tips

Pitfalls

1. Toolbar Misconfiguration

   • Issue: Toolbar groups not loading or breaking the editor.
   • Fix: Ensure all referenced groups (e.g., basic, text) exist in the toolbar definition. Validate YAML syntax for typos or missing colons.

2. HTML Injection Risks

   • Issue: Unsanitized rich text input may expose XSS vulnerabilities.
   • Fix: Always use $richTextService->convertToHTML() with sanitization enabled:

     $html = $richTextService->convertToHTML($richText, ['sanitize' => true]);
     

3. Database Storage

   • Issue: Rich text fields may store large XML/JSON blobs, impacting performance.
   • Fix: Optimize database queries or use Laravel's ->with() to eager-load related content:

     $content = Content::with('body')->find($id);
     

4. Editor Asset Conflicts

   • Issue: JavaScript/CSS conflicts with other editors (e.g., TinyMCE, CKEditor).
   • Fix: Explicitly load ezrichtext assets in a blade layout or use Laravel Mix to isolate dependencies:

     @vite(['resources/js/ezrichtext.js'])
     

5. Laravel Caching Quirks

   • Issue: Rich text processing bypasses Laravel's cache.
   • Fix: Cache processed HTML manually:

     $cacheKey = "richtext_{$contentId}";
     $html = Cache::remember($cacheKey, now()->addHours(1), function() use ($richTextService, $content) {
         return $richTextService->convertToHTML($content->body);
     });
     

Debugging

1. Validation Errors

   • Enable debug mode in config/ezplatform/richtext.yaml:

     debug: true
     

   • Check logs for validation failures (e.g., invalid toolbar usage).

2. Editor Not Loading

   • Verify assets are published:

     php artisan vendor:publish --tag=ezrichtext-assets
     

   • Check browser console for 404 errors on JS/CSS files.

3. Content Not Rendering

   • Ensure the field type is correctly mapped in your content type:

     fields:
         body:
             type: ezrichtext
             toolbar: full
     

   • Validate the field value structure (should be an array/object, not raw HTML).

Extension Points

1. Custom Sanitization

   • Extend the sanitizer by creating a custom service:

     use EzSystems\EzPlatformRichText\API\Sanitizer\SanitizerInterface;
     
     class CustomSanitizer implements SanitizerInterface {
         public function sanitize($richText) {
             // Custom logic
             return $richText;
         }
     }
     

   • Bind it in Laravel's service container:

     $app->bind(SanitizerInterface::class, CustomSanitizer::class);
     

2. Toolbar Plugins

   • Add custom buttons/plugins to the toolbar:

     toolbars:
         custom:
             groups:
                 - basic
             items:
                 - name: customButton
                   icon: icon-custom
                   command: customCommand
     

   • Register the command in JavaScript:

     tinymce.PluginManager.add('customCommand', function(editor) {
         editor.addButton('customButton', {
             text: 'Custom',
             onclick: function() { /* ... */ }
         });
     });
     

3. Field Value Processing

   • Override how rich text is stored/retrieved:

     $content->setFieldValue('body', $richTextService->processForStorage($richTextInput));
     $storedRichText = $richTextService->processFromStorage($content->getField('body')->value);
     

4. Event Subscribers

   • Listen to rich text events (e.g., RichTextConvertEvent):

     public function onRichTextConvert(RichTextConvertEvent $event) {
         if ($event->getType() === 'to_html') {
             $event->setHtml($this->modifyHtml($event->getHtml()));
         }
     }