Tools Bundle Laravel Package

Getting Started

First Steps

1. Installation Add the bundle to your Symfony project via Composer:

   composer require amalricbzh/tools-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       AmalricBzh\ToolsBundle\AmalricBzhToolsBundle::class => ['all' => true],
   ];
   

2. Key Features Overview The bundle provides:

   • Helper utilities (e.g., string manipulation, array operations).
   • Twig extensions for common templating tasks.
   • Symfony form integrations (e.g., custom field types, validators).
   • Dependency injection helpers (e.g., service locators, parameter utilities).

3. First Use Case: String Utilities Access string helpers via the AmalricBzh\ToolsBundle\Helper\StringHelper service:

   use AmalricBzh\ToolsBundle\Helper\StringHelper;
   
   class MyController extends AbstractController {
       public function index(StringHelper $stringHelper) {
           $slug = $stringHelper->slugify('Hello World!');
           // Returns: "hello-world"
       }
   }
   

Implementation Patterns

1. Twig Extensions

Pattern: Extend Twig with reusable filters/filters. Example:

{{ 'Hello World'|slugify }}  {# Output: "hello-world" #}

Integration Tip:

• Override default Twig extensions in config/packages/amalricbzh_tools.yaml:

  amalricbzh_tools:
      twig:
          extensions:
              - 'App\Twig\CustomExtension'
  

2. Form Field Customization

Pattern: Use built-in form types or extend them. Example:

use AmalricBzh\ToolsBundle\Form\Type\AutoCompleteType;

$builder->add('search', AutoCompleteType::class, [
    'choices' => $choices,
    'placeholder' => 'Search...',
]);

Workflow:

1. Register custom form types in services.yaml:

   services:
       App\Form\Type\CustomType:
           tags: ['form.type']
   

3. Dependency Injection Helpers

Pattern: Use ServiceLocator or ParameterHelper. Example:

use AmalricBzh\ToolsBundle\Helper\ServiceLocator;

class MyService {
    public function __construct(private ServiceLocator $locator) {}

    public function getMailer() {
        return $this->locator->get('mailer');
    }
}

4. Event Listeners

Pattern: Subscribe to bundle events (e.g., tools.event). Example:

use AmalricBzh\ToolsBundle\Event\ToolsEvent;

class MySubscriber implements EventSubscriberInterface {
    public static function getSubscribedEvents() {
        return [
            ToolsEvent::PRE_PROCESS => 'onPreProcess',
        ];
    }
}

Gotchas and Tips

Pitfalls

1. Namespace Conflicts

   • The bundle uses AmalricBzh\ToolsBundle namespace. Ensure your project doesn’t clash (e.g., avoid use AmalricBzh\ToolsBundle\Helper in custom classes).

2. Twig Auto-Reloading

   • Clear Twig cache after adding custom extensions:

     php bin/console cache:clear
     

3. Form Type Overrides

   • If extending AutoCompleteType, ensure your class extends the base type:

     class CustomAutoCompleteType extends AutoCompleteType { ... }
     

Debugging Tips

• Enable Debug Mode Set AMALRICBZH_TOOLS_DEBUG=true in .env to log helper usage:

  AMALRICBZH_TOOLS_DEBUG=1
  

• Check Service Availability Verify services are registered:

  php bin/console debug:container amalricbzh_tools.helper.string
  

Extension Points

1. Custom Helpers Register new helpers in config/packages/amalricbzh_tools.yaml:

   amalricbzh_tools:
       helpers:
           - 'App\Helper\CustomHelper'
   

2. Override Default Config Use config/packages/amalricbzh_tools.yaml to modify bundle behavior:

   amalricbzh_tools:
       twig:
           enabled: false  # Disable Twig extensions globally
   

3. Event Customization Dispatch custom events by extending ToolsEvent:

   class MyCustomEvent extends ToolsEvent { ... }