Compass Elephant Bundle Laravel Package

Getting Started

Read this first: notrix/compass-elephant-bundle is a Symfony2 bundle, not a Laravel package. It has zero stars, zero dependents, and no active maintainers. Do not expect it to install into a Laravel app — the requirements (symfony/symfony ~2.x, Assetic, AppKernel) will conflict with Laravel. Treat this as reference material for a legacy Symfony2 project only.

Minimal steps for a Symfony2 project:

1. Confirm prerequisites outside PHP. Compass is a Ruby gem. You need ruby, gem install compass, and a working config.rb. The bundle only shells out to compass; it does not bundle the Ruby toolchain.
2. Install: composer require notrix/compass-elephant-bundle:dev-master (there are no tagged releases).
3. Register the bundle in app/AppKernel.php:

   new Notrix\CompassElephantBundle\NotrixCompassElephantBundle(),
   

4. Configure in app/config/config.yml — at minimum a project name, a config.rb path, and an output directory that your web server can serve.
5. First use case: point the bundle at a trivial config.rb with a single main.scss in sass/, run the compile command provided by the bundle, and verify web/css/main.css is created. If that works, you can incrementally move real stylesheets over.

The first place to look in the repo is the bundle's DependencyInjection/Configuration.php — that is the schema for what you can actually configure. Second is the console command class; that is where the compass invocation happens and where you will be reading errors.

Implementation Patterns

Compile-on-demand in development. Wire the bundle's compile command into your dev workflow (a Makefile target, a composer script, or a Symfony command alias). Do not put it in a kernel.request listener — Compass is slow (seconds per compile) and would tank page loads.

Compile-as-a-deploy-step in production. Never run Compass at request time in prod. Run it once during deploy, then serve the static CSS from web/css. Treat the compiled output as a build artifact and gitignore it.

Assetic integration. If you are already on Assetic, the natural pattern is to let the bundle produce the CSS and reference it via Twig asset('css/main.css') (or Assetic's assetic:dump step), rather than trying to use Assetic's own compass filter — mixing the two usually leads to double-compiles and stale fingerprints.

Multi-project / multi-theme layout. Configure one entry per config.rb (e.g. frontend, admin, emails). Keep each project's config.rb self-contained with its own sass_dir and css_dir; the bundle does not resolve cross-project imports for you.

Compose with the asset pipeline explicitly. The clean pattern is:

composer install → compass compile (via bundle) → assetic:dump → clear Symfony cache → deploy

Keep these as discrete, idempotent steps so a failed Compass run does not silently ship stale CSS.

Gotchas and Tips

• Abandonment risk is the headline. Zero stars, zero dependents, no releases. Pin the exact commit hash in composer.json and be prepared to fork. Assume you will replace this bundle within a year, and isolate the compile step behind a Makefile target so the migration is a one-line swap.
• Ruby toolchain drift is your real enemy. Modern Compass/SASS gems are end-of-life; Node-based sass/dart-sass has superseded them. If you are starting fresh, skip this bundle entirely and use a Node build (Webpack Encore or plain sass CLI). Use this bundle only when the existing asset setup is already Compass-based.
• Path resolution is the number-one failure mode. config.rb's sass_dir/css_dir are resolved relative to where compass is invoked from, not relative to config.rb or the Symfony kernel. Pass absolute paths in the bundle config and verify the working directory of the process.
• Silent no-ops. Shelling out to compass can return exit code 0 while producing nothing (e.g. empty sass_dir, wrong project name). Always assert the expected output file exists and its mtime changed after a compile.
• --trace for debugging. When a compile fails with a one-line Compass::Error, you need compass compile --trace to see the real backtrace. Check whether the bundle exposes an option to pass extra CLI flags; if not, you will be forking to add one.
• Cache invalidation. Symfony caches config; changing config.yml without app/console cache:clear will leave you debugging phantom behavior. Do the cache:clear first when something "doesn't make sense."
• File permissions. Compass runs as the Symfony user (often www-data under FPM, but your cron/deploy user under CLI). Mixed ownership on web/css causes intermittent "cannot write" failures that are painful to diagnose from a browser test alone.
• No Laravel path. There is no service provider, no facade, no config publishing. If you are coming from Laravel's elixir/vite/mix ecosystem, the closest equivalent here is a manual Process::run('compass compile') in a deploy script — which, honestly, is simpler than depending on this bundle.

Extension points: fork the console command (it is the integration seam), and keep a thin adapter class around compilation so you can swap Compass for dart-sass later without touching Symfony config.