Sensio Distribution Bundle Laravel Package

Getting Started

This is a Symfony package, not a Laravel one — there is no service provider, no config file to publish, and composer require sylius-labs/sensio-distribution-bundle in a Laravel app will just sit inert in vendor/. If you're evaluating it from a Laravel codebase, the honest first step is to confirm you actually have a legacy Symfony Standard Edition project to maintain; otherwise stop here.

If you do have one:

composer require --dev sylius-labs/sensio-distribution-bundle

Then register it in app/AppKernel.php:

$bundles = [
    // ...
    new Sensio\Bundle\DistributionBundle\SensioDistributionBundle(),
];

Where to look first:

1. vendor/sylius-labs/sensio-distribution-bundle/Composer/ScriptHandler.php — this is the entire reason the package exists. Every method you'll call from composer.json lives here.
2. vendor/sylius-labs/sensio-distribution-bundle/Command/ — cache:clear, assets:install, cache:warmup wrappers that predate their Symfony core equivalents.
3. Your app's composer.json scripts block — that's where the real integration happens.

First use case: wiring build-time automation into composer install/update so a deployment clears cache and installs assets without a manual app/console step.

"scripts": {
    "post-install-cmd": [
        "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::buildBootstrap",
        "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::clearCache",
        "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::installAssets"
    ],
    "post-update-cmd": [
        "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::buildBootstrap",
        "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::clearCache",
        "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::installAssets"
    ]
}

Implementation Patterns

Standard deploy pipeline. The canonical workflow is a four-step script chain: buildBootstrap (writes app/bootstrap.php.cache), installAssets (symlink or copy bundle web assets into web/bundles), clearCache (drops app/cache/{env}), installRequirements (optional interactive check for parameters.yml completeness). Put the first three in both post-install-cmd and post-update-cmd; they're idempotent.

Environment-aware cache clearing. ScriptHandler::clearCache accepts an event and reads --env / --no-dev from the Composer IO. To build a production cache during a --no-dev install, pass the env explicitly:

composer install --no-dev --env=prod

and the handler will clear prod rather than dev. This is the single most common way to get a stale cache after deploy.

Custom distribution bundle. If you maintain your own Standard Edition fork, subclass the bundle so you can add your own Composer handlers and console commands without duplicating the base:

namespace Acme\DistributionBundle;

use Symfony\Component\HttpKernel\Bundle\Bundle;

class AcmeDistributionBundle extends Bundle
{
    public function getParent()
    {
        return 'SensioDistributionBundle';
    }
}

Override getParent() rather than copy-pasting — everything in Command/ and Composer/ is then inherited.

Parameters bootstrapping. The package's installRequirements/buildBootstrap cycle pairs with a checked-in app/config/parameters.yml.dist. Treat the .dist file as your contract: the handler diffs the local parameters.yml against it and prompts for missing keys. Keep parameters.yml in .gitignore and let the handler generate it on first install.

CI integration. In a build container, skip the interactive requirement check and run the non-interactive path:

composer install --no-interaction --no-dev --optimize-autoloader
app/console cache:warmup --env=prod

The Composer handlers fire automatically; you only need the explicit cache:warmup if you're not using the clearCache handler.

Asset strategy. installAssets defaults to symlinks (--symlink). On deploy targets where symlinks break (some shared hosting, Docker layers copied across stages), pass --copy via extra.symfony-assets-install in composer.json:

"extra": {
    "symfony-assets-install": "copy"
}

Gotchas and Tips

This package is abandoned. Last release 2019-03-04. It was superseded by Symfony Flex and is not compatible with Symfony 4+. Do not start new work on it; only touch it to maintain an existing Standard Edition project, and plan migration to Flex as the exit path. Its 12 stars and 0 dependents on the mirror you're reading are a signal that the ecosystem has already moved on.

app/console vs bin/console. The bundled commands assume the pre-Symfony-3 directory layout (app/console, app/cache, web/). If your project has been partially migrated to bin/console, the handlers will fail with "Could not find console" — there is no config knob to redirect them. Either keep the legacy path or stop using the handlers and call the core Symfony commands directly.

Method names drifted between versions. Older 3.x/4.x releases exposed ScriptHandler::build and ScriptHandler::installAssets; later 5.x renamed build to buildBootstrap. If you copy a composer.json scripts block from a blog post and get Call to undefined method, check the version in composer.lock and read ScriptHandler.php for the actual method list.

Cache clear during install can wipe a warming cache. If you run composer install while a deploy script is simultaneously warming the cache, clearCache will delete directories mid-warmup and you'll get partial caches (missing annotations.php, truncated container). Serialize your deploy steps: install → clear → warm, never parallel.

Permissions. buildBootstrap writes app/bootstrap.php.cache to the project root, and clearCache removes app/cache/*. In Docker or CI running as a non-owner user, these fail silently or with a terse RuntimeException. Ensure the invoking user owns both paths, or run Composer as the same user as the web server.

parameters.yml.dist drift causes prompt hangs. installRequirements prompts interactively when parameters.yml is missing keys. In CI without --no-interaction this hangs the build until timeout. Always pass --no-interaction in automation, and validate parameters.yml.dist in a pre-commit hook so drift is caught locally.

No Laravel analogue. Everything here maps to Laravel's php artisan package:discover / optimize:clear / vendor:publish workflow, but none of it is reusable — the classes are Symfony Bundle and Command subclasses. If your goal was to learn patterns for a Laravel deployment pipeline, read ScriptHandler.php as a case study in Composer script hooks, then implement the equivalent with @php artisan script entries in composer.json. Don't try to install this package.

Extension point if you must customize. The only clean extension point is subclassing SensioDistributionBundle and overriding getParent(), plus registering your own ScriptHandler classes under your namespace and calling those from composer.json instead of the vendor FQCNs. That survives a composer update; editing files under vendor/ does not.