Standards Laravel Package

Technical Evaluation

Architecture Fit

• Type Safety & Validation: The package leverages PHP 8.1+ enums to enforce strict type safety for international standards (ISO 3166, ISO 4217, etc.), aligning well with Laravel’s growing adoption of enums (e.g., Illuminate\Support\Enum). This reduces runtime errors by validating inputs early (e.g., country codes, currencies).
• Domain-Driven Design (DDD) Alignment: The interconnected enums (e.g., CountryAlpha2 ↔ CountryAlpha3 ↔ Currency) mirror real-world relationships, making it ideal for Laravel applications requiring geographic, linguistic, or financial data modeling (e.g., e-commerce, localization, or compliance systems).
• API/Contract Clarity: Enums enable clear API contracts (e.g., CountryAlpha2 $country in method signatures), improving IDE autocompletion and reducing ambiguity in documentation.

Integration Feasibility

• Laravel Compatibility:
  • Native PHP 8.1+: Laravel 9+ (PHP 8.1+) fully supports enums, ensuring seamless integration without polyfills.
  • Service Container: Enums can be bound in Laravel’s IoC container for dependency injection (e.g., app()->bind(CountryAlpha2::class, fn() => CountryAlpha2::from('US'))).
  • Eloquent Casting: Custom Eloquent attributes/casts can map database fields (e.g., country_code) to enums (e.g., CountryAlpha2).
• Database Schema:
  • Enum Backed Values: The package’s enums use string/integer backings (e.g., CountryAlpha2::US → 'US'), which map cleanly to database ENUM or VARCHAR columns.
  • Migration Helper: Laravel migrations can use Db::raw() to create ENUM columns (MySQL) or validate against enum values in unique/foreignKey constraints.
• Validation: Integrates with Laravel’s validator (e.g., Rule::in(array_column(CountryAlpha2::cases(), 'value'))) or custom rules extending Illuminate\Validation\Rule.

Technical Risk

• Breaking Changes:
  • SemVer Adherence: The package follows SemVer, but major versions may introduce enum renames or value changes (e.g., new country codes). Mitigate by:
    • Pinning to a minor version in composer.json (e.g., ^1.0).
    • Using feature flags or strats for deprecated enums during upgrades.
  • Dependency Conflicts: No direct Laravel dependencies, but risk of version conflicts with shared PHP packages (e.g., symfony/options-resolver used internally). Test with composer why-not and composer why.
• Performance:
  • Memory Usage: Enums are lightweight, but loading all standards (e.g., 250+ countries) at once may impact boot time. Lazy-load via service providers or cache loaded enums.
  • Database Queries: Avoid N+1 queries when fetching related data (e.g., currencies for a country). Use eager loading or denormalize data.
• Edge Cases:
  • Non-Standard Data: Some enums (e.g., CountrySubdivision) may require custom handling for regions not covered by ISO standards.
  • Locale-Specific Formatting: Methods like formatNumber() rely on user-provided locales; ensure your app handles fallback locales gracefully.

Key Questions

1. Use Cases:
   • Will this replace existing ad-hoc country/currency storage (e.g., raw strings in DB) or augment it?
   • Are there custom standards (e.g., internal region codes) that conflict with ISO enums?
2. Performance:
   • How many standards will be loaded per request? Can they be cached (e.g., Redis)?
   • Will enum conversions (e.g., CountryAlpha2 ↔ CountryNumeric) be frequent in hot paths?
3. Testing:
   • How will you test enum relationships (e.g., CountryAlpha3::NLD->getCurrencies()) in CI?
   • Are there edge cases (e.g., deprecated countries like CountryAlpha2::CS) that need handling?
4. Maintenance:
   • Who will monitor upstream updates (e.g., new country codes) and sponsor maintenance?
   • How will you handle schema migrations if enum values change (e.g., adding CountryAlpha2::XX)?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Enums: Native support in Laravel 9+; pair with spatie/laravel-enum for additional utilities (e.g., database casting).
  • Validation: Use prinsfrank/standards enums in Illuminate\Validation\Rules\Enum or custom rules.
  • Localization: Integrate with laravel-localization or spatie/laravel-translatable for language/country-specific content.
  • APIs: Serialize enums to JSON using JsonSerializable or custom JSON encoders (e.g., Illuminate\Support\Str::upper() for CountryAlpha2).
• Database:
  • MySQL: Use ENUM columns for backed values (e.g., country_code ENUM('US', 'CA', 'GB')).
  • PostgreSQL: Use TEXT columns with checks or DOMAIN constraints.
  • SQLite: Store as TEXT with application-level validation.
• Caching:
  • Cache enum collections (e.g., CountryAlpha2::cases()) in Redis or Laravel’s cache driver to avoid repeated instantiation.

Migration Path

1. Assessment Phase:
   • Audit existing country/currency/language storage (DB, configs, APIs).
   • Identify pain points (e.g., string-based codes, manual validation).
2. Pilot Integration:
   • Start with a single feature (e.g., country selection in user profiles).
   • Replace raw strings with enums in:
     • Eloquent models (e.g., country_code → CountryAlpha2 attribute).
     • API requests/responses (e.g., country: "US" → country: CountryAlpha2::US).
   • Use trait-based casting for gradual adoption:

     use PrinsFrank\Standards\Country\HasCountryAlpha2;
     
     class User extends Model {
         use HasCountryAlpha2;
     }
     

3. Full Adoption:
   • Replace all string-based standards with enums in:
     • Database schemas (add ENUM columns or backfill data).
     • Validation logic (e.g., Rule::in(CountryAlpha2::cases())).
     • Business logic (e.g., if ($order->country->isMemberOf(EU::class))).
   • Deprecate old string-based APIs with middleware or feature flags.

Compatibility

• Backward Compatibility:
  • Use accessors to maintain backward compatibility (e.g., getCountryCode() returning a string while storing CountryAlpha2).
  • Example:

    class Order extends Model {
        protected $country;
    
        public function getCountryCode(): string {
            return $this->country?->value ?? null;
        }
    
        public function setCountryCode(string $code): void {
            $this->country = CountryAlpha2::from($code);
        }
    }
    

• Fallbacks:
  • Handle invalid inputs gracefully (e.g., CountryAlpha2::tryFrom('XX')).
  • Provide default values for optional fields (e.g., CountryAlpha2::UNDEFINED).

Sequencing

1. Phase 1: Validation Layer
   • Replace manual string validation with enum-based rules.
   • Example:

     $validator = Validator::make($request->all(), [
         'country' => ['required', Rule::in(array_column(CountryAlpha2::cases(), 'value'))],
     ]);
     

2. Phase 2: Data Layer
   • Update Eloquent models to use enum attributes/casts.
   • Example:

     use Illuminate\Database\Eloquent\Casts\Attribute;
     
     class User extends Model {
         protected function country(): Attribute {
             return Attribute::make(
                 get: fn ($value) => CountryAlpha2::from($value),
                 set: fn ($value) => $value?->value,
             );
         }
     }
     

3. Phase 3: Business Logic
   • Replace hardcoded strings with enum methods (e.g., CountryAlpha3::NLD->getCurrencies()).
4. Phase 4: API Layer
   • Standardize enum serialization in API responses (e.g., always return CountryAlpha2::US->value).
   • Use Laravel’s JsonSerializable or custom encoders for complex enums (e.g., CountryAlpha3 with related data).

Operational Impact

Maintenance

• Upstream Updates:
  • Automated Checks: Monitor GitHub Actions for failed updates (e.g., update-spec-country.yml).
  • Manual Review: Sponsor maintenance to review breaking changes (e.g., new country codes) and update tests.
  • Changelog: Track changes in `UP