Extra Tools Bundle Laravel Package

Getting Started

Minimal Setup

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

   composer require bcc/extra-tools-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       MichelSalib\BCCExtraToolsBundle\BCCExtraToolsBundle::class => ['all' => true],
   ];
   

2. First Use Case: Translation Extraction Run the translation extractor to scan your project for missing translations:

   php bin/console extra-tools:extract-translations
   

   • Outputs missing keys to var/extra-tools/translations/.
   • Configure paths in config/packages/bcc_extra_tools.yaml:

     bcc_extra_tools:
         extractor:
             paths: ['%kernel.project_dir%/src', '%kernel.project_dir%/templates']
     

3. Locale-Specific Date Handling Use the LocaleDateParser and LocaleDateFormatter services:

   use MichelSalib\BCCExtraToolsBundle\Service\LocaleDateParser;
   use MichelSalib\BCCExtraToolsBundle\Service\LocaleDateFormatter;
   
   // Parse a date string (e.g., "12/03/2023" for fr_FR)
   $parser = $this->container->get(LocaleDateParser::class);
   $date = $parser->parse('12/03/2023', 'fr_FR');
   
   // Format a date (e.g., for en_US)
   $formatter = $this->container->get(LocaleDateFormatter::class);
   $formatted = $formatter->format($date, 'en_US', 'Y-m-d');
   

Implementation Patterns

Translation Workflow

1. Extract Missing Keys Integrate extraction into your CI/CD pipeline:

   php bin/console extra-tools:extract-translations --env=prod
   

   • Use --format=json for API-friendly output.

2. Merge with Existing Translations Automate merging extracted keys into your translation files (e.g., .po/.xliff):

   php bin/console extra-tools:merge-translations
   

3. Dynamic Translation Fallbacks Use the TranslationExtractor service to validate keys at runtime:

   $extractor = $this->container->get('bcc_extra_tools.extractor');
   if (!$extractor->hasTranslation('domain', 'key')) {
       // Log or handle missing translation
   }
   

Locale-Aware Date Handling

1. Contextual Date Parsing Parse user-uploaded dates dynamically:

   $locale = $request->getLocale(); // e.g., 'de_DE'
   $date = $parser->parse($request->get('date'), $locale);
   

2. Consistent Formatting Standardize date outputs across locales:

   $formatted = $formatter->format($date, $locale, 'MMMM d, Y'); // e.g., "March 12, 2023"
   

3. Twig Integration Extend Twig with custom filters:

   {{ date|format_date('fr_FR', 'd/m/Y') }}
   

   Register in twig.config.yaml:

   twig:
       filters:
           format_date: MichelSalib\BCCExtraToolsBundle\Twig\LocaleDateExtension
   

Unit Conversion

1. Currency/Measurement Conversions Use the UnitConverter service:

   $converter = $this->container->get('bcc_extra_tools.converter');
   $converted = $converter->convert(100, 'USD', 'EUR'); // Uses current exchange rates
   

2. Custom Units Extend the converter for domain-specific units (e.g., "points" to "euros"):

   # config/packages/bcc_extra_tools.yaml
   bcc_extra_tools:
       converter:
           custom_units:
               points_to_eur: 0.01
   

Gotchas and Tips

Translation Extractor

• Pitfalls:

  • False Positives: The extractor may flag static strings (e.g., in SQL queries). Exclude paths:

    bcc_extra_tools:
        extractor:
            exclude_paths: ['%kernel.project_dir%/migrations']
    

  • Performance: Avoid running on large codebases in CI. Use --limit to scan specific files.

• Tips:

  • Custom Patterns: Extend the extractor by implementing ExtractorInterface and overriding the service:

    services:
        app.extractor:
            class: App\Service\CustomExtractor
            decorates: 'bcc_extra_tools.extractor'
    

  • Dry Runs: Use --dry-run to preview changes before merging.

Locale Date Tools

• Pitfalls:

  • Ambiguous Formats: Some locales (e.g., en_US vs. en_GB) parse MM/dd/yyyy differently. Specify formats explicitly:

    $parser->parse('01/02/2023', 'en_US', 'm/d/Y'); // Avoid auto-detection
    

  • Timezones: Dates are timezone-agnostic. Use DateTimeZone for consistency:

    $date->setTimezone(new DateTimeZone('Europe/Paris'));
    

• Tips:

  • Caching: Cache parsed/formatted dates to avoid redundant operations:

    $cache = $this->container->get('cache.app');
    $key = 'date_'.$locale.$format.serialize($date);
    return $cache->get($key, fn() => $formatter->format($date, $locale, $format));
    

  • Fallback Locales: Configure defaults in config/packages/bcc_extra_tools.yaml:

    bcc_extra_tools:
        locale:
            default: 'en_US'
            fallback: 'en'
    

Unit Converter

• Pitfalls:

  • Stale Data: Exchange rates/currency data may not update automatically. Schedule a cron job:

    php bin/console bcc_extra_tools:update-converter-data
    

  • Precision Loss: Floating-point conversions (e.g., points_to_eur) may introduce rounding errors. Use bcmath for financial data:

    $converted = bcmul($value, '0.01', 2); // 2 decimal places
    

• Tips:

  • Custom Providers: Replace the default data source (e.g., for internal APIs):

    services:
        bcc_extra_tools.converter.data_provider:
            class: App\Service\CustomDataProvider
            arguments:
                - '@http_client'
    

  • Batch Conversions: Process arrays efficiently:

    $converter->convertBatch([100, 200, 300], 'USD', 'EUR');
    

General Bundle Tips

• Configuration Overrides: Always validate changes in bcc_extra_tools.yaml after updates.
• Debugging: Enable verbose output for commands:

  php bin/console extra-tools:extract-translations -v
  

• Symfony 6+: Use the autoconfigure: true option in bundles.php for auto-wiring:

  BCCExtraToolsBundle::class => ['all' => true, 'autoconfigure' => true],