Download the PHP package mediagone/vue-in-twig-bundle without Composer

mediagone/vue-in-twig-bundle

Integrates Vue.js 3 into Twig/Symfony templates and extends Vue's capabilities with Twig's server-side power: slots, extends, embed...

Compose your components, inject PHP constants or initial data directly into them and generate safe Symfony URLs with dynamic parameters.

No Node.js toolchain required: no bundler, no build step, no node_modules...

The primary objective is to automate and simplify using Vue inside a Symfony/Twig app, without adding a JS build toolchain on top of it.

Table of contents

• Installation
• Configuration
• Introduction
  • Credo: PHP as the single source of truth
  • What Twig brings that Vue alone cannot do
• Get started
  • Create a Vue application
  • Declare and include components
  • Override the default configuration
• Differences from standard Vue.js
  • Delimiters
  • Injecting server-side data into Vue props
  • Injecting PHP constants into Vue expressions
  • Generate safe URLs for Symfony's routes
  • File naming convention
  • Twig composition over Vue slots
• Examples
• Local development

Installation

This package requires PHP 8.1+, Twig 3 and "symfony/framework-bundle" ^6.1|^7.0

1. Add it as Composer dependency:

2. Register the bundle in config/bundles.php:

3. Load Vue 3 full build (with compiler) in your layout. \ Note: the compiler build is required since there is no precompile step, the x-templates are compiled in the browser at runtime.

4. A few components also call API endpoints via axios — load it once if you use any of these: ToggleButton, UploadZone, DataList, DataEditor

Introduction

This bundle formalizes a specific integration pattern: Vue components are written as x-templates, rendered and composed server-side by Twig.

PHP as the single source of truth

Beyond simplifying the front-end toolchain, the core benefit of rendering Vue server-side with Twig is that PHP stays the single source of truth, automatically kept in sync with the front-end.

Server-side values — enum cases, constants, config, URLs — flow into the Vue UI at render time, so there is no hand-maintained JS duplicate that silently drifts out of sync when the PHP changes.

A concrete example: a <select> populated by iterating a PHP enum's cases in Twig.

Add, rename or remove a case in BlockType, and the dropdown updates on the next render — no parallel JS array to keep in sync. \ The same idea applies to v-if checks against a status, a list of allowed types, a feature flag, etc. (see Injecting PHP constants into Vue expressions below).

What Twig brings that Vue alone cannot do:

• Compose components server-side (Twig blocks/embeds — see Twig composition over Vue slots)
• Inject PHP constants without an API call: v-if="type === '{{ constant('Domain\\Block::TYPE_A') }}'"
• Inject initial data without an API call: :account="{{ account|vue_json_encode }}"
• Generate type-safe Symfony URLs with dynamic Vue expressions, via vue_path()

Get started

Everything is wired from your layout via Twig tags and functions — there is no .js entry file to write by hand.

Use {% vue_app %} to create and mount automatically your Vue application:

Declare required components to be queued for inclusion with the {% vue_use %} tag:

Every {% vue_use %} tag must be used within the {% vue_app %} tags — whether placed in the same template or in any included or extended template:

Example:

Layout.twig:

Page.twig:

Partial.twig:

Placed in your base layout, vue_app will output:

1. Opening tag → <script>window.VUE_APP = Vue.createApp(window.VUE_ROOT ?? {});</script> + setup.js (delimiters, global mixin)
2. Body → rendered normally; {% vue_use %} tags queue components silently (no output)
3. Closing tag → all queued component templates + scripts (deduplicated, in call order) + <script>VUE_APP.mount('selector');</script>

Differences from standard Vue.js

Delimiters

Vue's default {{ }} delimiters conflict with Twig, so Vue-in-twig reconfigures them to [[ ]]. \ Use [[ ]] everywhere Vue reactivity is needed — in x-templates (.vue.twig) and in the mounted HTML.

The two template engines coexist in the same markup, each running at a different time:

Twig composition over Vue slots

Components in this bundle are extended/composed with Twig ({% embed %} + blocks — server-side composition) rather than Vue's slots, because they are too limited for and offer less customization. This is why a complex component like DataList exposes Twig blocks instead of Vue slots for its markup — see the DataList example.

Simple, purely visual customization points (a button label, a small fragment of markup) still use regular Vue slots — e.g. Modal's header/footer, DropZone's instructions/infos...

Injecting server-side data into Vue props

Twig {{ }} still works inside HTML attributes — Twig renders the attribute value as a string, and Vue reads it as a JS expression:

Both lines above write the value raw, with no JSON encoding — safe here given the nature of these values: app.request.locale and maxFileSizeBytes can't contain characters that would break the expression. For anything else (user input, free text, structured data...) this library provides the |vue_json_encode filter, which is an HTML-safe replacement for |json_encode that serializes and escapes the value safely:

_Note: vue_json_encode applies JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_AMP | JSON_HEX_QUOT | JSON_THROW_ON_ERROR._

Injecting PHP constants into Vue expressions

Constants and enums can be injected directly into Vue attribute values — Twig renders them as literal strings before Vue compiles the template.

Generate safe URLs for Symfony's routes

Symfony URLs combining static and dynamic, Vue-side parameters can be safely generated via the vue_path(route, staticParams, dynamicParams) function (similar to Symfony's path()):

Generates: '/ajax/account?accountId=__ACCOUNTID__'.replace('__ACCOUNTID__', account.id)

File naming convention

.vue.twig + .vue.js — immediately identifies Vue files among other Twig templates.

Placed in your base layout, it'll output:

1. Opening tag → <script>window.VUE_APP = Vue.createApp(window.VUE_ROOT ?? {});</script> + setup.js (delimiters, global mixin)
2. Body → rendered normally; {% vue_use %} tags queue components silently (zero output)
3. Closing tag → all queued component templates + scripts (deduplicated, in call order) + <script>VUE_APP.mount('selector');</script>

VUE_ROOT — root component options

Vue.createApp() is called with window.VUE_ROOT ?? {}. Declare root-level data()/methods/etc. globally before {% vue_app %} runs:

Tip — mount placement

Vue replaces the mount target's content (container.innerHTML = '') before mounting. Since {% endvue_app %} outputs the queued x-templates and component scripts, place {% vue_app %}...{% endvue_app %} after the element you mount onto (e.g. after </div> closing #App), not inside it — otherwise the x-templates get wiped out before Vue can read them.

Declare and include components (2)

Vue components are declared and queued for inclusion via the {% vue_use %} tag:

Can be called from any partial, before {% endvue_app %}. Duplicate calls are ignored (include-once); the queue otherwise preserves call order. Each call queues two files (if they exist):

• Category/ComponentName.vue.twig — the x-template
• Category/ComponentName.vue.js — the component registration

By default, a bare 'Category/Name' resolves against the bundle's own @VueInTwig namespace — this is what you use for every built-in component shown in Examples.

Registering your own components

By default, a bare 'Category/Name' resolves against the bundle's own @VueInTwig namespace — this is what you use for every built-in component shown in examples.

{% vue_use %} also accepts an explicit @Namespace/... reference, used as-is instead of being prefixed. This lets a consuming app register its own Vue components through the same queue/dedup mechanism — typically to extend a bundle component (see the DataList example).

Without this config, the default namespace stays @VueInTwig, so every bare {% vue_use 'Category/Name' %} keeps resolving to the bundle's own components — no change for the common case.

Order matters. The queue is flushed in call order, immediately before VUE_APP.mount(). A component that extends another (e.g. VUE_APP.component('vue-datalist')) must be {% vue_use %}'d after its base — otherwise the base isn't registered yet when the extending component reads it.

Override the default configuration

The default configuration can be overridden via the vue_config function or tag, which populates window.VUE_CONFIG — read by setup.js and by components such as DataList. Two complementary forms:

The dot-path maps to VUE_CONFIG.root.key ('search.debounceMs' → VUE_CONFIG.search = { debounceMs: 500 };). Both forms write the same way and can target the same root key from different places; the buffered config is flushed once as a single <script> block at {% endvue_app %}, replacing the old pattern of an inline <script>VUE_CONFIG.x = ...;</script> override placed by hand in the body.

setup.js mixins and helpers

setup.js is rendered automatically by the opening {% vue_app %} tag. It provides:

Examples

Each example assumes the component was declared with {% vue_use %} and Vue 3 (+ axios where noted) is loaded, as described in Get started. Props tables list every prop declared on the component; "Required" props have no default.

Controls

DatePicker (vue-date-picker)

Date selection input (year / month / day selects).

Props

Emits: dateSelected (the new Date)

DatetimePicker (vue-datetime-picker)

Date + time selection input.

Props

Emits: dateSelected (the new Date)

DropZone (vue-drop-zone)

File selection + validation + a confirmation preview modal. Does not upload — it only emits the selected files; the parent handles the actual upload (see UploadZone for an integrated alternative).

Props

Emits: select (array of valid File objects, once confirmed in the preview modal)

Slots

UploadZone (vue-upload-zone)

File selection with an integrated upload (axios) and an optional built-in crop step (embeds ImageCropper) before sending.

Props

Emits: uploaded (the server response's results)

ImageCropper (vue-image-cropper)

Interactive crop UI (8 resize handles + move) over a source image, rendering the crop to a <canvas>.

Props

Emits: cropped (a Blob, from canvas.toBlob())

SwitchButton (vue-switch-button)

Toggle switch that is parent-controlled: it never mutates the bound object itself, it only asks for the change.

Props

Emits: switch-request (the would-be next value — the parent decides whether/how to apply it, e.g. after an API call)

ToggleButton (vue-togglebutton)

Two-state button that is API-driven, unlike SwitchButton: it fetches its own current value on creation and posts the change itself.

Props

On creation, performs GET {api_url}?fields={result_property} and reads response.data.results[result_name][result_property]. On click, POSTs the new value the same way and updates from the response. No emits — state lives in the component.

Layout

Modal (vue-modal)

Props

Emits: clickyes, clickno (from the default footer buttons)

Slots

LockWrapper (vue-lock-wrapper)

Locks/unlocks its content (e.g. a disabled form until the user explicitly unlocks it).

No props. Internal state: locked (defaults to true).

Slots

Behaviors

Renderless components (no wrapper element) — they apply behavior directly to their single child.

AutoResize (vue-auto-resize)

Resizes its child (e.g. a <textarea>) to fit its content, on input and on window resize. No props, no emits — wraps exactly one child element.

Draggable (vue-draggable)

Native HTML5 drag & drop, zero dependency. Reorders a list's children and moves items between lists sharing the same group.

Props

Emits: update:modelValue (new array), change (no payload) — the component mutates nothing in place, it re-emits new arrays.

Drop feedback is themable via CSS variables (on the list element or :root): --vue-draggable-indicator-color (#2684ff), --vue-draggable-indicator-size (2px), --vue-draggable-indicator-style (solid, line mode only), --vue-draggable-placeholder-bg.

Widgets

DataEditor (vue-data-editor)

Formalizes an inline-edit pattern: tracks whether item changed since it was loaded/saved, and shows a save bar only when there's something to save.

Props

No emits. Calling changed() (exposed in the default slot) re-checks whether item differs from its last-saved snapshot and shows/hides the save bar accordingly; save() posts the listed properties and re-snapshots on success.

Slots

DataList (vue-datalist)

Formalizes a list pattern: fetch + pagination + create/delete, with debounced refresh for search/filter inputs. vue-datalist itself is logic only — it has no template and no slots. The markup comes from embedding Widgets/DataList.twig and overriding its Twig blocks; your own component then extends the base logic.

1. Base component — queue it like any other:

2. Your extending component — registered in your own app, under your configured namespace so it loads through the same queue, after the base:

3. The markup — embed the bundle's template, overriding only the blocks you need:

Props (on the base vue-datalist, inherited by your component)

Twig blocks (Widgets/DataList.twig)

Overridable hooks (override in your extending component's methods)

Call this.debounceRefresh() (instead of this.itemsRefresh()) from a search/filter input handler to debounce the request using VUE_CONFIG.debounceSearch.

config shape — { parseResponse, parseErrorResponse, icons, texts, tooltips }, merged over VUE_CONFIG.DataList (global default for every list, set via vue_config); icons/texts/tooltips merge per-key, so a partial override keeps the other defaults.