PHPackages reducktion/socrates - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Validation & Sanitization](/categories/validation) 4. / 5. reducktion/socrates ActiveLibrary[Validation & Sanitization](/categories/validation) reducktion/socrates =================== A package to validate, and extract citizen information from, national identification numbers. v2.0.0(3y ago)489.1k↑700%6[6 issues](https://github.com/reducktion/socrates/issues)[3 PRs](https://github.com/reducktion/socrates/pulls)MITPHPPHP ^8.1CI failing Since Jun 2Pushed 5mo ago3 watchersCompare [ Source](https://github.com/reducktion/socrates)[ Packagist](https://packagist.org/packages/reducktion/socrates)[ RSS](/packages/reducktion-socrates/feed)WikiDiscussions main Synced yesterday READMEChangelog (6)Dependencies (2)Versions (9)Used By (0) [![Socrates logo](./art/socrates.svg)](./art/socrates.svg) [![Usage example](./art/carbon.svg)](./art/carbon.svg) [![Badge](https://github.com/reducktion/socrates/actions/workflows/php.yml/badge.svg)](https://github.com/reducktion/socrates/actions/workflows/php.yml/badge.svg) [![Total Downloads](https://camo.githubusercontent.com/8a8070f0b633f19a8094c3cb59d935874ac7b33dbc8c2796f6021a37b05d3a96/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f72656475636b74696f6e2f736f637261746573)](https://camo.githubusercontent.com/8a8070f0b633f19a8094c3cb59d935874ac7b33dbc8c2796f6021a37b05d3a96/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f72656475636b74696f6e2f736f637261746573) [![Latest Version](https://camo.githubusercontent.com/97004f094b1a84706d274aa78961204691d6549ec89f67b48ceeac7b4b85f6fb/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f72656475636b74696f6e2f736f637261746573)](https://camo.githubusercontent.com/97004f094b1a84706d274aa78961204691d6549ec89f67b48ceeac7b4b85f6fb/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f72656475636b74696f6e2f736f637261746573) [![License](https://camo.githubusercontent.com/c0d042c684bd5162b8e6f446c8de1ae92e1f2219c231522c7864b701f6ff79a1/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f72656475636b74696f6e2f736f637261746573)](https://camo.githubusercontent.com/c0d042c684bd5162b8e6f446c8de1ae92e1f2219c231522c7864b701f6ff79a1/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f72656475636b74696f6e2f736f637261746573) [![StyleCI](https://camo.githubusercontent.com/987de1c642eb420ce55d501c35d36e919711e17131acbe15df1c810f4efdc54d/68747470733a2f2f6769746875622e7374796c6563692e696f2f7265706f732f3233383930303335302f736869656c643f6272616e63683d6d61696e)](https://camo.githubusercontent.com/987de1c642eb420ce55d501c35d36e919711e17131acbe15df1c810f4efdc54d/68747470733a2f2f6769746875622e7374796c6563692e696f2f7265706f732f3233383930303335302f736869656c643f6272616e63683d6d61696e) [![Contributors](https://camo.githubusercontent.com/4e96de37ea680371089642c8762ee051f42043eb64b50c4119a4e48970a2d434/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f616c6c5f636f6e7472696275746f72732d312d6f72616e67652e7376673f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/4e96de37ea680371089642c8762ee051f42043eb64b50c4119a4e48970a2d434/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f616c6c5f636f6e7472696275746f72732d312d6f72616e67652e7376673f7374796c653d666c61742d737175617265) --- Introduction ------------ [](#introduction) > I am a **Citizen of the World**, and my Nationality is Goodwill. **Socrates** is a PHP Package that allows you to validate and retrieve personal data from [National Identification Numbers](https://en.wikipedia.org/wiki/National_identification_number). Most countries in Europe are supported as well as some North and South American ones, with the goal to support as many countries in the world as possible. Some countries also encode personal information of the citizen, such as gender or the place of birth. This package allows you to extract that information in a consistent way. This package can be useful for many things such as validating a user's ID for finance related applications or verifying a user's age without asking for it explicitly. We recommend you review your country's data processing and protection laws before storing any information. [Ports](https://github.com/reducktion/socrates#ports) of this package to other languages are currently in progress. Check further below for which ones are currently available. PHP Version ----------- [](#php-version) PHP 8.1 is the minimum required version. If you are using an older version you should pull in the 1.3.0 version of this package. We highly recommend you upgrade though! Installation ------------ [](#installation) `composer require reducktion/socrates` Usage ----- [](#usage) Socrates provides two methods: `validateId` and `getCitizenDataFromId`. Both receive an ID and the country code as a backed enum with the [ISO 3166-2 format](https://en.wikipedia.org/wiki/ISO_3166-2) as the first and second parameters respectively. Simply instantiate the class and call the method you wish: ``` use Reducktion\Socrates\Socrates; use Reducktion\Socrates\Constants\Country; $socrates = new Socrates(); $socrates->validateId('14349483 0 ZV3', Country::Portugal); ``` ### validateId [](#validateid) This method will return true or false. In case the ID has a wrong character length an `InvalidLengthException` will be thrown. ``` if ($socrates->validateId('719102091', Country::Netherlands)) { echo 'Valid ID.'; } else { echo 'Invalid ID.'; } ``` ### getCitizenDataFromId [](#getcitizendatafromid) This method will return an instance of `Citizen`. If the ID is invalid, an `InvalidIdException` will be thrown. If the country does not support data extraction, an `UnsupportedOperationException` will be thrown. ``` $citizen = $socrates->getCitizenDataFromId('3860123012', Country::Estonia); ``` The `Citizen` class stores the extracted citizen data in a consistent format across all countries. It exposes the `getGender()`, `getDateOfBirth()`, `getAge()` and `getPlaceOfBirth()` methods. `getGender` will return an instance of the `Gender` enum. `getPlaceOfBirth` will return a city or region name as a `string`. `getAge()` returns the age of the citizen as an `int`. `getDateOfBirth()` returns a `DateTime` instance. Using the example above, Estonia only encodes the date of birth and gender of the citizen in their ID. So the above methods will return: ``` echo $citizen->getGender(); // 'Gender::Male' echo $citizen->getDateOfBirth(); // DateTime instance with the date '1986-01-23' echo $citizen->getAge(); // (The current age as a number) echo $citizen->getPlaceOfBirth(); // null - Estonia does not encode place of birth on its ID numbers ``` Supported and Unsupported Countries ----------------------------------- [](#supported-and-unsupported-countries) [Here](COUNTRIES.md) you can see the full list of supported countries and whether they support data extraction. Four european countries are currently unsupported: Austria πŸ‡¦πŸ‡Ή, Belarus πŸ‡§πŸ‡Ύ, Cyprus πŸ‡¨πŸ‡Ύ and Luxembourg πŸ‡±πŸ‡Ί. A number of countries in the Americas are also unsupported. This is because we could not find a reliable source for the algorithm, if at all. Help would be appreciated to get these countries supported. Testing ------- [](#testing) `composer test` Ports ----- [](#ports) This package is also available for the following languages: [Rust](https://github.com/reducktion/socrates-rs) [Java](https://github.com/reducktion/socrates-java) Contributing ------------ [](#contributing) Did you find a problem in any of the algorithms? Do you know how to implement a country which we have missed? Are there any improvements that you think should be made to the codebase? Any help is appreciated! Take a look at our [contributing guidelines](CONTRIBUTING.md). Code of Conduct --------------- [](#code-of-conduct) Our CoC is based on Ruby's. Check out [our code of conduct](CODE_OF_CONDUCT.md). License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. Credits ------- [](#credits) Socrates was made with πŸ’– by [Alexandre Olival](https://github.com/AlexOlival) and [JoΓ£o Cruz](https://github.com/JoaoFSCruz). We are Reducktion. We hope to make someone's life easier after all the hard work compiling, researching, reverse-engineering and agonizing over ID validation algorithms - many of which were very obscure and hard to find. Special Thanks -------------- [](#special-thanks) A big thanks goes to these people who helped us either test with real life IDs or guide us in finding the algorithm for their countries: - Alexandra from πŸ‡·πŸ‡΄ - Berilay from πŸ‡ΉπŸ‡· - Christian from πŸ‡¨πŸ‡­ - Domynikas from πŸ‡±πŸ‡Ή - Jeppe from πŸ‡©πŸ‡° - Jeremy from πŸ‡«πŸ‡· - Lisa from πŸ‡¬πŸ‡· - Miguel from πŸ‡ͺπŸ‡Έ and Nair from πŸ‡΅πŸ‡Ή for the package name. Contributors ✨ -------------- [](#contributors-) Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)): [![](https://avatars2.githubusercontent.com/u/7704656?v=4) **SLourenco**](https://github.com/SLourenco) [πŸ›](https://github.com/reducktion/socrates/issues?q=author%3ASLourenco "Bug reports") [πŸ“–](https://github.com/reducktion/socrates/commits?author=SLourenco "Documentation") [πŸ’»](https://github.com/reducktion/socrates/commits?author=SLourenco "Code") [![](https://avatars0.githubusercontent.com/u/471860?v=4) **FlΓ‘vio Heleno**](https://www.linkedin.com/in/flavioheleno/) [πŸ’»](https://github.com/reducktion/socrates/commits?author=flavioheleno "Code") [πŸ“–](https://github.com/reducktion/socrates/commits?author=flavioheleno "Documentation") [![](https://avatars1.githubusercontent.com/u/22393924?v=4) **Yves Bos**](https://github.com/YvesBos) [πŸ“–](https://github.com/reducktion/socrates/commits?author=YvesBos "Documentation") [πŸ’»](https://github.com/reducktion/socrates/commits?author=YvesBos "Code") [πŸ›](https://github.com/reducktion/socrates/issues?q=author%3AYvesBos "Bug reports") [![](https://avatars2.githubusercontent.com/u/54977705?v=4) **bofalke**](https://github.com/bofalke) [πŸ’»](https://github.com/reducktion/socrates/commits?author=bofalke "Code") [πŸ“–](https://github.com/reducktion/socrates/commits?author=bofalke "Documentation") [![](https://avatars1.githubusercontent.com/u/1103419?v=4) **Rodolpho Lima**](https://github.com/gheleri) [πŸ’»](https://github.com/reducktion/socrates/commits?author=gheleri "Code") [πŸ“–](https://github.com/reducktion/socrates/commits?author=gheleri "Documentation") [![](https://avatars1.githubusercontent.com/u/28356381?v=4) **tiagomichaelsousa**](https://github.com/tiagomichaelsousa) [πŸ’»](https://github.com/reducktion/socrates/commits?author=tiagomichaelsousa "Code") [πŸ“–](https://github.com/reducktion/socrates/commits?author=tiagomichaelsousa "Documentation") This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! ### Health Score 46 β€” FairBetter than 92% of packages Maintenance46 Moderate activity, may be stable Popularity37 Limited adoption so far Community17 Small or concentrated contributor base Maturity70 Established project with proven stability Bus Factor1 Top contributor holds 52.9% of commits β€” single point of failure How is this calculated?**Maintenance (25%)** β€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** β€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** β€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** β€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~180 days Recently: every ~223 days Total 6 Last Release 1320d ago Major Versions v1.3.0 β†’ v2.0.02022-11-21 PHP version history (3 changes)v1.0.0PHP ^7.2 v1.3.0PHP ^7.2|^8.0 v2.0.0PHP ^8.1 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/6274076?v=4)[Alexandre Almeida Olival](/maintainers/AlexOlival)[@AlexOlival](https://github.com/AlexOlival) ![](https://avatars.githubusercontent.com/u/26048679?v=4)[JoΓ£o Cruz](/maintainers/JoaoFSCruz)[@JoaoFSCruz](https://github.com/JoaoFSCruz) --- Top Contributors [![AlexOlival](https://avatars.githubusercontent.com/u/6274076?v=4)](https://github.com/AlexOlival "AlexOlival (127 commits)")[![JoaoFSCruz](https://avatars.githubusercontent.com/u/26048679?v=4)](https://github.com/JoaoFSCruz "JoaoFSCruz (103 commits)")[![allcontributors[bot]](https://avatars.githubusercontent.com/in/23186?v=4)](https://github.com/allcontributors[bot] "allcontributors[bot] (9 commits)")[![flavioheleno](https://avatars.githubusercontent.com/u/471860?v=4)](https://github.com/flavioheleno "flavioheleno (1 commits)") --- Tags composer-packagecountrieshacktoberfestidentification-numberidentitylaravelnational-id-validatorphpphp-packagesymfonyvalidationphplaravelvalidationpassportidentificationcitizenshipcitizennationality ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/reducktion-socrates/health.svg) ``` [![Health](https://phpackages.com/badges/reducktion-socrates/health.svg)](https://phpackages.com/packages/reducktion-socrates) ``` ### Alternatives [yorcreative/laravel-argonaut-dto Argonaut is a lightweight Data Transfer Object (DTO) package for Laravel that supports nested casting, recursive serialization, and validation out of the box. Ideal for service layers, APIs, and clean architecture workflows. 1063.4k2](/packages/yorcreative-laravel-argonaut-dto) PHPackages Β© 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)