- How do I install prinsfrank/standards in a Laravel project?
- Run composer require prinsfrank/standards in your project; the only requirement is PHP 8.1 or higher. There is no service provider, config file or publishable asset, because the package is a pure enum library with zero transitive dependencies. You can immediately import enums such as CountryAlpha2 or CurrencyAlpha3 in your code. Use the --dev flag if you only need the package for seeders and tests.
- Does this package require Laravel, and which Laravel and PHP versions are supported?
- The package does not require Laravel at all; it is framework-agnostic and works in any PHP 8.1+ codebase. In practice that means any Laravel release running on PHP 8.1 or newer, including Laravel 9, 10, 11 and 12. There are no Laravel version constraints, service providers or bootstrapping steps to manage, so upgrades of the framework never conflict with it.
- Which standards and enum types does the package actually cover?
- It covers ISO 3166 country codes and subdivisions, ISO 4217 currencies including SIX minor units and symbols, ISO 639 languages, IANA media types, timezones, TLDs and URI schemes, HTTP methods and status codes, and country groups. Each set is exposed as backed enums with helper methods for names, codes and relationships such as country to currency or language to script. The data is generated from authoritative upstream sources rather than hand-maintained arrays.
- How do I validate a country or currency code in a Laravel form request?
- Use Laravel's Rule::enum() rule with the relevant enum class, for example Rule::enum(CountryAlpha2::class), which rejects any value that is not a valid case. Because the rules work against backed values, a plain string from an API payload validates directly. There is no built-in normalizer, so trim whitespace and uppercase loose input before validating. For optional fields, wrap the rule in Rule::when() or add nullable.
- How do I cast a country or currency column to an enum on an Eloquent model?
- Add the enum to the model's $casts array, for example 'country' => CountryAlpha2::class, and Eloquent will hydrate the attribute as a typed enum instance. The database column stores the backed value, typically the alpha-2 or alpha-3 string, so existing schema and indexes keep working. When returning data through API resources, output ->value to serialize the canonical string rather than the enum case name. Queries should still filter on the raw value, for example where('country', CountryAlpha2::Netherlands->value).
- Are the enum case names stable between releases?
- No. Case names are generated from upstream human-readable names, so a territory rename or a changed qualifier can alter a case identifier and that only ships in a major release. In practice it is easy to miss in review, so avoid referencing case names directly in application code. Resolve enums with from() or tryFrom() against canonical values and persist and serialize the ->value. That keeps upstream renames from breaking your code.
- Can I replace my countries or currencies database table with this package?
- Not entirely. The enums are compile-time constant sets, not queryable data, so anything that needs list-all-where filtering, pagination, admin editing or foreign key relationships still wants a database table. The recommended pattern is to keep a reference table seeded from the enum cases and use the package as the source of truth for validation, transformation and lookups in code. That gives you type safety at the boundaries without losing SQL joins.
- How is the reference data kept up to date, and what happens if an upstream source changes?
- Dedicated GitHub Actions workflows pull from ISO, IANA, the SIX Group and the US Library of Congress daily, and the resulting diffs are reviewed manually before release. If an upstream site changes its presentation, parsing scripts have to be updated, so updates can pause while that is fixed. There is no SLA and the package is maintained by a single sponsorship-funded developer. Pin versions in composer.lock, review changelogs on bump, and remember the package is small enough to fork if needed.
- Will adding new enum cases break my tests or exhaustive match statements?
- Yes, potentially. New cases usually land in minor releases, and semver treats additive changes as non-breaking, but an exhaustive match without a default arm will throw and a snapshot test on Enum::cases() will fail. Assert on the specific cases you care about instead of asserting counts or full lists. Always give match statements a default arm, and treat every dependency bump as potentially breaking until your test suite says otherwise.
- Does the package provide localized country names, or just codes?
- The enums expose helper methods for names, codes and common relationships, and country names are available for a limited set of languages, but there is no full localization layer. If you need translated display names in every locale, use Laravel translation files or an ICU-backed library such as symfony/intl and treat the enums purely as the canonical identifier. Keep the enum value as your stored key so translations stay decoupled from the data source.