setono / sylius-cms-plugin
CMS plugin for your Sylius store
Package info
github.com/Setono/SyliusCMSPlugin
Type:sylius-plugin
pkg:composer/setono/sylius-cms-plugin
Requires
- php: >=8.1
- ext-json: *
- doctrine/collections: ^1.6
- doctrine/dbal: ^2.13 || ^3.0
- doctrine/persistence: ^2.2 || ^3.0
- fakerphp/faker: ^1.21
- knplabs/gaufrette: ^0.8 || ^0.9 || 0.10 || ^0.11
- knplabs/knp-gaufrette-bundle: ^0.7 || ^0.8
- knplabs/knp-menu: ^3.3
- liip/imagine-bundle: ^2.6
- psr/cache: ^1.0 || ^2.0 || ^3.0
- psr/event-dispatcher: ^1.0
- psr/log: ^1.1 || ^2.0 || ^3.0
- setono/composite-compiler-pass: ^1.1
- setono/editorjs-bundle: ^1.2
- setono/editorjs-php: ^1.2
- setono/twig-cache-purger-bundle: ^1.0
- stof/doctrine-extensions-bundle: ^1.7
- sylius/channel: ^1.0
- sylius/channel-bundle: ^1.0
- sylius/core: ^1.0
- sylius/core-bundle: ^1.0
- sylius/locale: ^1.0
- sylius/resource-bundle: ^1.8
- sylius/ui-bundle: ^1.8
- symfony/config: ^5.4 || ^6.4 || ^7.0
- symfony/dependency-injection: ^5.4 || ^6.4 || ^7.0
- symfony/event-dispatcher: ^5.4 || ^6.4 || ^7.0
- symfony/event-dispatcher-contracts: ^2.5 || ^3.1
- symfony/form: ^5.4 || ^6.4 || ^7.0
- symfony/http-foundation: ^5.4 || ^6.4 || ^7.0
- symfony/http-kernel: ^5.4 || ^6.4 || ^7.0
- symfony/options-resolver: ^5.4 || ^6.4 || ^7.0
- symfony/property-access: ^5.4 || ^6.4 || ^7.0
- symfony/routing: ^5.4 || ^6.4 || ^7.0
- symfony/security-core: ^5.4 || ^6.4 || ^7.0
- symfony/string: ^5.4 || ^6.4 || ^7.0
- symfony/uid: ^5.4 || ^6.4 || ^7.0
- twig/twig: ^2.15 || ^3.4
- webmozart/assert: ^1.11
Requires (Dev)
- api-platform/core: ^2.7.18
- babdev/pagerfanta-bundle: ^3.8
- behat/behat: ^3.15
- doctrine/doctrine-bundle: ^2.11
- infection/infection: ^0.27.11
- jms/serializer-bundle: ^4.2
- lexik/jwt-authentication-bundle: ^2.17
- matthiasnoback/symfony-config-test: ^4.3 || ^5.2
- matthiasnoback/symfony-dependency-injection-test: ^4.3 || ^5.1
- phpspec/prophecy-phpunit: ^2.2
- phpunit/phpunit: ^9.6
- psalm/plugin-phpunit: ^0.18.4
- psalm/plugin-symfony: ^5.1
- setono/code-quality-pack: ^2.8.3
- shipmonk/composer-dependency-analyser: ^1.7
- sylius/sylius: ~1.12.19
- symfony/debug-bundle: ^5.4 || ^6.4 || ^7.0
- symfony/dotenv: ^5.4 || ^6.4 || ^7.0
- symfony/intl: ^5.4 || ^6.4 || ^7.0
- symfony/property-info: ^5.4 || ^6.4 || ^7.0
- symfony/serializer: ^5.4 || ^6.4 || ^7.0
- symfony/web-profiler-bundle: ^5.4 || ^6.4 || ^7.0
- symfony/webpack-encore-bundle: ^1.17.2
- weirdan/doctrine-psalm-plugin: ^2.9
- willdurand/negotiation: ^3.1
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- 2.x-dev
- 1.x-dev
- v1.0.0-beta
- v1.0.0-alpha.5
- v1.0.0-alpha.4
- v1.0.0-alpha.3
- v1.0.0-alpha.2
- v1.0.0-alpha
- 0.8.x-dev
- v0.8.3
- v0.8.2
- v0.8.1
- v0.8.0
- v0.7.0
- v0.6.3
- v0.6.2
- v0.6.1
- v0.6.0
- v0.5.1
- v0.5.0
- v0.4.0
- v0.3.2
- v0.3.1
- v0.3.0
- v0.2.1
- v0.2.0
- v0.1.2
- v0.1.1
- v0.1.0
- dev-prototype/admin-information-architecture
- dev-research/api-readiness
- dev-research/cms-caching
- dev-research/root-level-routing
- dev-research/ux-image
- dev-research/sylius-1-14-constraints
- dev-research/editor-technology
- dev-research/cms-content-modeling
- dev-research/sylius-cms-plugins
- dev-research/cms-editing-ux
- dev-refactor-carousel
- dev-tags
- dev-navigation
This package is auto-updated.
Last update: 2026-11-19 11:25:14 UTC
README
A CMS for Sylius stores. Developers define what content can look like in code, and merchants compose, publish and place content in the Sylius admin.
v2 is a rebuild from scratch for Sylius 1.14, developed on the 2.x branch.
- The specification is the source of truth for what v2 does.
- The glossary defines the words the specification and the code use.
- The architecture decision records explain the hard-to-reverse calls.
v1 lives on the 1.x branch. v2 is a clean break, and there is
no migration from v1.
Requirements
- Sylius 1.14, on Symfony 6.4
- PHP 8.2 or newer, with the
dom,filter,libxml,mbstringandzipextensions - MySQL 8.0 or newer, or PostgreSQL
- A Symfony Messenger worker, which a Sylius shop already needs for its catalog promotions (below)
The builder ships prebuilt, so the shop needs no Node, Encore or Symfony UX for it.
Installation
These steps start from a Sylius 1.14 shop made from Sylius-Standard. Everything else the plugin needs, such as LiipImagine, Flysystem and Messenger, is already there.
1. Require the package
composer require setono/sylius-cms-plugin
Until 2.0 is tagged, require the branch: composer require setono/sylius-cms-plugin:2.x-dev.
2. Register the bundle
Add the bundle to config/bundles.php, before SyliusGridBundle:
return [ // ... Sylius\Bundle\ResourceBundle\SyliusResourceBundle::class => ['all' => true], Setono\SyliusCMSPlugin\SetonoSyliusCMSPlugin::class => ['all' => true], Sylius\Bundle\GridBundle\SyliusGridBundle::class => ['all' => true], // ... ];
The plugin adds the grids of its entry lists to SyliusGridBundle's config. Registered after it, the container fails to
build with You have requested a non-existent parameter "setono_sylius_cms.model.entry.class".
3. Import the routes
Create config/routes/setono_sylius_cms.yaml with the plugin's three route files:
setono_sylius_cms_admin: resource: '@SetonoSyliusCMSPlugin/Resources/config/routes/admin.php' prefix: '/%sylius_admin.path_name%' setono_sylius_cms_media: resource: '@SetonoSyliusCMSPlugin/Resources/config/routes/media.php' setono_sylius_cms_shop: resource: '@SetonoSyliusCMSPlugin/Resources/config/routes/shop.php' prefix: /{_locale} requirements: _locale: ^[A-Za-z]{2,4}(_([A-Za-z]{4}|[0-9]{3}))?(_([A-Za-z]{2}|[0-9]{3}))?$
- The admin goes under Sylius's admin prefix, so it sits behind the admin firewall, also on a shop that renamed the
admin path with
SYLIUS_ADMIN_ROUTING_PATH_NAME. - The media routes have no prefix. They give documents and videos their permanent URLs,
/media/{uuid}/{filename}. - The shop routes go under the same locale prefix and requirement as
sylius_shop. An entry's URL is matched after every other route, so the plugin never takes a URL from Sylius or another plugin.
Keep LiipImagine's routes imported, as Sylius-Standard does in config/routes/liip_imagine.yaml: image variants are made
through them.
4. Configure it, if you need to
The plugin works without any config of its own. Its defaults, and every key a project can set, are in the
configuration reference, and bin/console config:dump-reference setono_sylius_cms
prints them. A project adds what it changes to config/packages/setono_sylius_cms.yaml, for example:
setono_sylius_cms: fallback_locales: de_CH: [de_DE] content_types: blog_post: prefix: 'news'
The plugin adds what it needs to the config of other bundles itself: its Flysystem storage, its LiipImagine filter sets, its Messenger routing, its grids and its blocks on Sylius's template events. A project overrides any of it in its own config.
5. Create the database tables
The plugin ships no Doctrine migrations, because a project's own content types add columns to the plugin's tables. Generate a migration and run it:
bin/console doctrine:migrations:diff bin/console doctrine:migrations:migrate
Do the same after every upgrade of the plugin, and whenever you add or change a content type, and review what the migration does before you run it.
6. Install the assets
bin/console assets:install
This copies the prebuilt builder, the shop's stylesheet and carousel script, and the admin's scripts to
public/bundles/setonosyliuscmsplugin. Run it on every deploy, as a Sylius deploy already does.
7. Keep the media storage
Media items are stored in the plugin's own Flysystem storage, setono_sylius_cms.storage. By default it's the local
directory public/media/cms, which the web server serves at /media/cms, beside Sylius's own public/media/image.
- It holds the only copy of every file, so keep
public/media/cmsacross deploys, such as in a deploy tool's shared directories or on a persistent volume, as you keeppublic/media/image. The image variants are cached underpublic/media/cms/cache. - The Messenger worker needs the same storage as the web servers, because an import stores media files in it. On one server that's the same directory. With several servers, or a worker on another one, put the storage somewhere they share, such as S3.
Exports uploaded for an import in the admin wait for the worker in a storage of their own, setono_sylius_cms.transfer_storage,
which is the private local directory private/cms, outside the web root, so the web server never serves them. Each is
deleted once its import finishes, fails or is cancelled, or after a day without being confirmed. Keep private/cms
across deploys, as Sylius's plugins keep their private files, or an import waiting during a deploy loses its zip. The
worker reads the zips from there, so it must run on the same server. A worker on another server needs a storage both
share: define one in your flysystem config, written private, and name it in setono_sylius_cms.transfer.storage:
setono_sylius_cms: transfer: storage: 'app.cms_transfer_storage'
To store media elsewhere, define a Flysystem storage in your own flysystem config, name it in
setono_sylius_cms.media.storage, and point Setono\SyliusCMSPlugin\Media\MediaUrlGeneratorInterface at a service
that builds the storage's public URLs. The shipped MediaUrlGenerator takes a base URL:
# config/packages/setono_sylius_cms.yaml flysystem: storages: app.cms_storage: adapter: 'aws' # league/flysystem-aws-s3-v3 options: client: 'app.s3_client' # your Aws\S3\S3Client service bucket: '%env(CMS_BUCKET)%' prefix: 'cms' setono_sylius_cms: media: storage: 'app.cms_storage' services: Setono\SyliusCMSPlugin\Media\MediaUrlGeneratorInterface: class: Setono\SyliusCMSPlugin\Media\MediaUrlGenerator arguments: ['https://%env(CMS_BUCKET)%.s3.amazonaws.com/cms']
The plugin's LiipImagine loader and resolver read and write through the storage, so image variants follow it. On a storage other than the default, each variant gets LiipImagine's signed runtime URL, which makes it on its first request. See Image processing.
8. Load demo content, if you want to
The Sylius fixture setono_cms_import imports an export folder or zip, and publishes what it imported. Add it to a
fixtures suite in config/packages/sylius_fixtures.yaml:
sylius_fixtures: suites: default: fixtures: setono_cms_import: options: path: '%kernel.project_dir%/fixtures/cms'
Make the export with bin/console setono:cms:export fixtures/cms --all in a shop that has the content, or from the
admin's Transfer screen.
Then sign in to the admin: Content is a new item in its main menu.
Running it
Run a Messenger worker
The plugin sends its background work to Sylius's main Messenger transport, the one Sylius schedules its catalog
promotions on. A shop that runs a worker for Sylius already has one:
bin/console messenger:consume main
Sylius's own messages also use the catalog_promotion_removal transport, so a Sylius shop usually consumes both. Run
the worker under a process manager such as Supervisor or systemd, and stop it on every deploy with
bin/console messenger:stop-workers, so it restarts on the new code.
These are the plugin's messages, all dispatched on sylius.event_bus:
| Message | Does | Delayed |
|---|---|---|
Setono\SyliusCMSPlugin\Publishing\ScheduledPublishDue |
Runs a scheduled publish | until the publish's time |
Setono\SyliusCMSPlugin\Media\DeleteReplacedFile |
Deletes a replaced media file and its variants | by media.grace_period, one day by default |
Setono\SyliusCMSPlugin\Transfer\Import\RunImport |
Checks, or runs, an import started in the admin | no |
Setono\SyliusCMSPlugin\Transfer\Import\AbandonImport |
Abandons an uploaded import no one confirmed, and deletes its zip | one day |
- The transport must be asynchronous and support delays. Sylius's default,
doctrine://default, does, as do Redis and AMQP. Onsync://a scheduled publish would publish at once, and an uploaded import would be abandoned before anyone confirmed it. Set the DSN inSYLIUS_MESSENGER_TRANSPORT_MAIN_DSN. - The plugin routes them in its own config. To send them elsewhere, route them in your own
framework.messenger.routing. - The worker needs the same media and transfer storages as the web servers (above), the
zipextension, and room in PHP's temporary directory for a copy of an uploaded zip and of each media file it checks. - Without a worker, scheduled publishes don't run, and the admin warns about each one five minutes after its time. Imports started in the admin wait, and replaced files are never deleted.
- A message that keeps failing ends in Sylius's
main_failedtransport, wherebin/console messenger:failed:showlists it. An import whose run kept failing shows the error on its page, and its zip is deleted.
Every upload in the admin, a media file or an export to import, is capped by PHP's upload_max_filesize and
post_max_size, and a media file also by setono_sylius_cms.media.max_upload_size when you set it. Import a bigger
export with bin/console setono:cms:import. An import, on the CLI, in the fixture or on the worker, checks each media
file in the export against media.max_upload_size alone, since it doesn't upload them through PHP: the CLI's own
upload_max_filesize doesn't apply, and without a configured limit a file of any size is imported.
Run the cron commands
| Command | When | Does |
|---|---|---|
bin/console setono:cms:bestsellers:compute |
Nightly, for example | Recomputes the bestseller scores of every channel, or of one with --channel=CODE. Until it first runs, every Bestsellers list is empty. |
bin/console setono:cms:revisions:prune |
Daily, for example | Deletes each entry's revisions beyond the newest revisions.keep, 50 by default. |
Check routes at deploy and in CI
bin/console setono:cms:check-routes
An entry's URL is matched after every other route, so a route added later, by your code or a plugin, silently takes the URL of an entry published before it. The command lists every entry URL another route now matches, with its channel, locale and route, and exits non-zero when it finds any. Run it at every deploy, after the new code is in place, and in CI. It also updates the problem counts the admin shows for those URLs.
A deploy of a shop with the plugin then runs, besides what Sylius needs:
bin/console doctrine:migrations:migrate --no-interaction bin/console assets:install bin/console setono:cms:check-routes bin/console messenger:stop-workers
Other commands
| Command | Does |
|---|---|
setono:cms:export <dir> and setono:cms:import <path> |
Move content between environments (Transfer). setono:cms:import --dry-run exits with the code the import would, for CI and deploys. |
setono:cms:preset:validate |
Validates the code preset files of every registered directory, and exits non-zero on an error. Run it in CI when the project has code presets of its own. |
setono:cms:preset:export <preset> <dir> |
Writes an editor preset to a code preset file. |
setono:cms:upgrade [--dry-run] |
Runs the upgraders over all stored content and writes it back. Upgraders also run whenever stored content is read, so this is optional. |
setono:cms:lint |
Reports stored values that don't fit their field type, blocks of unknown types and broken references. Exits non-zero on any. Run it in CI or after a deploy that changes block types. |
Extending
Developers add their own building blocks as PHP classes registered by attribute. Each guide is short, with code that works:
- Block types
- Layouts
- Content types
- Sources
- Condition kinds
- Bindable properties
- Link targets
- Field types and their field controls
- Styling
- Overriding templates
- Switching off what ships
The full contract is in Extending.
Caching
v2.0 caches nothing it renders (ADR 0021). A shop that wants to save the queries behind its slots and entry URLs can add a cache: Caching placements and URL lookups.
Development
The plugin is developed against the Sylius test application in tests/Application. The tests run on MySQL 8.0. Set
DATABASE_URL in tests/Application/.env.local or tests/Application/.env.test.local to point it at your database.
composer install (cd tests/Application && yarn install && yarn build) (cd tests/Application && bin/console assets:install) (cd tests/Application && bin/console doctrine:database:create) (cd tests/Application && bin/console doctrine:schema:update --force --complete) # The data the functional and UI suites run against. Every test is rolled back to it (cd tests/Application && APP_ENV=test bin/console sylius:fixtures:load test --no-interaction)
The tests come in three PHPUnit suites:
vendor/bin/phpunit --testsuite unit vendor/bin/phpunit --testsuite functional # needs the database, the test fixtures and built assets vendor/bin/phpunit --testsuite ui # also needs a browser: vendor/bin/playwright-install chromium
The builder is a React and TypeScript app in assets/builder. Its compiled assets in src/Resources/public/builder
are committed, so projects that install the plugin need no Node. After changing it, build it and commit the result:
npm ci
npm test
npm run build