Sam Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package. There is no service provider, no config/sam.php, and nothing auto-discovered by Laravel. For a Laravel developer, day-to-day leverage is effectively zero unless you are maintaining a legacy Symfony 2/3-era application that already uses it. Confirm the target app has the old layout (app/config/, app/AppKernel.php) before investing any time.

v0.2 is a maintenance release on an otherwise dormant project (repo archived-ish, 0 dependents, 2 stars; the previous tagged release was December 2018). Nothing in it changes the Laravel verdict — it fixes an asset-build bug and tidies internals. Proceed only if forced.

1. Confirm compatibility before installing. Check constraints first:

   composer require johnkrovitch/sam-bundle --dry-run
   

   If it conflicts on symfony/symfony or PHP version, stop — do not fight the resolver for a 2-star archived bundle.

2. Pin the version deliberately. v0.2 restructured the source tree to PSR-4. If you are matching an existing composer.lock, the class paths and autoload mapping differ from the pre-0.2 layout. Read the PSR-4 mapping in the installed composer.json rather than assuming the namespace matches the vendor/package name.

3. Register the bundle in the legacy kernel (app/AppKernel.php):

   $bundles = [
       // ...
       new Johnkrovitch\SamBundle\SamBundle(),
   ];
   

4. Locate the commands rather than guessing names — the release added/improved commands, so list them:

   bin/console list | grep -i sam
   

5. Write the config under app/config/ (the bundle's stated purpose is reading build config there). Start from whatever example ships in the bundle's Resources/config/ or README, and reduce it to a single entry: one source directory, one output directory under web/.

6. Run the build and verify the artifact, not just the exit code:

   bin/console <sam-command> -vvv
   ls -la web/css web/js
   

First use case: compile one stylesheet/script bundle from your assets directory into web/ and reference it in Twig via {{ asset('css/app.css') }}. That is the entire value proposition — a config-driven asset build command. If you need more than that, use Webpack Encore or Vite instead.

Implementation Patterns

Config-driven, deploy-time builds. The intended workflow is: assets are described declaratively in app/config, and the command is run as a build step rather than during a request. Wire it into your deploy pipeline (Capistrano task, CI job, or a Makefile target) before cache warmup:

assets:
	bin/console <sam-command> --env=prod -vvv
	bin/console cache:clear --env=prod --no-warmup
	bin/console cache:warmup --env=prod

Watch mode is now usable (v0.2). The watch command now performs an initial build when it starts, so you no longer have to run a full build then start watching. It also fixes an infinite build loop that could wedge both the watcher and, if you mistakenly wired it into CI, the pipeline. Use it only for local dev:

watch:
	bin/console <sam-watch-command> -vvv

Keep the watch command out of any deploy or CI target — a non-terminating command in a pipeline is how the pre-0.2 infinite-loop bug used to manifest as a hung build.

Environment-specific configuration. Keep dev config unminified and prod minified by splitting across config_dev.yml / config_prod.yml (or the bundle's own env-aware keys, if it supports them). Because Symfony compiles config into the container, always clear cache after editing. v0.2's added "tests against different environments" only tells you the bundle's own suite covers env switching — it does not mean it understands modern Symfony env handling.

Twig integration with cache busting. If the command emits hashed filenames, do not hardcode them. Either have the command write a manifest and read it from a Twig extension, or keep stable output names and rely on asset()'s version parameter. Hashed filenames without a manifest reader is a common half-implemented setup — check whether the bundle provides one before assuming.

Isolate it behind a wrapper. Because the bundle is effectively unmaintained — v0.2 is a bugfix, not a revival — never call the command directly from a dozen places. Put it behind a single make assets / Composer script target so replacing it later with Encore or Vite is a one-line change:

"scripts": {
    "build:assets": "bin/console <sam-command> --env=prod"
}

Mapping to the Laravel mental model, which is where most of the confusion will come from:

Coexistence pattern. If the legacy app already has Assetic, Encore, or a hand-rolled Grunt/Gulp build, do not run two pipelines over the same output directory. Pick one owner per output path, or you will get nondeterministic deploys where the last writer wins.

Gotchas and Tips

• v0.2 is a patch, not a lifeline. The fixes are real (infinite loop, initial build on watch, PSR-4 layout, broader test environments) but there are still no security patches for Symfony 4/5/6, no Flex support, and no maintainer roadmap. Treat every remaining bug as yours to fix or work around. Budget for replacement, not adoption.
• PSR-4 restructure may break an existing pinned install or your own overrides. If you subclassed the command or overrode templates from app/Resources/, re-check paths and namespaces after bumping to 0.2. When in doubt, diff the installed composer.json autoload block.
• Symfony Flex incompatibility. The bundle expects app/config; modern Symfony uses config/. On a Flex app this bundle will not find its configuration and will either fail or silently build nothing.
• PHP version drift. Code from that era commonly uses constructs removed in PHP 8 (curly-brace string offsets, each(), implicit nullable params). Expect deprecation noise at minimum and fatal errors at worst — the 0.2 test matrix does not extend to PHP 8.
• Config caching bites first. After any YAML change, run cache:clear before debugging "my config is ignored." This is the single most common false alarm with Symfony bundles.
• Verify the exit code and the output. A build command that logs an error but returns 0 will happily ship stale or missing assets. Always assert the expected files exist in CI:

  test -s web/css/app.css || { echo "asset build produced nothing"; exit 1; }
  

• Path resolution is relative to the project root, not web/. Misconfigured output paths silently write into the repo root or app/. Run git status after the first build and confirm nothing unexpected appears.
• Debug by bypassing the bundle. If the underlying tool (sam) can be invoked directly, run it manually with the same inputs. That immediately tells you whether the failure is in the asset tool or in the bundle's command wrapper — especially useful now that the build command itself was reworked in 0.2.
• Use -vvv and check var/logs/ (or var/log/). The command's own output is often terse; the exception trace in the log is where the real cause lives.
• Extension points are limited and unpoliced. You can subclass the command or override templates/config in app/Resources/, but you are patching code nobody will ever merge. Fork it into src/ or vendor it if you must change behavior.
• The correct long-term move for a Laravel developer inheriting this: replace it with Webpack Encore (Symfony-native) or a plain Vite build. The bundle's only real feature — "read a config file and compile assets" — is a ten-line Vite config, and you get a maintained ecosystem, watch mode, and HMR that don't depend on a 0.2 patch release to terminate correctly.