Installer Bundle Laravel Package

Getting Started

You almost certainly do not composer require this. It ships as part of sylius/sylius and is already registered via the Sylius Kernel/bundle list in any standard Sylius app. Your first task is confirming what's actually wired up on the checkout you've been handed:

bin/console list sylius:install
# sylius:install                    # umbrella: runs every step in order
# sylius:install:check-requirements # environment gate only
# sylius:install:database           # create DB, schema, (sometimes) fixtures
# sylius:install:setup              # interactive: admin user, locale, currency, etc.
# sylius:install:sample-data        # load Sylius fixtures
# sylius:install:assets             # copy/publish bundle assets

First use case is exactly one thing: a fresh clone on a new machine, ending in a browsable storefront.

APP_ENV=dev bin/console sylius:install

It prompts its way through requirements → database → setup (admin credentials, locale, currency, sample data y/n) → assets. Treat that as a one-time ceremony. Everything after day one is the granular subcommands, because you want them in scripts, not in your terminal history.

Where to look first when it misbehaves:

• Command/InstallCommand.php — the orchestration. It tells you the real order, which subcommands run, and what gets skipped.
• Command/CheckRequirementsCommand.php plus the requirement-checker services — source of ~80% of "the install won't start" complaints.
• InstallerEvents (and the InstallerEvent object) — the event constants you subscribe to for custom provisioning.
• The bundle's Resources/config/services.* and any compiler pass — the DI tags that collect requirement checkers and install/setup steps. This is where you learn how to add your own step without forking.

One thing to get straight up front for a Laravel team: this does not install into a Laravel app. Its dependency graph and container registrations assume the Symfony kernel and Sylius core services. Your first read of the source should be as a specification for a native php artisan app:install — requirement gates, ordered idempotent steps, interactive prompts — not as something you'll vendor.

Implementation Patterns

Umbrella once, granular forever. The realistic pattern is: sylius:install on a brand-new checkout, then never again. Compose the subcommands into whatever your team already runs:

{
  "scripts": {
    "app:db": "bin/console doctrine:database:create --if-not-exists && bin/console doctrine:migrations:migrate -n",
    "app:setup": "bin/console sylius:install:setup",
    "app:sample": "bin/console sylius:install:sample-data",
    "app:assets": "bin/console sylius:install:assets",
    "app:install": [
      "@app:db",
      "@app:setup",
      "@app:sample",
      "@app:assets",
      "bin/console cache:clear"
    ]
  }
}

Note that after the first install you use migrations, not sylius:install:database. The installer creates schema; migrations evolve it. Mixing the two on an existing database is how people lose an afternoon.

Requirement checks as a CI gate. sylius:install:check-requirements is cheap and has a meaningful exit code. Run it as the first step of a build job so container-image regressions (missing ext-intl, non-writable var/cache, wrong PHP version) fail in ten seconds instead of forty minutes into a fixture load.

Custom provisioning as a setup step. The extension point people actually want is "after the stock installer finishes, do my thing" — create a super-admin API user, seed a default channel and taxonomy, warm the search index, import a brand's product feed. Two viable shapes:

1. Subscribe to InstallerEvents::INSTALLATION_START / INSTALLATION_END (and the per-step events, if present in your version) and run your logic there. Least invasive; keeps you upgrade-safe.
2. Register your own service implementing the bundle/core setup interface and tag it so the installer's collector picks it up, making it appear as a first-class step in the interactive flow. Better UX; slightly more coupled to the tag name, so verify it against the compiler pass in your pinned version before committing.

Ephemeral demo environments. Install → sample data → mysqldump the result. From then on, per-branch and per-prospect sandboxes are "restore the dump", which is minutes instead of a fixture load. This is the highest-value use of the bundle for an agency or sales-engineering context, and it's the one that doesn't require you to touch the installer again.

The Laravel-side mirror (what you should actually build). If the appeal is the flow, port the flow. A native equivalent is a few days of work:

• A config/install.php checklist of requirement closures, each returning pass/fail with a message; a app:install:check Artisan command that iterates them and exits non-zero on failure.
• An app:install command that runs ordered steps, each idempotent, each recording completion in an install_steps table so a failed run resumes rather than restarts.
• Laravel Prompts for the interactive layer, with --no-interaction honoring env vars — same CLI/web parity idea, one shared service layer behind both.
• Never make step one "drop the database".

That is the reusable asset here. The PHP code is not.

Gotchas and Tips

Do not attempt in-process use from Laravel. Composer will fight you over Symfony component versions pinned by the framework, and even a resolved graph registers services referencing Sylius classes that don't exist in the Illuminate container. If you genuinely need Sylius, it is a separate service with its own composer.json, lockfile, CI job, and database — never a shared vendor/. Record the rejection with a one-line rationale so it isn't re-proposed next quarter.

install:database is destructive-adjacent. It creates the database and schema and in some versions offers to drop existing schema. It is for empty databases only. Never wire the umbrella sylius:install into a container entrypoint or a deploy hook that can run against a populated environment — that's an on-call incident waiting for a deploy window.

Interactive prompts will hang your CI. Anything without full option coverage blocks on stdin. Either pass --no-interaction with the environment fully configured (DATABASE_URL, APP_ENV, admin credentials via env/parameters), or drive it from a Symfony\Component\Process\Process with explicit setInput(). Budget time for this — the prompt set differs between Sylius majors.

Requirements pass locally, fail in the container. The classic trio: var/cache and var/log not writable by the runtime user, a missing extension (intl, fileinfo, pdo_*), and memory_limit too low for fixture loading. The checker's messages are decent — read them literally rather than assuming a Sylius bug. In Docker, fix ownership in the image build, not with a runtime chmod -R 777.

Sample data is the slow part. Large fixture sets are memory- and time-hungry and occasionally time out mid-load, leaving a half-populated database with no rollback. For CI, skip sample data entirely and build only what the test needs. For demos, load once and snapshot the dump.

Re-running against a populated environment is undefined behavior in practice. Admin creation, locale/currency setup, and fixture loading are not designed to be safely re-entrant. If you need a reset, drop, recreate, reinstall — and only in dev/test.

Disable the web side in production. The web installer is a setup-time convenience, not a provisioning system and not a security boundary. Routes and any associated firewall entries should be absent or blocked outside dev/staging. Search the routing config for the installer routes and confirm they're not reachable on the public host.

Version coupling is real. The bundle tracks Sylius majors and is a read-only split of the monorepo. Pin it in lockstep with the platform version; upgrade them as one unit. Ignore the zero-star / zero-dependent signals on the split repo — they're artifacts of the monorepo split workflow. Verify cadence and support commitments against the main sylius/sylius repository, not this one.

Extend by decorating, not forking. Decorate the installer or your setup-step service, or subscribe to InstallerEvents. Forks of a package released in lockstep with the platform turn every Sylius upgrade into a merge exercise.

Debugging a stuck install: -vvv first, then check for a subscriber on the installer events that's swallowing an exception, then confirm the service tags on your custom step were actually collected (dump the container definitions and grep the tag name from the compiler pass). Nine times out of ten it's a step that threw and a front-end that didn't surface it.