Front Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package — there is no service provider, no php artisan, and no config/front.php. If you're coming from Laravel, map it mentally to a Symfony bundle that wraps a gulp-based asset pipeline.

Minimal steps to get it running:

1. Install via Composer in a Symfony app:

   composer require planmylife/front-bundle
   

2. Register the bundle — config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 2/3):

   PlanMyLife\FrontBundle\PlanMyLifeFrontBundle::class => ['all' => true],
   

3. Inspect what the bundle ships before writing any config. At a minimum you're looking for:
   • DependencyInjection/Configuration.php — the real config keys and defaults
   • Resources/ — the bundled gulpfile.js, package.json, and any Twig/asset templates
   • Command/ — console commands the bundle registers for running gulp tasks
4. Install Node dependencies using the shipped package.json (copy it to your project root if the bundle expects it there):

   npm install
   

5. Run the bundle's console command to confirm the pipeline works end-to-end:

   php bin/console list planmylife
   php bin/console <task-command>
   

Where to look first: the bundle's Command/ directory and Resources/ tree. That tells you exactly which gulp tasks are exposed, where sources are expected, and where compiled assets land — the three things you actually need to operate it day-to-day.

First real use case: replacing Assetic or ad-hoc shell scripts with a declarative gulp build. Configure source/output paths, run the watch command during development, run the build command for production deploys. Treat it as a thin Symfony-to-gulp bridge, not a full asset management system.

Implementation Patterns

Configuration in the app config. Define source and destination paths once, in config/packages/plan_my_life_front.yaml (or config.yml on older Symfony). Use %kernel.project_dir% so paths stay portable:

plan_my_life_front:
    source_dir: '%kernel.project_dir%/assets'
    build_dir:  '%kernel.project_dir%/public/build'
    # confirm the actual keys against the bundle's Configuration.php

Environment split: watch in dev, build in prod. The whole point of a gulp wrapper is that the two modes differ. Wire them into your scripts and deploy pipeline rather than calling node by hand:

• Development: run the bundle's watch command in a second terminal (or a docker-compose sidecar / Procfile entry).
• CI/production: run the one-shot build command as a deploy step, before cache warmup, so the compiled assets exist when Twig renders.

Console command wrapping beats direct gulp calls. Route all invocations through bin/console commands the bundle registers. Benefits: correct working directory, access to Symfony config for paths, and one consistent entry point for CI scripts and Makefiles.

Twig asset consumption. The bundle builds files; it generally does not replace Symfony's asset() helper. Point framework.assets / your web root at the configured build directory, then reference output normally:

<link rel="stylesheet" href="{{ asset('build/app.css') }}">

Template/gulpfile override pattern. Symfony bundles are overridable. If the shipped gulpfile.js doesn't fit your needs, copy it into your project root and let the project-level file take precedence — this is the standard Symfony extension point and the safest way to add tasks (SASS, PostCSS, image optimization) without forking the bundle.

Deploy pipeline order. npm install → bundle build command → Symfony cache clear/warmup → asset publish. Getting the order wrong means Twig references files that don't exist yet.

Gotchas and Tips

• Abandonment risk is the headline. Zero stars, zero dependents, score 0. Treat this as unmaintained until proven otherwise: check the repo's last commit date and open issues before committing. Pin the version in composer.json and document a migration path to Webpack Encore or Vite, which are the actively maintained Symfony answers.
• Gulp version drift is the most likely breakage. A bundle written against Gulp 3 (gulp.task('default', ['build'])) will not run on Gulp 4 (series/parallel API, and gulp-cli instead of global gulp). Check the package.json engine/gulp version and lock Node with .nvmrc or an engines field.
• Node version matters as much as PHP. Modern Node will choke on old node-sass/gulp-sass builds. If npm install fails on a native module, that's a Node/native-build incompatibility, not a bundle bug — pin an older Node in Docker rather than patching the bundle.
• No artisan-style ergonomics. No auto-discovery, no facades. If a command isn't listed under bin/console list, the bundle isn't registered or the cache is stale — run bin/console cache:clear before debugging anything else.
• Hardcoded path assumptions. Bundles of this vintage often assume web/ (Symfony 2/3) rather than public/ (Symfony 4+). Symptom: build succeeds, files land in the wrong place, Twig 404s the asset. Verify the build output directory matches your web root.
• Silent failures from the wrapper. If the console command shells out to gulp and swallows stderr, a failing task can look like a success. Run the underlying gulp task directly once to see the real error, then fix the wrapper usage.
• Debugging checklist, in order: bundle registered? → cache cleared? → node_modules present and matching package.json? → gulp binary resolvable (npx gulp --version)? → output paths aligned with web root? Most reported "it doesn't work" issues die at step 2 or 3.
• Extension points to rely on: project-level config, a project-level gulpfile.js override, and Symfony bundle template overrides. Do not edit files inside vendor/ — composer install will erase them on every deploy.
• When to walk away. If you're spending more time fighting Node/gulp compatibility than writing application code, the migration to Webpack Encore (Symfony's first-party answer) or Vite is cheaper than maintaining a zero-dependency bundle. Budget that migration before adopting this package.