Shared Tools Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require bayardev/shared-tools-bundle
   

   Ensure your project meets the PHP ≥5.6 requirement (upgrade if needed).

2. Create VERSION file Add an empty VERSION file in your project root (required for versioning utilities).

3. Enable the Bundle Register in config/bundles.php (Symfony Flex) or app/AppKernel.php (legacy):

   return [
       // ...
       Bayardev\SharedToolsBundle\BayardevSharedToolsBundle::class => ['all' => true],
   ];
   

4. First Use Case Test the version helper via Twig:

   {{ app.version() }}  {# Outputs version from VERSION file #}
   

   Or in PHP:

   $version = $this->get('bayardev_shared_tools.version')->getVersion();
   

Implementation Patterns

Core Workflows

1. Version Management

   • Dynamic Versioning: Use app.version() in Twig or $this->get('bayardev_shared_tools.version') in controllers.
   • Custom Version Sources: Override the VERSION file logic by extending the VersionService:

     // src/Service/CustomVersionService.php
     class CustomVersionService extends \Bayardev\SharedToolsBundle\Service\VersionService {
         public function getVersion() {
             return file_get_contents('custom/path/VERSION');
         }
     }
     

     Register as a service in config/services.yaml:

     services:
         Bayardev\SharedToolsBundle\Service\VersionService: '@App\Service\CustomVersionService'
     

2. Logging Utilities

   • Structured Logging: Use Bayardev\SharedToolsBundle\Logger\StructuredLogger for JSON-formatted logs:

     $logger = $this->get('bayardev_shared_tools.structured_logger');
     $logger->info('User login', ['user_id' => 123, 'ip' => '192.168.1.1']);
     

   • Monolog Integration: Configure in config/packages/monolog.yaml:

     handlers:
         structured:
             type: service
             id: bayardev_shared_tools.structured_logger
     

3. Request Helpers

   • Client IP: Access via app.request.client_ip.
   • User Agent Parsing: Use Bayardev\SharedToolsBundle\Helper\RequestHelper:

     $ua = $this->get('bayardev_shared_tools.request_helper')->getUserAgent();
     $browser = $ua->getBrowserName();
     

4. Response Utilities

   • JSON Responses: Simplify with Bayardev\SharedToolsBundle\Response\JsonResponse:

     return $this->jsonResponse(['success' => true], 200);
     

Integration Tips

• Symfony Events: Listen to bayardev.tools.version.loaded to react to version changes.
• Twig Extensions: Extend Twig with custom filters/filters using the bundle’s TwigExtension:

  {{ "hello"|uppercase_with_prefix("Prefix: ") }}  {# "Prefix: HELLO" #}
  

• Dependency Injection: Prefer autowiring for services (e.g., VersionService).

Gotchas and Tips

Pitfalls

1. Version File Dependency

   • The VERSION file is mandatory. Forgetting it causes VersionService to throw RuntimeException.
   • Fix: Add to .gitignore if using dynamic versions (e.g., CI-generated).

2. Legacy Kernel Support

   • The bundle assumes Symfony ≥3.4 (due to Flex). For older projects:
     • Manually require symfony/flex as a dev dependency.
     • Use composer require symfony/flex and run composer dump-autoload.

3. Logger Overrides

   • The StructuredLogger replaces the default logger if not configured properly. Explicitly define handlers in monolog.yaml to avoid losing logs:

     handlers:
         main:
             type: stream
             path: "%kernel.logs_dir%/%kernel.environment%.log"
         structured:
             type: service
             id: bayardev_shared_tools.structured_logger
     

4. Request Helper Caching

   • RequestHelper caches user agent parsing. Clear cache with:

     $this->get('bayardev_shared_tools.request_helper')->clearCache();
     

   • Tip: Disable caching in config/packages/bayardev_shared_tools.yaml:

     bayardev_shared_tools:
         request_helper:
             cache_user_agent: false
     

Debugging

• Version Service Issues

  • Check file permissions for VERSION (must be readable).
  • Verify the service is properly registered (debug with bin/console debug:container bayardev_shared_tools.version).

• Logger Not Working

  • Ensure monolog is enabled in config/bundles.php.
  • Check for typos in handler IDs (case-sensitive).

Extension Points

1. Custom Version Sources

   • Implement Bayardev\SharedToolsBundle\Service\VersionSourceInterface for alternative version providers (e.g., Git tags, API calls).

2. Twig Filters

   • Add custom filters by extending Bayardev\SharedToolsBundle\Twig\TwigExtension:

     // src/Twig/AppExtension.php
     class AppExtension extends \Bayardev\SharedToolsBundle\Twig\TwigExtension {
         public function getFunctions() {
             return [
                 new \Twig\TwigFunction('custom_filter', [$this, 'customFilter']),
             ];
         }
     }
     

   • Register in config/packages/twig.yaml:

     twig:
         paths: ['%kernel.project_dir%/templates']
         extensions:
             - App\Twig\AppExtension
     

3. Event Listeners

   • Subscribe to bayardev.tools.version.loaded to trigger actions on version changes:

     // src/EventListener/VersionListener.php
     class VersionListener implements EventSubscriberInterface {
         public static function getSubscribedEvents() {
             return [
                 'bayardev.tools.version.loaded' => 'onVersionLoaded',
             ];
         }
         public function onVersionLoaded(VersionEvent $event) {
             // Logic here
         }
     }
     

Performance Tips

• Disable Unused Features: Configure in config/packages/bayardev_shared_tools.yaml:

  bayardev_shared_tools:
      version:
          enabled: true
      request_helper:
          enabled: false  # Disable if not needed
  

• Cache User Agent Data: Enable caching for RequestHelper to reduce parsing overhead:

  bayardev_shared_tools:
      request_helper:
          cache_user_agent: true
          cache_ttl: 3600  # 1 hour