Codice fiscale for Laravel

Overview

Version 3.0 is a ground-up rewrite: a domain core independent of Laravel, with immutable value objects and single-purpose services, plus a Laravel layer made of a validation rule, an Eloquent cast, a Faker provider and an artisan command. The core handles generation, parsing, validation, matching against a person and omocodia. Error messages are translated and bundled in English and Italian.

Birthplace data (Italian municipalities and foreign countries) is not bundled with the package: each installation downloads it with the codice-fiscale:update-places command. Until it has been run, semantic validation and birthplace lookups return «unknown».

Highlights

• «codice_fiscale» validation rule (format, checksum, semantics) and a fluent CodiceFiscaleRule::make()->matching() rule to cross-check against submitted name, date, birthplace and gender.
• Generating and parsing a codice fiscale (Generator, Parser), with automatic normalization of accents, apostrophes and whitespace in names.
• Omocodia handling: canonical form, level and all 128 possible variants of the same code.
• Eloquent cast, Faker provider and translated error messages, in English and Italian.
• Matching against a person with three explicit states: matched, mismatched or skipped, never counting a missing field as a pass.

Who it is for

For teams building with PHP and Laravel that need to validate, generate or parse the codice fiscale in forms or Eloquent models. The core can also be used outside Laravel.

Installation

Install with Composer; the service provider is auto-discovered. Then run the artisan command once to download birthplace data, and again to refresh it. A publishable config file is available.

composer require robertogallea/laravel-codicefiscale:^3.0

php artisan codice-fiscale:update-places

Read the README on GitHub

Points of attention

• Requirements: PHP ^8.2 and Laravel ^12.0 or ^13.0.
• Birthplace data is not shipped with the package and must be downloaded with update-places; without it, semantic validation returns «unknown».
• Version 3.0 is a deliberate clean break from 2.x with no compatibility shims; UPGRADE.md holds the migration table.

Can an agent use it?

AGENTS.md and CLAUDE.md are guidance for agents contributing to the repository code. No SKILL.md or MCP server found: this is a PHP library, not an agent tool.