robertogallea/laravel-codicefiscale/using-laravel-codicefiscale

Using laravel-codicefiscale

Full API reference with runnable examples: README.md at this package's root. This skill is a map to it, not a replacement for it - read the relevant README section before writing code against an API you haven't confirmed.

Reach for these, don't hand-roll them

• `CodiceFiscale::from()`/`::tryFrom()` - an immutable value object; the only way to hold a codice fiscale. Checks structure only, not checksum/semantics.
• `Generator` - builds a CodiceFiscale from a Person DTO (Robertogallea\CodiceFiscale\Data\Person, with a BirthPlaceCode, not a name or string).
• `Parser` - decodes a CodiceFiscale into its parts. surnameCode()/nameCode() are 3-character encoded fragments, never the person's real name - there is no way to recover it. birthDate()/birthYear() are nullable: the two-digit year is inherently ambiguous between two candidate centuries, resolved via a swappable Contracts\BirthDateResolver (default DefaultBirthDateResolver); both are null when neither candidate is plausible. See README's "Reference-date resolution". birthPlace() returns the attributable era - the one valid on the birth date, else the earliest instituted after it - since the tax authority assigns codes as of issue time; it is null only for an unknown code or one that had ceased before the birth date.
• `Validator` - checks format, checksum, and semantics as independently-callable tiers; never accepts a Person. Returns a ValidationResult with a ValidationError enum, not exceptions. Semantics judge the birthplace by attributability (README "Birthplace attributability"): a code instituted after the birth date passes; BirthPlaceNotValidOnDate means every era of the code ended before the birth date.
• `Matcher` - cross-checks a CodiceFiscale against a Person or PartialPerson. This is the only place a codice fiscale gets compared to a person - Validator never does this.
• `Omocodia` - canonical(), level(), variants() for the digit/letter substitution scheme used to resolve collisions.
• Birthplace domain - Contracts\BirthPlaceRepository (find(), eras(), search()) backed by real ANPR/MAECI government data via codice-fiscale:update-places, not a static list. To check whether a code exists at all, use eras($code) !== [] - existedEver() is deprecated since 3.1.0. search() resolves a typed name to candidate BirthPlaceCodes; it never feeds back into generation.

Laravel-specific

• codice_fiscale validation rule (format/checksum/semantics), or the fluent CodiceFiscaleRule::make()->matching(...) to cross-check other request fields.
• CodiceFiscaleCast for an Eloquent attribute typed as CodiceFiscale.
• fake()->codiceFiscale() Faker provider - always a random, valid, fully-generated code; not for a specific person.
• php artisan codice-fiscale:update-places - required once before any semantic validation or birthplace lookup will succeed. Never touches the host application's own database.

Before writing code

1. Confirm whether the target application is actually on 3.x - if you find calls like ->getFirstName(), ->parse(), ::generate($string, ...), or the robertogallea\LaravelCodiceFiscale\* namespace, that's 2.x; switch to the upgrading-laravel-codicefiscale-from-v2 skill instead of applying 3.x guidance to it.
2. Read the specific README.md section for the API you're about to use - the signatures above are a map, not the full contract.