Standards Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require prinsfrank/standards
   

   Ensure PHP 8.1+ is used.

2. First Use Case: Validate and work with standardized data types. For example, enforce valid country codes in a form handler:

   use PrinsFrank\Standards\Country\CountryAlpha2;
   
   public function store(Request $request)
   {
       $country = CountryAlpha2::from($request->input('country'));
       // $country now enforces valid ISO 3166-1 Alpha-2 codes
   }
   

3. Key Entry Points:

   • Browse the package docs for available standards (e.g., Country, Currency, Language).
   • Use the from() method to instantiate enums from raw values (e.g., CountryAlpha2::from('US')).

Implementation Patterns

Core Workflows

1. Type Safety: Use enums as method parameters or return types to enforce valid values:

   public function getCountryName(CountryAlpha2 $country): string
   {
       return $country->name;
   }
   

2. Data Conversion: Leverage relationships between enums (e.g., country codes ↔ numeric values):

   $countryAlpha3 = CountryAlpha3::from('USA');
   $countryNumeric = $countryAlpha3->toCountryNumeric(); // CountryNumeric::USA
   

3. Localization: Fetch localized names or formats (e.g., currency, numbers):

   $country = CountryAlpha2::France;
   $formattedNumber = $country->formatNumber(1000.5, LanguageAlpha2::French);
   // Outputs: "1 000,5" (French locale)
   

4. Group Membership Checks: Validate if a country belongs to a group (e.g., EU, NATO):

   if (CountryAlpha2::Germany->isMemberOf(EU::class)) {
       // Logic for EU countries
   }
   

5. Phone Number Handling: Format phone numbers based on country-specific rules:

   $phoneNumber = CountryAlpha2::Japan->formatPhoneNumber('0312345678');
   // Outputs: "+81 3-1234-5678"
   

Integration Tips

• Validation: Use enums in Laravel’s FormRequest validation:

  public function rules(): array
  {
      return [
          'country' => ['required', Rule::enum(CountryAlpha2::class)],
      ];
  }
  

• API Responses: Return enum values (e.g., CountryAlpha2::US->value) for standardized responses.
• Database Storage: Store enum values (e.g., CountryAlpha3::US->value) in DB columns with string type.
• Dependency Injection: Bind enums to interfaces for loose coupling:

  $this->app->bind(
      CountryService::class,
      fn() => new CountryService(CountryAlpha2::class)
  );
  

Gotchas and Tips

Pitfalls

1. Case Sensitivity:

   • Country codes (Alpha2, Alpha3) are case-sensitive (e.g., CountryAlpha2::from('nl') fails; use 'NL').
   • Language codes (Alpha2, Alpha3) are case-sensitive (e.g., LanguageAlpha2::from('en') works; 'EN' fails).

2. Backed Enum Values:

   • Enums use backed values (e.g., CountryAlpha2::US->value returns 'US'). Avoid comparing names directly:

     // ❌ Avoid (compares names, not values)
     if ($country->name === 'United States') { ... }
     
     // ✅ Correct (compares values)
     if ($country->value === 'US') { ... }
     

3. Non-Bidirectional Conversions:

   • Not all conversions are possible (e.g., LanguageTag → Country is supported, but Country → LanguageTag requires additional logic).

4. Flag Emojis:

   • Flag emojis (e.g., $country->getFlagEmoji()) may not render correctly on Windows. Use workarounds.

5. Deprecated Entries:

   • Some enums (e.g., CountryAlpha2::Czechoslovakia) may exist but are deprecated. Check isDeprecated() if needed.

Debugging

• Invalid Values: Use try-catch for invalid inputs:

  try {
      $country = CountryAlpha2::from('ZZ'); // Throws InvalidArgumentException
  } catch (\InvalidArgumentException $e) {
      // Handle invalid country code
  }
  

• Enum Introspection: List all available values for debugging:

  foreach (CountryAlpha2::cases() as $country) {
      echo $country->value . "\n";
  }
  

Extension Points

1. Custom Groups: Extend GroupInterface to create custom country groups:

   class CustomGroup implements GroupInterface {
       public function isMember(CountryAlpha2 $country): bool { ... }
   }
   

2. Localization Overrides: Override default names/translations by extending enums:

   final class CustomCountryName extends CountryName {
       public static function from(string $value): self {
           return parent::from($value)->withName('Custom Name');
       }
   }
   

3. Adding New Standards: Fork the package and add new enums by following the existing pattern (e.g., Country, Currency). Submit a PR to upstream.

4. Performance:

   • Cache enum instantiation for frequently used values:

     $cache = new \Symfony\Component\Cache\Adapter\ArrayAdapter();
     $country = $cache->get('country_US', fn() => CountryAlpha2::US);
     

5. Testing:

   • Use assertSame() for enum comparisons in tests:

     $this->assertSame(CountryAlpha2::US, CountryAlpha2::from('US'));
     

   • Test edge cases (e.g., deprecated entries, special regions like CountryAlpha2::Antarctica).