Download the PHP package setono/sylius-video-plugin without Composer

Sylius Video Plugin

Adds a Videos tab to the admin product create/edit page so editors can attach videos to a product through three built-in types — file upload, external URL and direct embed code — and renders them on the shop product page.

An optional fourth type, Cloudflare Stream, uploads videos from the admin's browser straight to Cloudflare Stream and plays them on the product page through Cloudflare's own player, or a player of your choice — see Cloudflare Stream.

Videos are stored with Single Table Inheritance (a base ProductVideo plus FileProductVideo / UrlProductVideo / EmbedProductVideo subtypes) and presented through tagged composite renderers, so the plugin is extended exactly like setono/sylius-qr-code-plugin: add a subtype + a resource entry + a renderer and the discriminator map picks it up — no edits to the plugin's mapping required.

Installation

Requirements

• Sylius with the Gedmo sortable and timestampable listeners enabled (Sylius core enables them by default). They fill the position, created_at and updated_at columns of a video; an application that disables stof_doctrine_extensions cannot insert videos.
• Sylius 1.13 or newer with sylius/resource-bundle 1.11 or newer, which is what Sylius 1.13 and 1.14 ship; the plugin uses nothing newer from the resource bundle, so installing it never forces a resource-bundle bump.
• No other runtime dependency beyond what Sylius already ships.

1. Require the plugin

2. Register the bundle

3. Make your Product own its videos

Implement ProductVideosAwareInterface and use the trait on your Product:

That is all for an attribute-mapped Product (the Sylius-Standard default): the trait's videos property carries the OneToMany attributes (mapped by product, cascade persist, orphan removal, ordered by position), and Doctrine reads them through your class. The owning ManyToOne lives on ProductVideo. The test application under tests/Application does exactly this.

If your Product is XML- or YAML-mapped instead, the attributes are ignored and you declare the inverse side yourself, next to the rest of your mapping:

Either way, point the product resource at your class (skip if you already override it):

4. Update the database

The plugin does not ship migrations — generate one against your own schema and run it:

This creates the single setono_sylius_video__product_video table. The discriminator listener adds the Single Table Inheritance map at runtime (keyed on each subtype's getType()), so no extra mapping is needed beyond the videos association you added in step 3. The type column is 64 characters wide so derived type names of custom subtypes fit; installs created with an earlier development version (20 characters) pick the change up with another doctrine:migrations:diff.

5. Install assets

This publishes the small dependency-free JavaScript controller that toggles the type-specific field on the adaptive entry form to match the selected type, and the shop stylesheet that keeps the video block responsive (it stretches pasted embed iframes to the 16:9 box). The stylesheet is added to the shop layout through the sylius.shop.layout.stylesheets event; override or disable that setono_sylius_video block if your theme ships its own styles.

Upload limits

Video files go through the same Sylius media filesystem as product images. That adapter is string-based, so each upload passes through PHP memory once, and the request must fit the upload_max_filesize, post_max_size and memory_limit of the PHP that serves the admin. Size those for the largest video you expect (a few hundred megabytes is a practical ceiling), and prefer attaching very large videos as an External URL video hosted elsewhere.

Uploads are validated in the sylius group by the plugin's validation XML: a video file must sniff as video/mp4, video/webm, video/ogg or video/quicktime, and a poster must be a JPEG, PNG or WebP image of at most 10 MB. To tighten either (a lower video size cap, fewer types), add your own constraints for Setono\SyliusVideoPlugin\Model\FileProductVideo or ProductVideo in config/validator/; Symfony merges them with the plugin's.

Usage

• Admin: open any product's edit page and switch to the Videos tab. Add videos, pick a type (file / url / embed) per row, and optionally attach a poster image. The type is fixed once a video is saved (to change it, remove the row and add a new one). Ordering uses the per-row position field (lowest first); positions are maintained per-product by the Gedmo Sortable extension Sylius already enables, so a new row left blank is appended automatically. Removing a video (or its product, through the orphan-removal mapping above) also deletes the stored video file and poster once the change is flushed.

• Shop: the product's videos render on the product page as a block on the sylius.shop.product.show.content event (it always fires, unlike before_thumbnails, which only fires for products with more than one image), under a "Videos" heading, after the product tabs and before the associations (priority 12; Sylius renders higher priorities first, tabs are 20 and associations 10). Move it, drop the heading or disable it by overriding the block:

  Or render videos wherever you like:

• Twig functions (setono_sylius_video_render is marked HTML-safe; setono_sylius_video_poster returns a plain URL, escaped like any other value):

Configuration

Cloudflare Stream

An opt-in type for shops that host their videos on Cloudflare Stream. The file never passes through the shop's PHP: the admin form uploads it from the browser straight to Cloudflare (a direct creator upload over the tus protocol, in 50 MiB chunks, so PHP upload limits do not apply) and only the video's uid is saved. On the product page the video plays through Cloudflare's own Stream Player (an iframe, no JavaScript dependency), with Cloudflare's generated thumbnail as the poster unless one was uploaded; a template override can plug in any other player.

Setup

1. In the Cloudflare dashboard note the account id, create an API token with the Stream: Edit permission, and copy the customer subdomain shown under Stream (customer-<code>.cloudflarestream.com; the code alone is accepted too).

2. Enable the type:

3. Import the plugin's admin route (the endpoint that creates uploads) and Symfony's webhook endpoint, which the symfony/webhook Flex recipe adds as config/routes/webhook.yaml:

4. Add the columns and publish the shop script: bin/console doctrine:migrations:diff (two nullable columns on the video table, cloudflare_stream_uid and cloudflare_stream_ready), doctrine:migrations:migrate and assets:install.

5. Point Cloudflare's webhook at the shop:

   The URL defaults to the application's /webhook/cloudflare_stream endpoint with the host from framework.router.default_uri; pass another URL as the argument to override it. The command is idempotent (a subscription that already points at the URL is left alone; --force subscribes again), so it can simply run on every deploy.

   There is no secret to copy around: Cloudflare returns the signing secret together with the subscription, and the plugin reads it back through the API. It is remembered in cache.app for an hour and read again when a signature stops matching, so re-subscribing needs no restart. Set webhook_secret only if you want to pin the secret in the configuration instead.

   Cloudflare allows one webhook per account. If several environments share an account, only the one subscribed last is notified, so run the command for production only and let the others rely on the sync command below.

How it behaves

• Processing. Cloudflare transcodes after the upload. Until it reports the video ready (readyToStream), the video stays off the product page: the renderer outputs nothing, the plugin's block skips it and setono_sylius_video_ready(video) returns false, so templates that list videos themselves can do the same. The webhook flips the flag the moment Cloudflare is done: it is handled by Symfony's Webhook component — the plugin registers a request parser under the cloudflare_stream type and a remote-event consumer that marks the video ready, so consumption runs through Messenger (synchronously by default; route ConsumeRemoteEventMessage to a transport to process notifications in a worker). Without a reachable webhook, run bin/console setono:sylius-video:cloudflare-stream:sync from cron — it asks Cloudflare about every video that is not ready yet.
• Admin. A row of this type shows a progress bar while uploading, blocks saving until the upload has finished, and afterwards shows the uid and whether the video is ready. Its type is locked once saved like any other; picking a new file on a saved row replaces the video, and the previous one is deleted from Cloudflare after the save, as is the video of a removed row.
• Shop. The default template embeds Cloudflare's Stream Player in an iframe, sized by the plugin's responsive box like the URL type's providers, with the resolved poster passed as the player's poster parameter. To use your own player instead, override templates/bundles/SetonoSyliusVideoPlugin/shop/renderer/cloudflare_stream.html.twig: the context carries player_url, hls_url and dash_url, so a Video.js or hls.js player is a <video> with the HLS (and DASH) manifest as its sources — Safari plays HLS natively, other browsers need the player library, which your shop then loads and mounts itself.
• Security. The upload endpoint sits under the admin prefix, so the admin firewall guards it, and it only answers XMLHttpRequest calls (a cross-site form post cannot add that header). The webhook endpoint is public but the parser refuses any notification whose Webhook-Signature (HMAC-SHA256 of <time>.<body> keyed with the secret) is invalid or older than five minutes. The secret is the configured webhook_secret or, by default, the one read from Cloudflare; while the account has no subscription every notification is refused. Forged notifications cannot burn the API quota: one without a signature costs no API call, and the secret is re-read at most once a minute.

Security

The embed type stores the HTML an administrator pastes and prints it on the product page with |raw, on purpose: provider embed codes need their <iframe> and attributes intact, and a sanitizer would break them. Treat that field as trusted input. Anyone who can edit a product can put arbitrary markup and scripts in front of every visitor of that product page, and Sylius has no admin role finer than "can edit products".

• If the shop does not need pasted embed codes, turn the type off with embed.enabled: false; YouTube, Vimeo and similar providers work through the External URL type, which only ever outputs an escaped src.
• Otherwise, consider a Content Security Policy on the shop with a frame-src allow-list of the providers you use, so a pasted <script> or an unexpected frame host is blocked by the browser.

Overriding

• Models: swap any subtype via the setono_sylius_video.resources.*.classes.model config — the discriminator keys stay stable because they are derived from each model's getType().
• Renderer templates: override at templates/bundles/SetonoSyliusVideoPlugin/shop/renderer/<type>.html.twig; the shop block itself is shop/product/_videos.html.twig and the admin tab admin/product/tab/_videos.html.twig under the same bundle directory.
• Renderers and poster resolvers: both are tagged composites (setono_sylius_video.renderer, setono_sylius_video.poster_resolver) that ask their services in descending priority order and use the first whose supports() returns true. The plugin's renderers run at priority 0 and its stored-poster resolver at 100, so tag a more specific renderer above 0 and a computed poster resolver below 100 if an uploaded poster should keep winning.
• Uploads: decorate the setono_sylius_video.uploader service, or point filesystem.adapter at any Flysystem/Gaufrette adapter Sylius exposes.

Extending — adding a new video type

Worked example: a youtube type that extends the URL type to reuse its url column and accessors, parses the video id from the link, renders YouTube's player and computes its thumbnail from the YouTube CDN. Because it adds no column no migration is needed. The test application ships this exact type under tests/Application (Entity/Video, Form, Renderer, Poster, config/validator, templates/video, translations), so read it as a complete reference.

1. Subtype model + interface — name it <Type>ProductVideo and the static getType() derives the discriminator (YoutubeProductVideo → youtube); override it only for a non-conventional name. Extending a concrete type is fine: the derived name (youtube, not url) keeps the two apart in the discriminator map. Two models resolving to the same type (for example an override of getType() returning url) fail loudly at container build and metadata load, since one would otherwise shadow the other in the map; to replace a built-in type's class rather than add a type, override its resources.*.classes.model instead (see Configuration).

2. ORM mapping — every class in the discriminator map must be known to a mapping driver, even one that adds no column, so always ship a mapping. Declare it as a mapped superclass (Sylius turns the resource into an entity) and map fields only for new columns. With attributes that is a single line on the class:

or, for an XML-mapped entity namespace, <mapped-superclass name="App\Entity\Video\YoutubeProductVideo"/> in config/doctrine/Video.YoutubeProductVideo.orm.xml.

3. Register it as a resource — the plugin scans every Sylius resource whose model implements ProductVideoInterface: the discriminator listener adds it to the STI map and the type selector picks it up (label derived as setono_sylius_video.ui.types.<type>). No plugin config to edit, no listener to decorate:

4. Renderer + poster — implement VideoRendererInterface (instanceof YoutubeProductVideoInterface), tag it setono_sylius_video.renderer with a priority above 0 so it is asked before the plugin's URL renderer (a YouTube video is a URL video too, and the composite picks the first renderer that supports it), and add a template for it. Add a poster resolver that builds the thumbnail from the parsed id and tag it setono_sylius_video.poster_resolver; the plugin's stored-poster resolver runs at priority 100, so an uploaded poster still wins:

5. Form fields — ship a ProductVideoType extension for the type's input(s) by extending AbstractProductVideoTypeExtension and tagging it form.type_extension. Declare the type and its field(s) as a name => [form type, options] map; the base class adds them, reveals/hides them per the selected type and strips them on submit when another type is chosen:

6. Validation + translations — add a per-subtype validation file with its constraints in the sylius group (each row is validated in %setono_sylius_video.form.type.product_video.validation_groups%, [sylius] by default) and the setono_sylius_video.ui.types.youtube label key (plus labels for any fields your extension adds).

Development & quality gates

CI (.github/workflows/build.yaml) enforces more than the composer scripts: vendor/bin/rector process --dry-run, vendor/bin/infection (minCoveredMsi 100, minMsi ratcheted in infection.json.dist), vendor/bin/composer-dependency-analyser, composer validate --strict, composer normalize --dry-run, and lint:yaml, lint:twig and lint:container in the test application. Run them before pushing.

The test application lives in tests/Application. Admin credentials: sylius / sylius.

License

This plugin is released under the MIT License. See the bundled LICENSE file.