Popper Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require alexandermatveev/popper-bundle
   

   Ensure your project uses Symfony 3+ (compatible with older versions but untested).

2. Enable the Bundle: Add to config/bundles.php:

   return [
       // ...
       Alexandermatveev\PopperBundle\AlexandermatveevPopperBundle::class => ['all' => true],
   ];
   

3. First Use Case: Include Popper.js in your Twig template (e.g., base.html.twig):

   <script src="{{ asset('bundles/alexandermatveevpopper/popper.min.js') }}"></script>
   

   Verify the file exists at vendor/alexandermatveev/popper-bundle/Resources/public/popper.min.js.

Implementation Patterns

Core Workflows

1. Dropdowns/Tooltips: Use Popper.js to position dropdowns or tooltips dynamically. Example:

   import Popper from 'popper.js';
   const popper = new Popper(document.getElementById('dropdownTrigger'), document.getElementById('dropdown'), {
       placement: 'bottom',
       modifiers: {
           offset: { offset: '0, 8px' }
       }
   });
   

2. Asset Integration:

   • Webpack Encore: Copy the JS file to your public/js folder during build:

     // webpack.config.js
     Encore.copyFiles({
         from: './vendor/alexandermatveev/popper-bundle/Resources/public/popper.min.js',
         to: 'js/[name].js'
     });
     

   • Symfony Assets: Use symfony/webpack-encore-bundle to bundle Popper with other JS.

3. Dynamic Initialization: Initialize Popper after DOM is ready (e.g., in a Vue/React component or via jQuery):

   $(document).ready(function() {
       new Popper('#trigger', '#content', { placement: 'right' });
   });
   

Integration Tips

• Symfony Forms: Combine with symfony/form for dynamic form tooltips:

  {% for error in form.errors %}
      <div class="tooltip" data-placement="right">
          {{ error.message }}
      </div>
  {% endfor %}
  

  Initialize Popper for each tooltip in a loop.

• Laravel Mix: If using Laravel, alias the file in webpack.mix.js:

  mix.copy('vendor/alexandermatveev/popper-bundle/Resources/public/popper.min.js', 'public/js');
  

Gotchas and Tips

Pitfalls

1. Outdated Version: The bundle ships Popper.js 1.14.4 (released 2018). Modern projects may need newer features (e.g., v2’s auto-placement). Consider:

   • Forking the Bundle: Update the JS file and publish a new version.
   • Direct CDN: Replace the bundle with:

     <script src="https://cdn.jsdelivr.net/npm/popper.js@2.x"></script>
     

2. Symfony 4+ Compatibility: The require-dev targets Symfony 2.x. Test thoroughly in Symfony 4/5, especially with:

   • Asset management (e.g., symfony/asset).
   • Webpack Encore integration.

3. File Path Assumptions: The bundle assumes assets are served from /bundles/alexandermatveevpopper/. If using custom paths, override the asset path in Twig:

   <script src="{{ asset('custom/path/popper.min.js') }}"></script>
   

Debugging

• Missing JS: Verify the file exists at vendor/alexandermatveev/popper-bundle/Resources/public/popper.min.js. Run composer dump-autoload if missing.
• Console Errors: Check for Popper is not defined—ensure the script is loaded before your custom JS.
• Placement Issues: Use Popper’s debug tools to visualize boundaries.

Extension Points

1. Custom Modifiers: Extend Popper’s behavior by adding custom modifiers (e.g., for Laravel-specific animations):

   const customModifier = {
       name: 'laravelFlip',
       enabled: true,
       phase: 'beforeWrite',
       fn: ({ state }) => {
           state.modifiersData.flip = { wasFlipped: false };
       },
       // ... other modifier logic
   };
   new Popper(trigger, content, { modifiers: [customModifier] });
   

2. Event Listeners: Bind Popper events (e.g., update) to trigger Laravel AJAX calls:

   popper.addListener('update', (data) => {
       fetch(`/api/tooltip-position?x=${data.state.rects.reference.x}`)
           .then(response => { /* handle */ });
   });
   

3. Server-Side Rendering: For SSR (e.g., Laravel Vapor), pre-render Popper’s initial state in Twig:

   <div id="tooltip" data-popper-placement="{{ app.request.get('placement', 'bottom') }}"></div>