Phoneformatterbundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony2/3 Bundle: The package is a Symfony bundle, which integrates cleanly into a Laravel ecosystem only via legacy Symfony components (e.g., via illuminate/support compatibility layers or Symfony bridge packages). Laravel’s service container and dependency injection differ from Symfony’s, requiring abstraction or wrapper logic.
• Core Functionality: The package provides phone number formatting (national/international/E164/AUTO) and Twig integration. This aligns with Laravel’s need for consistent phone number handling in APIs, forms, or frontend templates.
• Limitation: The bundle is Symfony-specific (e.g., AppKernel, Twig extensions tied to Symfony’s Twig environment). Laravel’s Twig integration (via laravelcollective/html) would need adaptation.

Integration Feasibility

• High-Level Feasibility: Possible via:
  1. Wrapper Class: Create a Laravel service class that mirrors the bundle’s PhoneFormatterHelper using the underlying giggsey/libphonenumber-for-php library (direct dependency).
  2. Symfony Bridge: Use symfony/http-foundation or symfony/dependency-injection in Laravel (e.g., via spatie/laravel-symfony-support), but this adds complexity.
• Twig Integration: Requires custom Twig extensions in Laravel (e.g., Str::of($number)->phoneFormat() or a PhoneFormatter facade).
• Database/ORM: No direct ORM integration, but can be used in model accessors/mutators or form requests.

Technical Risk

• Deprecation Risk: Last release in 2016; relies on Symfony 2.8/3.0 and libphonenumber-for-php@7.7 (now at v8+). Potential breaking changes if upgrading dependencies.
• Laravel Compatibility:
  • Symfony’s ContainerInterface ≠ Laravel’s Container. Requires manual binding or a facade.
  • Twig extensions must be registered via Laravel’s service provider.
• Testing: No tests or CI in the package. Risk of undocumented edge cases (e.g., invalid country codes, malformed numbers).
• Performance: libphonenumber-for-php is robust but may introduce overhead for high-throughput APIs.

Key Questions

1. Is libphonenumber-for-php v8+ compatible? If not, can we fork or patch the bundle?
2. What’s the migration path for Twig templates? Will we replace Symfony Twig with Laravel’s Blade or adapt Twig extensions?
3. How will this integrate with Laravel’s validation? (e.g., Illuminate\Validation\Rule for phone numbers).
4. What’s the fallback for unsupported locales/country codes? The package lacks error handling examples.
5. Can we replace this with a lighter alternative? (e.g., egulias/email-validator for phone numbers, or a custom regex-based solution).

Integration Approach

Stack Fit

• Laravel Core: The package’s giggsey/libphonenumber-for-php dependency is the most valuable part. Laravel can use this directly without the Symfony bundle.
• Twig in Laravel: If using laravelcollective/html, the Twig extension would need a Laravel-compatible rewrite (e.g., via a custom TwigExtension service).
• Blade Templates: Prefer Blade directives (e.g., @phoneFormat($number, 'INTERNATIONAL')) or helper functions (phone_format($number)).
• APIs: Use the underlying library in Laravel services (e.g., PhoneFormatter::format($number)).

Migration Path

1. Phase 1: Extract Core Logic

   • Replace the bundle with direct libphonenumber-for-php usage:

     use libphonenumber\PhoneNumberUtil;
     use libphonenumber\PhoneNumberFormat;
     
     $util = PhoneNumberUtil::getInstance();
     $number = $util->parse($rawNumber, $countryCode);
     echo $util->format($number, PhoneNumberFormat::NATIONAL);
     

   • Create a Laravel service class (e.g., app/Services/PhoneFormatter.php) to wrap this logic.

2. Phase 2: Laravel Integration

   • Service Provider: Bind the formatter to the container:

     $this->app->singleton(PhoneFormatter::class, function ($app) {
         return new PhoneFormatter();
     });
     

   • Facade: Publish a Phone facade for easy access.
   • Twig/Blade: Add helpers or directives (e.g., {{ phone_format($number, 'INTERNATIONAL') }} or @phone($number)).

3. Phase 3: Deprecate Bundle

   • Remove Symfony-specific code (e.g., AppKernel, bundle registration).
   • Update documentation to reflect Laravel-specific usage.

Compatibility

• Laravel Versions: Works with Laravel 5.5+ (PHP 7.1+). For older versions, may need polyfills for libphonenumber-for-php.
• Symfony Dependencies: Avoid symfony/symfony; use only giggsey/libphonenumber-for-php.
• Country Codes: Ensure supported locales match your app’s requirements (e.g., DE, FR). Test edge cases like invalid inputs.

Sequencing

1. Audit Dependencies: Verify libphonenumber-for-php@7.7 compatibility with Laravel’s PHP version.
2. Prototype Core Logic: Test the formatter outside Symfony (e.g., in a Laravel Artisan command).
3. Integrate into Services: Replace hardcoded phone formatting in models/controllers with the new service.
4. Update Frontend: Replace Twig/Blade templates with the new helpers.
5. Deprecate Bundle: Remove Symfony bundle code post-migration.

Operational Impact

Maintenance

• Dependency Updates: Monitor libphonenumber-for-php for breaking changes (e.g., v8+). May require periodic updates.
• Custom Logic: If extending functionality (e.g., custom validation), maintain these changes in Laravel’s codebase.
• Documentation: Update Laravel-specific docs for the new PhoneFormatter service.

Support

• Error Handling: The original bundle lacks error handling for invalid numbers/country codes. Laravel should:
  • Throw exceptions for malformed inputs (e.g., InvalidPhoneNumberException).
  • Log warnings for unsupported locales.
• Fallbacks: Define defaults for unsupported cases (e.g., return raw input or a placeholder).
• Debugging: Add logging for phone formatting operations to trace issues.

Scaling

• Performance: libphonenumber-for-php is CPU-intensive for parsing/validation. Cache parsed numbers in Laravel’s cache (e.g., Cache::remember()).
• Batch Processing: For bulk operations (e.g., importing phone numbers), use queue workers to avoid timeouts.
• Database: Store formatted numbers in a consistent format (e.g., E164) to avoid repeated parsing.

Failure Modes

Ramp-Up

• Team Onboarding:
  • Document the new PhoneFormatter service in Laravel’s internal wiki.
  • Provide examples for common use cases (API responses, forms, emails).
• Training:
  • Conduct a 30-minute session on the migration (focus on service usage vs. bundle).
  • Highlight differences from the old Symfony Twig syntax.
• Deprecation Plan:
  • Phase out the Symfony bundle over 2–3 sprints.
  • Add deprecation warnings in logs for old bundle usage.
• Testing:
  • Add unit tests for the PhoneFormatter service (cover edge cases).
  • Test in staging with production-like data volumes.