Backbone Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require alexandermatveev/backbone-bundle
   

2. Enable the Bundle: Add to app/AppKernel.php:

   new AlexanderMatveev\BackboneBundle\AlexanderMatveevBackboneBundle(),
   

3. Install Assets:

   php bin/console assets:install web --symlink
   

4. First Use Case: Reference the scripts in a Twig template (e.g., base.html.twig):

   <script src="{{ asset('bundles/alexandermatveevbackbone/js/underscore-min.js') }}"></script>
   <script src="{{ asset('bundles/alexandermatveevbackbone/js/backbone-min.js') }}"></script>
   

   Verify by checking the browser's Network tab for loaded files.

Implementation Patterns

Workflow Integration

1. Asset Organization:

   • Use assets:install to symlink assets to web/bundles/alexandermatveevbackbone/js/.
   • For custom builds (e.g., concatenated/minified), override the default paths in config.yml:

     alexander_matveev_backbone:
         underscore_path: 'bundles/yourbundle/js/underscore-custom.js'
         backbone_path:   'bundles/yourbundle/js/backbone-custom.js'
     

2. Twig Templating:

   • Create a reusable Twig block for Backbone dependencies:

     {# templates/base.html.twig #}
     {% block backbone_scripts %}
         <script src="{{ asset(backbone.underscore_path) }}"></script>
         <script src="{{ asset(backbone.backbone_path) }}"></script>
     {% endblock %}
     

   • Access paths via Twig’s asset() function or pass them as Twig globals.

3. Symfony Controller Integration:

   • Pass Backbone models/views as JSON responses:

     // src/AppBundle/Controller/ApiController.php
     public function getModelAction()
     {
         return $this->json([
             'id' => 1,
             'name' => 'Example'
         ]);
     }
     

   • Use in Backbone:

     $.get('/api/model', function(data) {
         var model = new Backbone.Model(data);
     });
     

4. Asset Versioning:

   • Append a version query string to avoid cache issues:

     <script src="{{ asset('bundles/alexandermatveevbackbone/js/backbone-min.js?v=' ~ '1.0') }}"></script>
     

Gotchas and Tips

Pitfalls

1. Outdated Dependencies:

   • The bundle ships with Backbone 1.3.3 (2013) and Underscore 1.8.3 (2014). For modern projects, manually override paths to use newer versions (e.g., via webpack-encore or yarn).
   • Example override in config.yml:

     alexander_matveev_backbone:
         underscore_path: 'bundles/yourbundle/js/underscore@1.13.6.js'
         backbone_path:   'bundles/yourbundle/js/backbone@1.4.0.js'
     

2. Asset Installation Issues:

   • If assets:install fails, manually create symlinks:

     ln -s vendor/alexandermatveev/backbone-bundle/Resources/public/js/underscore-min.js web/bundles/alexandermatveevbackbone/js/
     

   • Ensure web/bundles/ directory exists and is writable.

3. Twig Path Resolution:

   • If asset() fails, verify the bundles/alexandermatveevbackbone/ directory exists in web/. Use absolute paths as a fallback:

     <script src="{{ asset('js/backbone-min.js') }}"></script>
     

     (Place files directly in web/js/ if needed.)

4. Symfony 4+ Compatibility:

   • The bundle targets Symfony 2.x. For Symfony 4/5, use a modern alternative (e.g., webpack + backbone-starter) or wrap this bundle in a custom autoloader.

Debugging Tips

1. Verify Asset Loading:

   • Check the browser’s Console for 404 errors on Backbone/Underscore paths.
   • Use {{ dump(asset('bundles/alexandermatveevbackbone/js/backbone-min.js')) }} in Twig to debug paths.

2. Console Errors:

   • If Backbone throws undefined, ensure:
     • Scripts load in order (Underscore → Backbone → Your code).
     • No global namespace conflicts (e.g., another library overriding Backbone).

3. Configuration Overrides:

   • Clear cache after modifying config.yml:

     php bin/console cache:clear
     

Extension Points

1. Custom Builds:

   • Replace the default JS files with concatenated/minified versions (e.g., using webpack):

     // webpack.config.js
     module.exports = {
         entry: './resources/assets/js/backbone-app.js',
         output: {
             path: __dirname + '/web/bundles/yourbundle/js',
             filename: 'backbone-custom.js'
         }
     };
     

   • Update config.yml to point to the custom path.

2. Local Development:

   • Use unminified versions for debugging:

     <script src="{{ asset('bundles/alexandermatveevbackbone/js/underscore.js') }}"></script>
     <script src="{{ asset('bundles/alexandermatveevbackbone/js/backbone.js') }}"></script>
     

3. Integration with Symfony Forms:

   • Serialize form data to Backbone models:

     var formData = {};
     $('form').serializeArray().forEach(function(item) {
         formData[item.name] = item.value;
     });
     var model = new Backbone.Model(formData);