{"id":21556973,"url":"https://github.com/reducktion/socrates","last_synced_at":"2025-04-10T10:22:53.374Z","repository":{"id":54642034,"uuid":"238900350","full_name":"reducktion/socrates","owner":"reducktion","description":"PHP package to Validate and Extract information from National Identification Numbers.","archived":false,"fork":false,"pushed_at":"2022-11-23T12:33:02.000Z","size":1194,"stargazers_count":46,"open_issues_count":5,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-24T09:11:30.220Z","etag":null,"topics":["composer-package","countries","hacktoberfest","identification-number","identity","laravel","national-id-validator","php","php-package","symfony","validation"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/reducktion.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-02-07T10:49:48.000Z","updated_at":"2025-03-24T01:09:38.000Z","dependencies_parsed_at":"2023-01-23T14:15:51.276Z","dependency_job_id":null,"html_url":"https://github.com/reducktion/socrates","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reducktion%2Fsocrates","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reducktion%2Fsocrates/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reducktion%2Fsocrates/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reducktion%2Fsocrates/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/reducktion","download_url":"https://codeload.github.com/reducktion/socrates/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248199079,"owners_count":21063641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["composer-package","countries","hacktoberfest","identification-number","identity","laravel","national-id-validator","php","php-package","symfony","validation"],"created_at":"2024-11-24T08:10:33.897Z","updated_at":"2025-04-10T10:22:53.352Z","avatar_url":"https://github.com/reducktion.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"./art/socrates.svg\" alt=\"Socrates logo\" width=\"480\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"./art/carbon.svg\" alt=\"Usage example\" width=\"800\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n    \u003cimg alt=\"Badge\" src=\"https://github.com/reducktion/socrates/actions/workflows/php.yml/badge.svg\"\u003e\n    \u003cimg alt=\"Total Downloads\" src=\"https://img.shields.io/packagist/dt/reducktion/socrates\"\u003e\n    \u003cimg alt=\"Latest Version\" src=\"https://img.shields.io/packagist/v/reducktion/socrates\"\u003e\n    \u003cimg alt=\"License\" src=\"https://img.shields.io/github/license/reducktion/socrates\"\u003e\n    \u003cimg alt=\"StyleCI\" src=\"https://github.styleci.io/repos/238900350/shield?branch=main\"\u003e\n    \u003cimg alt=\"Contributors\" src=\"https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square\"\u003e\n\u003c/p\u003e\n\n------\n## Introduction\n\u003eI am a **Citizen of the World**, and my Nationality is Goodwill.\n\n**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).\nMost 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.\n\u003cp\u003eSome 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.\u003c/p\u003e\n\n\u003cp\u003eThis 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.\u003c/p\u003e\n\n[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.\n\n## PHP Version\n\u003cp\u003ePHP 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!\u003c/p\u003e\n\n## Installation\n`composer require reducktion/socrates`\n\n## Usage\nSocrates 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:\n\n```php\nuse Reducktion\\Socrates\\Socrates;\nuse Reducktion\\Socrates\\Constants\\Country;\n\n$socrates = new Socrates();\n$socrates-\u003evalidateId('14349483 0 ZV3', Country::Portugal);\n```\n\n### validateId\nThis method will return true or false.\nIn case the ID has a wrong character length an `InvalidLengthException` will be thrown.\n\n```php\nif ($socrates-\u003evalidateId('719102091', Country::Netherlands)) {\n    echo 'Valid ID.';\n} else {\n    echo 'Invalid ID.';\n}\n```\n\n### getCitizenDataFromId\nThis method will return an instance of `Citizen`.\u003cbr\u003e\nIf the ID is invalid, an `InvalidIdException` will be thrown.\u003cbr\u003e\nIf the country does not support data extraction, an `UnsupportedOperationException` will be thrown.\n\n```php\n$citizen = $socrates-\u003egetCitizenDataFromId('3860123012', Country::Estonia);\n```\n\nThe `Citizen` class stores the extracted citizen data in a consistent format across all countries.\u003cbr\u003e\nIt exposes the `getGender()`, `getDateOfBirth()`, `getAge()` and `getPlaceOfBirth()` methods.\u003cbr\u003e\u003cbr\u003e\n`getGender` will return an instance of the `Gender` enum.\u003cbr\u003e \n`getPlaceOfBirth` will return a city or region name as a `string`.\u003cbr\u003e\n`getAge()` returns the age of the citizen as an `int`.\u003cbr\u003e\n`getDateOfBirth()` returns a `DateTime` instance.\u003cbr\u003e\n\u003cp\u003eUsing the example above, Estonia only encodes the date of birth and gender of the citizen in their ID. So the above methods will return:\u003c/p\u003e\n \n```php\necho $citizen-\u003egetGender(); // 'Gender::Male'\necho $citizen-\u003egetDateOfBirth(); // DateTime instance with the date '1986-01-23'\necho $citizen-\u003egetAge(); // (The current age as a number)\necho $citizen-\u003egetPlaceOfBirth(); // null - Estonia does not encode place of birth on its ID numbers\n```\n\n## Supported and Unsupported Countries\n\n[Here](COUNTRIES.md) you can see the full list of supported countries and whether they support data extraction.\n\nFour european countries are currently unsupported: Austria 🇦🇹, Belarus 🇧🇾, Cyprus 🇨🇾 and Luxembourg 🇱🇺.\nA 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.\n\n## Testing\n`composer test`\n\n## Ports\nThis package is also available for the following languages:\n\n[Rust](https://github.com/reducktion/socrates-rs)\u003cbr\u003e\n[Java](https://github.com/reducktion/socrates-java)\n\n## Contributing\n\nDid you find a problem in any of the algorithms? \nDo you know how to implement a country which we have missed?\nAre there any improvements that you think should be made to the codebase?\nAny help is appreciated! Take a look at our [contributing guidelines](CONTRIBUTING.md).\n\n## Code of Conduct\nOur CoC is based on Ruby's. Check out [our code of conduct](CODE_OF_CONDUCT.md).\n\n## License\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n\n## Credits\nSocrates was made with 💖 by [Alexandre Olival](https://github.com/AlexOlival)  and [João Cruz](https://github.com/JoaoFSCruz). \nWe are Reducktion.\nWe 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.\n\n## Special Thanks\nA 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:\n* Alexandra from 🇷🇴\n* Berilay from 🇹🇷\n* Christian from 🇨🇭\n* Domynikas from 🇱🇹\n* Jeppe from 🇩🇰\n* Jeremy from 🇫🇷 \n* Lisa from 🇬🇷\n* Miguel from 🇪🇸\n\nand Nair from 🇵🇹 for the package name.\n\n## Contributors ✨\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/SLourenco\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/7704656?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eSLourenco\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/reducktion/socrates/issues?q=author%3ASLourenco\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e \u003ca href=\"https://github.com/reducktion/socrates/commits?author=SLourenco\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"https://github.com/reducktion/socrates/commits?author=SLourenco\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://www.linkedin.com/in/flavioheleno/\"\u003e\u003cimg src=\"https://avatars0.githubusercontent.com/u/471860?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eFlávio Heleno\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/reducktion/socrates/commits?author=flavioheleno\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/reducktion/socrates/commits?author=flavioheleno\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/YvesBos\"\u003e\u003cimg src=\"https://avatars1.githubusercontent.com/u/22393924?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eYves Bos\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/reducktion/socrates/commits?author=YvesBos\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"https://github.com/reducktion/socrates/commits?author=YvesBos\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/reducktion/socrates/issues?q=author%3AYvesBos\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/bofalke\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/54977705?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003ebofalke\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/reducktion/socrates/commits?author=bofalke\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/reducktion/socrates/commits?author=bofalke\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/gheleri\"\u003e\u003cimg src=\"https://avatars1.githubusercontent.com/u/1103419?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eRodolpho Lima\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/reducktion/socrates/commits?author=gheleri\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/reducktion/socrates/commits?author=gheleri\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/tiagomichaelsousa\"\u003e\u003cimg src=\"https://avatars1.githubusercontent.com/u/28356381?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003etiagomichaelsousa\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/reducktion/socrates/commits?author=tiagomichaelsousa\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/reducktion/socrates/commits?author=tiagomichaelsousa\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-enable --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freducktion%2Fsocrates","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freducktion%2Fsocrates","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freducktion%2Fsocrates/lists"}