Require Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   • Add "bmatzner/require-bundle": "*" to composer.json under "require".
   • Run composer update bmatzner/require-bundle.
   • Register the bundle in AppKernel.php:

     new Bmatzner\RequireBundle\BmatznerRequireBundle(),
     

   • Install assets via:

     php app/console assets:install web
     

2. First Use Case:

   • Include RequireJS in a Twig template:

     <script type="text/javascript" src="{{ asset('bundles/bmatznerrequire/js/require.min.js') }}" data-main="{{ asset('js/app.js') }}"></script>
     

   • Define your app.js (entry point) in web/js/:

     require.config({ baseUrl: 'js' });
     require(['module'], function(module) { /* ... */ });
     

Implementation Patterns

Workflows

1. Modular Asset Organization:

   • Store RequireJS modules in web/js/ (e.g., models/, views/, controllers/).
   • Use require.config() in app.js to define paths:

     require.config({
         paths: {
             'text': 'bundles/bmatznerrequire/js/plugins/text',
             'i18n': 'bundles/bmatznerrequire/js/plugins/i18n'
         }
     });
     

2. Symfony Integration:

   • Twig Extensions: Use asset() to reference bundles dynamically:

     {# app/config/config.yml #}
     twig:
         globals:
             requirejs_base: "%kernel.root_dir%/../web/bundles/bmatznerrequire/js"
     

     <script src="{{ requirejs_base }}/require.min.js" data-main="{{ asset('js/app.js') }}"></script>
     

3. Dependency Management:

   • Leverage plugins (e.g., text for templates, i18n for localization):

     require(['text!templates/home.html'], function(template) { /* ... */ });
     

4. Debugging Workflow:

   • Use r.js (r.js optimizer) for production builds:

     node node_modules/requirejs/bin/r.js -o build.js
     

   • Configure build.js to optimize bundles:

     ({ appDir: 'web/js', baseUrl: 'js', dir: 'web/js/build', modules: [{ name: 'app' }] })
     

Gotchas and Tips

Pitfalls

1. Asset Paths:

   • Issue: asset() fails if web/ is not the public root.
   • Fix: Verify assets:install targets the correct directory (e.g., --symlink for shared hosting).

2. Plugin Conflicts:

   • Issue: Duplicate RequireJS plugins (e.g., text) may break builds.
   • Fix: Exclude bundled plugins if using standalone RequireJS:

     composer require requirejs/text --ignore-platform-req=php
     

3. Caching:

   • Issue: data-main changes require cache busting (e.g., ?v=1.0).
   • Fix: Use Symfony’s asset() with versioning:

     data-main="{{ asset('js/app.js', { version: '1.0' }) }}"
     

4. Deprecated Bundle:

   • Issue: No active maintenance; RequireJS 2.1.11 is outdated.
   • Fix: Fork the bundle or migrate to modern tools like Webpack Encore or Vite.

Tips

1. Custom Builds:

   • Override BmatznerRequireBundle to extend RequireJS config:

     // src/Bmatzner/RequireBundle/DependencyInjection/Configuration.php
     $rootNode->children()
         ->scalarNode('base_url')->defaultValue('/js')->end();
     

2. Debugging:

   • Use requirejs.debug.js (included in the bundle) for stack traces:

     <script src="{{ asset('bundles/bmatznerrequire/js/require.debug.js') }}"></script>
     

3. Localization:

   • Combine with Symfony’s trans filter:

     require(['i18n!app/translations'], function(translations) {
         console.log(translations['key']); // Symfony's {{ 'key'|trans }} equivalent
     });
     

4. Performance:

   • Preload critical modules:

     require(['domReady!'], function() {
         require(['module'], function(module) { /* ... */ });
     });