Tiptap Editor Laravel Package

Getting Started

Minimal Steps to First Use

1. Install the Bundle

   composer require besmartand-pro/tiptap-editor
   php bin/console besmartand-pro:tiptap-editor:install
   

   • The installer auto-detects and adds missing frontend dependencies (@tiptap/*, bootstrap-icons) and configures Encore/Vite.

2. Verify Frontend Build

   • Run pnpm install (or npm install/yarn install) to ensure Tiptap dependencies are installed.
   • Rebuild assets:

     npm run dev  # or yarn dev / pnpm dev
     

3. First Form Integration Add the TiptapType to a Symfony form:

   use BeSmartAndPro\TiptapEditorBundle\Form\Type\TiptapType;
   
   $builder->add('content', TiptapType::class, [
       'tiptap_placeholder' => 'Start typing here...',
   ]);
   

   • Ensure the form template includes Stimulus controllers:

     {{ stimulus_controller('besmartand-pro--tiptap-editor') }}
     

4. Test the Editor

   • Submit the form and verify the HTML content is saved correctly (default storage is plain text; use json column type if storing as JSON).

Where to Look First

• Configuration: Check config/packages/besmartand_pro_tiptap_editor.yaml for upload settings (e.g., Flysystem, security roles).
• Frontend Assets: Inspect assets/controllers/besmartand_pro/tiptap_editor_controller.ts for Stimulus logic and assets/styles/besmartand_pro_tiptap_editor.scss for CSS overrides.
• EasyAdmin: If using EasyAdmin, reference TiptapField in your CRUD controller:

  yield TiptapField::new('content', 'Content')->setPlaceholder('Edit here...');
  

First Use Case: Basic Rich Text Field

Replace a standard textarea in a Symfony form with a WYSIWYG editor:

// src/Form/ArticleType.php
use BeSmartAndPro\TiptapEditorBundle\Form\Type\TiptapType;

class ArticleType extends AbstractType {
    public function buildForm(FormBuilderInterface $builder, array $options) {
        $builder->add('body', TiptapType::class, [
            'tiptap_placeholder' => 'Write your article...',
            'tiptap_toolbar' => ['bold', 'italic', 'bulletList', 'link'], // Customize toolbar
        ]);
    }
}

Template:

{{ form_row(form.body) }}

Result: A lightweight Tiptap editor with the specified toolbar buttons.

Implementation Patterns

Common Workflows

1. Form Integration

• Basic Usage:

  $builder->add('description', TiptapType::class, [
      'tiptap_placeholder' => 'Describe your product...',
      'tiptap_toolbar' => ['heading', '|', 'bold', 'italic'], // Custom toolbar groups
  ]);
  

• Validation: Add constraints to the form field:

  $builder->add('content', TiptapType::class, [
      'constraints' => [new Length(['max' => 5000])],
  ]);
  

2. EasyAdmin Integration

• CRUD Field:

  yield TiptapField::new('content', 'Content')
      ->setPlaceholder('Edit in the editor...')
      ->setFormTypeOption('tiptap_toolbar', ['bold', 'italic', 'link']);
  

• List Display: Override the template to render HTML safely:

  {# templates/easyadmin/crud/field/tiptap.html.twig #}
  {{ field|raw }}
  

3. Image Uploads

• Configuration (config/packages/besmartand_pro_tiptap_editor.yaml):

  besmartand_pro_tiptap_editor:
      upload:
          enabled: true
          filesystem_service: 'oneup_flysystem.images_filesystem'
          public_url_prefix: '/uploads'
          security_attribute: 'ROLE_ADMIN'
          max_file_size: 5242880 # 5MB
  

• Backend Setup: Ensure your Flysystem service (e.g., oneup_flysystem) is configured to handle uploads. The bundle expects a service with writeStream() method.

4. Custom Extensions

• Extend Tiptap: Override the Stimulus controller to add custom extensions:

  // assets/controllers/besmartand_pro/tiptap_editor_controller.ts
  import { MyCustomExtension } from '../extensions/my_custom_extension';
  
  connect() {
      this.editor = new Editor({
          extensions: [
              StarterKit,
              Image,
              Link,
              Placeholder,
              MyCustomExtension, // Add your extension
          ],
      });
  }
  

• Register Extensions: Ensure your extension is imported in the controller and included in the extensions array.

5. Styling Overrides

• SCSS Variables: Override default styles in assets/styles/besmartand_pro_tiptap_editor.scss:

  $tiptap-editor-bg: #f8f9fa;
  $tiptap-toolbar-bg: #e9ecef;
  

• Custom CSS: Target the editor’s root class (e.g., .ProseMirror) in your global stylesheet.

Integration Tips

Symfony Forms

• Data Transformation: The bundle automatically handles conversion between HTML strings and Tiptap’s JSON format. For custom storage, extend the form type:

  class CustomTiptapType extends TiptapType {
      public function configureOptions(OptionsResolver $resolver) {
          $resolver->setDefaults([
              'tiptap_storage_format' => 'json', // Store as JSON instead of HTML
          ]);
      }
  }
  

EasyAdmin

• Field Customization: Use setFormTypeOption to pass options to the underlying TiptapType:

  yield TiptapField::new('content')
      ->setFormTypeOption('tiptap_toolbar', ['bold', 'italic'])
      ->setFormTypeOption('tiptap_placeholder', 'Custom placeholder...');
  

Frontend Builds

• Vite/Encore: The installer auto-detects your build tool and imports the bundle’s stylesheet. If manual setup is needed:
  • Vite: Add to assets/app.ts:

    import './styles/besmartand_pro_tiptap_editor.scss';
    

  • Encore: Add to webpack.config.js:

    Encore
        .addEntry('tiptap-editor', './assets/styles/besmartand_pro_tiptap_editor.scss')
        .enableSassLoader();
    

Security

• Role-Based Uploads: Use the security_attribute config to restrict uploads to specific roles:

  besmartand_pro_tiptap_editor:
      upload:
          security_attribute: 'ROLE_CONTENT_MANAGER'
  

• CSRF Protection: Ensure your upload endpoints include Symfony’s CSRF token validation.

Gotchas and Tips

Pitfalls

1. Frontend Build Failures:

   • Issue: Missing @tiptap/* dependencies after installation.
   • Fix: Run npm install (or pnpm install) and rebuild assets.
   • Debug: Check package.json for missing dependencies and rerun the installer:

     php bin/console besmartand-pro:tiptap-editor:install --force
     

2. Stimulus Controller Not Loading:

   • Issue: Editor not initializing in the browser.
   • Fix: Ensure the Stimulus controller is loaded in your base template:

     {{ stimulus_controller('besmartand-pro--tiptap-editor') }}
     

   • Debug: Check browser console for StimulusController errors and verify the controller file exists at assets/controllers/besmartand_pro/tiptap_editor_controller.ts.

3. Image Uploads Not Working:

   • Issue: Drag-and-drop or paste uploads fail silently.
   • Fix:
     • Verify upload.enabled: true in config.
     • Check that the Flysystem service is correctly configured and accessible.
     • Ensure the public_url_prefix is correct and the files are accessible at the given URL.
   • Debug: Enable debug mode and check Symfony logs for upload errors.

4. Toolbar Buttons Missing:

   • Issue: Custom toolbar buttons (e.g., link) are not appearing.
   • Fix: Ensure the button names match Tiptap’s extension names (e.g., link for ExtensionLink). Refer to Tiptap’s documentation for valid button names.

5. **EasyAdmin Field Not Rendering