Toolbox Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require antidot-be/toolbox-bundle
   

   Ensure your project uses PHP ≥7.2 and Symfony ≥4.4 (or ≥5.0).

2. Enable the Bundle Add to config/bundles.php (Symfony 4.4+):

   return [
       // ...
       Antidot\ToolboxBundle\AntidotToolboxBundle::class => ['all' => true],
   ];
   

3. First Use Case: Twig Uniform Rendering Use the antidot_toolbox Twig extension for consistent HTML rendering:

   {{ antidot_toolbox.render_button('Click Me', {type: 'primary'}) }}
   

   Check Resources/views/Twig/ for pre-built templates (e.g., buttons, alerts).

Implementation Patterns

Core Workflows

1. Twig Extensions

   • Button Rendering: Pass options like type, icon, or disabled:

     {{ antidot_toolbox.render_button('Save', {type: 'success', icon: 'save'}) }}
     

   • Alerts: Use render_alert with type (e.g., info, error):

     {{ antidot_toolbox.render_alert('Warning!', {type: 'warning'}) }}
     

   • Extend Templates: Override base templates in templates/antidot_toolbox/ to customize.

2. Helper Classes

   • String Utilities: Use Antidot\ToolboxBundle\Helper\StringHelper for common string ops:

     use Antidot\ToolboxBundle\Helper\StringHelper;
     $slug = StringHelper::slugify('Hello World'); // 'hello-world'
     

   • Array Merging: Leverage ArrayHelper::deepMerge() for nested array updates.

3. Integration with Forms

   • Use antidot_toolbox.form_row() in Twig to standardize form fields:

     {{ form_row(form.email, {label: 'Email Address'}) }}
     

Best Practices

• Consistency: Reuse bundle templates for UI components (buttons, cards, modals).
• Configuration: Override default Twig paths in config/packages/antidot_toolbox.yaml:

  antidot_toolbox:
      templates:
          button: 'custom/path/to_button.html.twig'
  

• Dependency Injection: Inject AntidotToolbox service for programmatic use:

  public function __construct(private AntidotToolbox $toolbox) {}
  $this->toolbox->renderButton('Text', ['type' => 'danger']);
  

Gotchas and Tips

Pitfalls

1. Kernel Compatibility

   • Issue: Bundle assumes Symfony 4.4+ (or 5.0+). Older versions may fail.
   • Fix: Check composer.json constraints or fork the bundle.

2. Template Overrides

   • Issue: Custom templates in templates/antidot_toolbox/ must match the bundle’s structure exactly.
   • Fix: Use {{ parent() }} in Twig to extend base templates:

     {# templates/antidot_toolbox/button.html.twig #}
     <button class="btn {{ type|default('default') }}">
         {{ parent() }}
     </button>
     

3. Twig Extension Naming

   • Issue: The extension is registered as antidot_toolbox, not toolbox. Typos break rendering.
   • Fix: Verify with {{ dump(antidot_toolbox) }} in Twig.

Debugging

• Missing Templates: Clear cache (php bin/console cache:clear) if templates don’t load.
• PHP Errors: Enable debug mode (APP_DEBUG=true) and check var/log/dev.log.
• Service Not Found: Ensure the bundle is enabled in config/bundles.php.

Extension Points

1. Add Custom Twig Functions Extend the AntidotToolboxExtension class:

   // src/Twig/AppExtension.php
   class AppExtension extends \Twig\Extension\AbstractExtension
   {
       public function getFunctions()
       {
           return [
               new \Twig\TwigFunction('custom_function', [$this, 'customFunction']),
           ];
       }
   }
   

2. Modify Helper Classes Override services in config/services.yaml:

   services:
       Antidot\ToolboxBundle\Helper\StringHelper:
           class: App\Helper\CustomStringHelper
           arguments: ['@antidot.toolbox.string_helper']
   

3. Event Listeners Attach to bundle events (e.g., antidot.toolbox.template.render) via Symfony’s event dispatcher.