Utility Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require aqarmap/utility-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Aqarmap\UtilityBundle\AqarmapUtilityBundle::class => ['all' => true],
   ];
   

2. First Use Case:

   • Gravatar Helper: Generate a Gravatar URL for a user’s email:

     use Aqarmap\UtilityBundle\Helper\GravatarHelper;
     
     $gravatarHelper = $this->get('aqarmap_utility.gravatar_helper');
     $url = $gravatarHelper->getUrl('user@example.com', 50); // 50px image
     

   • String Utilities: Format strings or truncate text:

     use Aqarmap\UtilityBundle\Helper\StringHelper;
     
     $stringHelper = $this->get('aqarmap_utility.string_helper');
     $truncated = $stringHelper->truncate('Long text here...', 10);
     

Key Classes to Explore

• GravatarHelper: For avatar generation.
• StringHelper: For text manipulation (truncate, slugify, etc.).
• ArrayHelper: For array operations (flatten, merge, etc.).
• FileHelper: For file/directory operations.

Implementation Patterns

Common Workflows

1. Service Injection: Inject utilities via constructor or setter:

   public function __construct(GravatarHelper $gravatarHelper) {
       $this->gravatarHelper = $gravatarHelper;
   }
   

   Or fetch via Symfony’s container:

   $this->get('aqarmap_utility.string_helper');
   

2. Twig Integration: Extend Twig with custom filters/extensions:

   {{ 'Hello World'|aqarmap_truncate(10) }}
   

   Register in services.yaml:

   twig:
       globals:
           aqarmap_utility: '@aqarmap_utility.twig_extension'
   

3. Command-Line Utilities: Use helpers in console commands:

   use Aqarmap\UtilityBundle\Helper\FileHelper;
   
   public function handle(FileHelper $fileHelper) {
       $fileHelper->createDirectory('path/to/dir');
   }
   

4. Event Listeners/Subscribers: Leverage utilities in event logic:

   public function onKernelRequest(GetResponseEvent $event) {
       $slug = $this->get('aqarmap_utility.string_helper')->slugify('User Name');
   }
   

Integration Tips

• Dependency Management: Prefer constructor injection over $this->get() for testability.
• Configuration: Override defaults via config/packages/aqarmap_utility.yaml (if supported).
• Performance: Cache Gravatar URLs or file operations if called frequently in loops.

Gotchas and Tips

Pitfalls

1. Outdated Codebase:

   • Last release in 2017 may lack compatibility with modern Symfony (5.4+/LTS).
   • Test thoroughly with your Symfony version (e.g., symfony/dependency-injection changes).
   • Workaround: Fork the repo and update dependencies if critical features are needed.

2. Gravatar Rate Limits:

   • GravatarHelper generates URLs dynamically. Cache responses to avoid hitting rate limits:

     $cache = $this->get('cache.app');
     $url = $cache->get("gravatar_{$email}", function() use ($gravatarHelper, $email) {
         return $gravatarHelper->getUrl($email);
     });
     

3. StringHelper Quirks:

   • slugify() may not handle all Unicode characters perfectly. Test edge cases (e.g., é, ü).
   • truncate() uses ... by default—customize via method parameters:

     $stringHelper->truncate('text', 10, ['append' => ' [+]']);
     

4. FileHelper Permissions:

   • File operations (e.g., createDirectory()) may fail due to server permissions.
   • Debug Tip: Use isWritable() to check paths before operations.

Debugging Tips

• Enable Debug Mode: Symfony’s debug toolbar helps trace service calls.
• Log Helper Outputs: Temporarily log helper results to verify behavior:

  $this->logger->debug('Gravatar URL', ['url' => $url]);
  

• Check for Deprecated Methods: Use phpstan or psalm to detect unsafe usage.

Extension Points

1. Custom Helpers: Extend existing helpers by subclassing and overriding methods:

   class CustomStringHelper extends StringHelper {
       public function customTruncate($string, $length) {
           return parent::truncate($string, $length) . ' [Custom]';
       }
   }
   

   Register the new service in services.yaml:

   aqarmap_utility.string_helper:
       class: App\Helper\CustomStringHelper
   

2. Add New Utilities: Create a custom bundle or service to wrap additional logic, then integrate with the existing pattern.

3. Twig Extensions: Add more filters/extensions by extending Aqarmap\UtilityBundle\Twig\TwigExtension:

   class CustomTwigExtension extends TwigExtension {
       public function getFilters() {
           return [
               new TwigFilter('custom_filter', [$this, 'customFilter']),
           ];
       }
   }