Gravity Editor Bundle Laravel Package

## Getting Started

### Minimal Setup
1. **Install the bundle**:
   ```bash
   composer require attuladzan/gravity-editor-bundle

For non-Flex projects, add to config/bundles.php:

Attuladzan\MarkdownEditorBundle\AttuladzanMarkdownEditorBundle::class => ['all' => true],

2. Install assets (required for frontend functionality):

   php bin/console attuladzan:markdown-editor:install-assets --build
   

   Use --symlink for development to avoid rebuilding assets repeatedly.

3. Basic configuration (optional, defaults are provided):

   # config/packages/attuladzan_markdown_editor.yaml
   attuladzan_markdown_editor:
       editor:
           lang: en  # or 'ru'
   

First Use Case: Symfony Form

Add the editor to a form field:

use Attuladzan\MarkdownEditorBundle\Form\MarkdownEditorType;

$builder->add('description', MarkdownEditorType::class, [
    'label' => 'Content',
    'required' => false,
]);

Implementation Patterns

Form Integration

1. Customize editor options per field:

   $builder->add('content', MarkdownEditorType::class, [
       'editor_options' => [
           'allow_html' => true,
           'sticky_toolbar' => false,
       ],
   ]);
   

2. Validation: Use Symfony’s validation constraints (e.g., NotBlank, Length) as usual. The editor handles markdown input, but validation applies to the raw output.

3. Data transformation: Override setData() or getData() in a custom form type to preprocess markdown or sanitize HTML if allow_html: true.

Twig Integration

1. Embed the editor in templates:

   {{ gravity_markdown_editor({
       name: 'article_content',
       value: article.content,
       attributes: { class: 'custom-editor' }
   }) }}
   

2. Dynamic configuration: Pass editor options via the editor_options parameter:

   {{ gravity_markdown_editor({
       name: 'bio',
       editor_options: { lang: 'ru', allow_html: false }
   }) }}
   

3. Preview mode: For read-only previews, use the readonly option:

   {{ gravity_markdown_editor({ value: article.content, readonly: true }) }}
   

EasyAdmin 5 Integration

1. Add the field to a CRUD controller:

   use Attuladzan\MarkdownEditorBundle\EasyAdmin\Field\MarkdownEditorField;
   
   yield MarkdownEditorField::new('longDescription')
       ->setFormTheme('@AttuladzanMarkdownEditor/Form/attuladzan_markdown_editor_widget.html.twig');
   

2. Enable markdown preview (optional):

   • Install dependencies:

     composer require twig/extra-bundle
     

   • Configure EasyAdmin to render markdown in list/detail views (leverages Twig’s markdown filter if available).

3. Customize per entity:

   yield MarkdownEditorField::new('notes')
       ->setEditorOptions(['allow_html' => false, 'lang' => 'ru']);
   

Plugin Workflows

1. Enable plugins in config/packages/attuladzan_markdown_editor.yaml:

   attuladzan_markdown_editor:
       plugins:
           mermaid: true
           latex: true
   

   Clear cache afterward:

   php bin/console cache:clear
   

2. Use plugins in forms/Twig:

   • Mermaid: Write diagrams in markdown (e.g., ````mermaid graph TD A[Start] --> B{Decision}

   • LaTeX: Use $...$ for inline math and $$...$$ for block math.

3. Debugging plugins: Verify plugin inclusion with:

   php bin/console debug:config attuladzan_markdown_editor
   

   Check the plugins section for enabled features.

Asset Management

1. Development workflow:

   • Use --symlink to avoid rebuilding assets:

     php bin/console attuladzan:markdown-editor:install-assets --symlink
     

   • Rebuild assets when dependencies change:

     cd vendor/attuladzan/gravity-editor-bundle && npm install && npm run build
     

2. Production:

   • Always use --build to ensure assets are compiled:

     php bin/console attuladzan:markdown-editor:install-assets --build
     

Gotchas and Tips

Common Pitfalls

1. Assets not loading:

   • Cause: Forgot to run install-assets or assets weren’t rebuilt.
   • Fix: Run php bin/console attuladzan:markdown-editor:install-assets --build and check browser console for 404 errors.

2. Editor not rendering in EasyAdmin:

   • Cause: Missing form theme or EasyAdmin bundle not installed.
   • Fix: Add ->addFormTheme('@AttuladzanMarkdownEditor/Form/attuladzan_markdown_editor_widget.html.twig') and ensure easycorp/easyadmin-bundle is installed.

3. Plugin features missing:

   • Cause: Plugins enabled in config but not in the editor.
   • Fix: Verify plugins are listed in the debug config and that the corresponding npm packages are installed in the bundle’s node_modules.

4. XSS vulnerabilities:

   • Cause: allow_html: true with untrusted input.
   • Fix: Sanitize HTML output using a library like htmlpurifier or validate input strictly.

Debugging Tips

1. Check editor initialization: Open browser dev tools (F12) and inspect the editor’s console logs for errors. Look for:

   • Missing assets (404s).
   • JavaScript errors in gravity-markdown-editor.js.

2. Validate configuration: Use the debug command to verify settings:

   php bin/console debug:config attuladzan_markdown_editor
   

   Compare output with your config/packages/attuladzan_markdown_editor.yaml.

3. Clear cache aggressively: After changing config or plugins, run:

   php bin/console cache:clear --env=prod
   

Extension Points

1. Customize the editor instance: Override the Twig function or form type to pass additional options:

   {{ gravity_markdown_editor({
       name: 'content',
       editor_options: {
           custom_plugin: {
               enabled: true,
               config: { /* ... */ }
           }
       }
   }) }}
   

2. Extend plugins: The bundle supports Gravity UI’s plugin system. To add a custom plugin:

   • Extend the editor’s configuration in JavaScript (via a custom asset).
   • Register the plugin in the bundle’s resources/js/app.js or override it in your project’s assets.

3. Override templates: Copy the bundle’s Twig templates to your project (e.g., templates/bundles/AttuladzanMarkdownEditor/) to customize rendering.

Performance Considerations

1. Lazy-load plugins: Disable unused plugins (e.g., mermaid, latex) to reduce bundle size:

   attuladzan_markdown_editor:
       plugins:
           mermaid: false
           latex: false
   

2. Asset optimization: For production, ensure assets are minified and cached. Use --build flag during installation.

3. Form type optimization: Avoid passing large editor_options objects to forms. Use bundle-level config for shared settings and override only what’s necessary per field.

Localization

1. Language support: The editor supports en and ru out of the box. Add other languages by:

   • Extending the bundle’s translation files.
   • Overriding the editor’s locale configuration in JavaScript.

2. Form labels: Localize form labels in your Symfony translation files (e.g., translations/messages.ru.yaml).

Security

1. HTML sanitization: If allow_html: true, always sanitize output before rendering in templates:

   {{ article.content|striptags }}
   

   Or use a library like htmlpurifier.

2. Plugin safety: Plugins like latex or mermaid may introduce XSS risks if user input is rendered unsafely. Validate and sanitize dynamic content.

3. CSRF protection: Ensure forms using the editor include Symfony’s CSRF token for security.

---