Backbone Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   • Add "bmatzner/backbone-bundle": "~1.3" to composer.json and run composer update.
   • Register the bundle in AppKernel.php under registerBundles().
   • Run php app/console assets:install web (or --symlink for symlinked assets).

2. First Use Case:

   • Include Backbone.js in a Twig template:

     {% block javascripts %}
         {{ parent() }}
         <script src="{{ asset('bundles/bmatznerbackbone/js/backbone.min.js') }}"></script>
         <script src="{{ asset('bundles/bmatznerbackbone/js/underscore.min.js') }}"></script> <!-- Required -->
         <script src="{{ asset('bundles/bmatznerbackbone/js/jquery.min.js') }}"></script> <!-- Optional -->
     {% endblock %}
     

   • Verify Backbone is loaded by checking window.Backbone in browser console.

Implementation Patterns

Core Workflows

1. Asset Management:

   • Use asset() helper for versioned paths (e.g., asset('bundles/bmatznerbackbone/js/backbone.min.js')).
   • Prefer --symlink in assets:install for development to avoid duplication.

2. Integration with Symfony:

   • Twig Templates: Load Backbone dependencies in javascripts block.
   • Controllers: Serve JSON data for Backbone models/collections via Symfony’s JsonResponse:

     return new JsonResponse($this->getDoctrine()->getRepository('App:Post')->findAll());
     

3. API Endpoints:

   • Use Symfony’s routing to map Backbone AJAX calls (e.g., POST /api/posts):

     # config/routes.yml
     api_posts:
         path: /api/posts
         methods: [GET, POST]
         defaults: { _controller: 'App\Controller\PostController::apiAction' }
     

4. Debugging:

   • Override backbone.min.js with unminified versions (e.g., backbone.js) in development.

Advanced Patterns

• Custom Builds:
  • Extend the bundle’s Resources/public/js to include your Backbone app logic.
  • Use Webpack Encore or Symfony Flex recipes for modern asset pipelines.
• Dependency Injection:
  • Pass Symfony services (e.g., Router, Serializer) to Backbone via Twig globals:

    <script>
        window.symfony = { router: {{ app.request.get('_route_params')|json_encode }} };
    </script>
    

Gotchas and Tips

Pitfalls

1. Asset Paths:

   • Hardcoding paths (e.g., /bundles/bmatznerbackbone/...) breaks when web/ is not the root.
   • Fix: Always use asset() helper.

2. Version Conflicts:

   • Backbone 1.3.3 is outdated. Mixing with newer jQuery/Underscore may cause issues.
   • Fix: Pin versions in composer.json or use a CDN for modern libraries.

3. Missing Dependencies:

   • Backbone requires Underscore.js (or Lo-Dash) and optionally jQuery/Zepto.
   • Fix: Include all required scripts in your template.

4. Archived Bundle:

   • No active maintenance. Avoid for new projects; consider alternatives like:
     • FOSJsRoutingBundle (for API routes).
     • Modern asset pipelines (Webpack, Vite).

Debugging Tips

• Console Errors:
  • Check for Backbone is not defined → Missing script tags.
  • Check for Uncaught TypeError → Version mismatches (e.g., jQuery 3.x with old plugins).
• Symfony Logs:
  • Use bin/console debug:assets to verify asset paths.

Extension Points

1. Custom Templates:
   • Override BmatznerBackboneBundle::Resources/views to modify default templates.
2. Asset Overrides:
   • Place custom JS files in app/Resources/public/bundles/bmatznerbackbone/js/ to override defaults.
3. Configuration:
   • No config.yml options exist; extend via Twig or custom services.

Performance

• Production:
  • Enable asset versioning (%kernel.debug% = false) for cache busting.
  • Use --symlink in development to avoid file duplication.