README

Symfony UX Bundle implementing VvvebJs — a drag-and-drop page builder and website editor.

Also working out of the box with EasyAdmin.

If you need a visual page builder (with drag-and-drop components) in a Symfony project, this is what you need.

• Installation
• Basic Usage
• Component Groups
• Plugins
• Editor Options
• EasyAdmin Integration
• File Upload
• Data Format
• CDN & Self-Hosting
• JavaScript Events

Installation

Step 1: Require the bundle

composer require makraz/ux-vvvebjs

If you are using the AssetMapper component, you're done!

Step 2: JavaScript dependencies (Webpack Encore only)

If you are using Webpack Encore (skip this step if using AssetMapper):

yarn install --force && yarn watch

Or with npm:

npm install --force && npm run watch

That's it. You can now use VvvebJsType in your Symfony forms.

Basic Usage

In a form, use VvvebJsType. It works like a classic form type with additional options:

use Makraz\VvvebJsBundle\Form\VvvebJsType;

public function buildForm(FormBuilderInterface $builder, array $options): void
{
    $builder
        ->add('content', VvvebJsType::class)
    ;
}

By default, the editor comes with Common, HTML, Elements, and Bootstrap 5 component groups enabled, plus the CodeMirror plugin for code editing.

Component Groups

Component groups define which drag-and-drop blocks are available in the editor's sidebar.

Available Groups

Customizing Components

use Makraz\VvvebJsBundle\Form\VvvebJsType;
use Makraz\VvvebJsBundle\DTO\Enums\VvvebJsComponentGroup;

$builder->add('content', VvvebJsType::class, [
    'vvvebjs_components' => [
        VvvebJsComponentGroup::COMMON,
        VvvebJsComponentGroup::BOOTSTRAP5,
        VvvebJsComponentGroup::EMBEDS,
    ],
]);

You can also pass string values directly:

'vvvebjs_components' => ['common', 'bootstrap5', 'embeds'],

Plugins

Plugins extend the editor with additional functionality.

Available Plugins

Customizing Plugins

use Makraz\VvvebJsBundle\Form\VvvebJsType;
use Makraz\VvvebJsBundle\DTO\Enums\VvvebJsPlugin;

$builder->add('content', VvvebJsType::class, [
    'vvvebjs_plugins' => [
        VvvebJsPlugin::CODE_MIRROR,
        VvvebJsPlugin::GOOGLE_FONTS,
        VvvebJsPlugin::AOS,
        VvvebJsPlugin::JSZIP,
    ],
]);

Editor Options

Use the vvvebjs_options parameter to configure global editor behavior:

$builder->add('content', VvvebJsType::class, [
    'vvvebjs_options' => [
        'height' => '800px',
        'border' => true,
        'designerMode' => false,
        'readOnly' => false,
        'uploadUrl' => '/vvvebjs/upload',
    ],
]);

EasyAdmin Integration

The bundle provides a dedicated VvvebJsAdminField for seamless EasyAdmin integration:

use Makraz\VvvebJsBundle\Form\VvvebJsAdminField;

public function configureFields(string $pageName): iterable
{
    yield VvvebJsAdminField::new('content');
}

To customize components, plugins, and options, use setFormTypeOptions:

use Makraz\VvvebJsBundle\DTO\Enums\VvvebJsComponentGroup;
use Makraz\VvvebJsBundle\DTO\Enums\VvvebJsPlugin;

yield VvvebJsAdminField::new('content')
    ->setFormTypeOptions([
        'vvvebjs_components' => [
            VvvebJsComponentGroup::COMMON,
            VvvebJsComponentGroup::BOOTSTRAP5,
        ],
        'vvvebjs_plugins' => [
            VvvebJsPlugin::CODE_MIRROR,
            VvvebJsPlugin::GOOGLE_FONTS,
        ],
        'vvvebjs_options' => [
            'height' => '700px',
            'uploadUrl' => '/vvvebjs/upload',
        ],
    ])
;

The field automatically registers the Twig form theme and works with both AssetMapper and Webpack Encore.

File Upload

The bundle provides a built-in upload controller. Three storage options are available: local filesystem, Flysystem, or your own custom handler.

Option 1: Local Filesystem (default)

Store uploads in your Symfony public/ directory:

# config/packages/vvvebjs.yaml
vvvebjs:
    upload:
        enabled: true
        handler: local
        local_dir: '%kernel.project_dir%/public/uploads/vvvebjs'
        local_public_path: '/uploads/vvvebjs'
        max_file_size: 10485760  # 10 MB
        allowed_mime_types:
            - image/jpeg
            - image/png
            - image/gif
            - image/webp
            - image/svg+xml
            - video/mp4
            - video/webm
            - application/pdf

Then import the bundle routes:

# config/routes/vvvebjs.yaml
vvvebjs:
    resource: '@VvvebJsBundle/config/routes.php'

And set the upload URL in your form:

$builder->add('content', VvvebJsType::class, [
    'vvvebjs_options' => [
        'uploadUrl' => '/vvvebjs/upload',
    ],
]);

Option 2: Flysystem

Store uploads via League Flysystem (S3, GCS, Azure, SFTP, etc.):

composer require league/flysystem-bundle

# config/packages/vvvebjs.yaml
vvvebjs:
    upload:
        enabled: true
        handler: flysystem
        flysystem_storage: 'default.storage'
        flysystem_path: 'uploads/vvvebjs'
        flysystem_public_url: 'https://cdn.example.com'
        max_file_size: 10485760  # 10 MB

Option 3: Custom Handler

Implement your own upload logic by creating a service that implements UploadHandlerInterface:

use Makraz\VvvebJsBundle\Upload\UploadHandlerInterface;
use Symfony\Component\HttpFoundation\File\UploadedFile;

class MyUploadHandler implements UploadHandlerInterface
{
    public function upload(UploadedFile $file): string
    {
        // Your upload logic here
        // Return the public URL of the uploaded file
        return 'https://example.com/path/to/file.jpg';
    }
}

# config/packages/vvvebjs.yaml
vvvebjs:
    upload:
        enabled: true
        handler: custom
        custom_handler: App\Upload\MyUploadHandler

Upload Configuration Reference

Data Format

VvvebJs outputs full HTML. The value stored in your entity will be a complete HTML string including the <html>, <head>, and <body> tags:

<html>
<head></head>
<body>
    <div class="container mt-4">
        <h1>My Page</h1>
        <p>Built with drag-and-drop.</p>
    </div>
</body>
</html>

Rendering in Twig

To display VvvebJs content in your templates, render the HTML directly:

{{ myEntity.content|raw }}

Or embed it within an iframe for full-page previews:

<iframe srcdoc="{{ myEntity.content|e('html_attr') }}" style="width: 100%; height: 600px; border: none;"></iframe>

CDN & Self-Hosting

By default, VvvebJs assets are loaded from the jsDelivr CDN:

https://cdn.jsdelivr.net/gh/givanz/VvvebJs@master

To self-host VvvebJs or use a specific version, configure the cdn_url:

# config/packages/vvvebjs.yaml
vvvebjs:
    cdn_url: '/bundles/vvvebjs'  # Local path
    # or
    cdn_url: 'https://cdn.jsdelivr.net/gh/givanz/VvvebJs@v0.7.7'  # Pinned version

JavaScript Events

The Stimulus controller loads VvvebJs assets dynamically and initializes the builder. The editor syncs HTML back to the hidden form input on form submit and before page unload.

Symfony Live Component Compatibility

The editor container is built dynamically by the Stimulus controller, so it works correctly alongside Symfony Live Components.

Requirements

• PHP >= 8.1
• Symfony 6.4, 7.x, or 8.x
• symfony/stimulus-bundle >= 2.9.1

License

MIT