Usefultoolbox Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require adachsoft/usefultoolbox-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Adachsoft\UsefulToolboxBundle\AdachsoftUsefulToolboxBundle::class => ['all' => true],
   ];
   

2. First Use Case The bundle provides utility classes under Adachsoft\UsefulToolboxBundle\Utils\. Example: Use the StringUtils for basic string operations:

   use Adachsoft\UsefulToolboxBundle\Utils\StringUtils;
   
   $sanitized = StringUtils::slugify('Hello World!');
   // Returns: 'hello-world'
   

3. Where to Look First

   • Documentation: Check the Utils namespace for available classes (e.g., ArrayUtils, DateUtils, FileUtils).
   • Tests: Browse tests/ for usage examples and edge cases.
   • Config: Override default settings in config/packages/adachsoft_usefultoolbox.yaml.

Implementation Patterns

Common Workflows

1. String Manipulation Use StringUtils for consistent formatting (e.g., slugs, truncation, or case conversion):

   $truncated = StringUtils::truncate('Long string...', 10);
   // Returns: 'Long stri...'
   

2. Array Operations Leverage ArrayUtils for deep merging, flattening, or diffing:

   $merged = ArrayUtils::deepMerge(['a' => 1], ['a' => 2, 'b' => 3]);
   // Returns: ['a' => 2, 'b' => 3]
   

3. Date Handling Use DateUtils for timezone-aware operations:

   $formatted = DateUtils::format(new \DateTime(), 'Y-m-d H:i:s');
   

4. File System FileUtils simplifies path resolution and file operations:

   $path = FileUtils::getProjectRoot() . '/public/uploads';
   

Integration Tips

• Service Container: Bind utilities to Symfony’s container for DI:

  # config/services.yaml
  services:
      Adachsoft\UsefulToolboxBundle\Utils\StringUtils: ~
  

  Then inject via constructor:

  public function __construct(private StringUtils $stringUtils) {}
  

• Custom Extensions: Extend utility classes by overriding methods or creating decorators.

• Command-Line Tools: Use ConsoleUtils for CLI output formatting:

  ConsoleUtils::success('Operation completed!');
  

Gotchas and Tips

Pitfalls

1. Namespace Conflicts The bundle uses Adachsoft\UsefulToolboxBundle\Utils\*. Ensure no naming collisions with your project’s utilities.

2. Configuration Overrides Default configs (e.g., slugify_separator) may not match expectations. Override in adachsoft_usefultoolbox.yaml:

   adachsoft_usefultoolbox:
       string_utils:
           slugify_separator: '-'
   

3. FileUtils Caching FileUtils::getProjectRoot() caches paths. Clear cache if paths change dynamically:

   FileUtils::clearCache();
   

4. DateUtils Timezones Defaults to system timezone. Explicitly set in methods:

   DateUtils::format($date, 'Y-m-d', 'Europe/Berlin');
   

Debugging Tips

• Enable Debug Mode: Set ADACHSOFT_TOOLBOX_DEBUG=true in .env for verbose logs.
• Test Coverage: Run php bin/phpunit to verify edge cases (e.g., empty arrays in ArrayUtils).

Extension Points

1. Custom Utilities Create a subclass (e.g., AppUtils extends StringUtils) and override methods:

   class AppUtils extends StringUtils {
       public static function customSlugify(string $string): string {
           return parent::slugify($string) . '-app';
       }
   }
   

2. Event Listeners Hook into bundle events (if documented) to extend functionality. Example:

   // src/EventListener/ToolboxListener.php
   public static function getSubscribedEvents(): array {
       return [
           AdachsoftUsefulToolboxEvents::PRE_SLUGIFY => 'onPreSlugify',
       ];
   }
   

3. Twig Integration Expose utilities to Twig for templating:

   {{ app.usefultoolbox.string_utils.slugify('Hello') }}
   

   Requires registering the bundle’s Twig extension in services.yaml.