PHPackages spoorsny/south-african-id - 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. spoorsny/south-african-id ActiveLibrary[Validation & Sanitization](/categories/validation) spoorsny/south-african-id ========================= A self-validating value object encapsulating a South African government-issued personal identification number. v3.1.0(1y ago)0394↑44.4%[1 issues](https://github.com/spoorsny/php-south-african-id/issues)1GPL-3.0-or-laterPHPPHP ^8.3 Since Jul 9Pushed 1y ago1 watchersCompare [ Source](https://github.com/spoorsny/php-south-african-id)[ Packagist](https://packagist.org/packages/spoorsny/south-african-id)[ RSS](/packages/spoorsny-south-african-id/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (4)Dependencies (3)Versions (6)Used By (1) [![Repository Bannner](https://camo.githubusercontent.com/b36123d7c78e33897943a9820a3ccd467372f81161d7a5409ed8188fa95b0578/68747470733a2f2f62616e6e6572732e6265796f6e64636f2e64652f536f7574682532304166726963616e25323049442e706e673f7468656d653d6c69676874267061636b6167654d616e616765723d636f6d706f7365722b72657175697265267061636b6167654e616d653d73706f6f72736e79253246736f7574682d6166726963616e2d6964267061747465726e3d63697263756974426f617264267374796c653d7374796c655f31266465736372697074696f6e3d412b73656c662d76616c69646174696e672b76616c75652b6f626a6563742b656e63617073756c6174696e672b612b536f7574682b4166726963616e2b676f7665726e6d656e742d6973737565642b706572736f6e616c2b6964656e74696669636174696f6e2b6e756d6265722e266d643d312673686f7757617465726d61726b3d3126666f6e7453697a653d313030707826696d616765733d68747470732533412532462532467777772e7068702e6e6574253246696d616765732532466c6f676f732532466e65772d7068702d6c6f676f2e737667267769647468733d353030)](https://camo.githubusercontent.com/b36123d7c78e33897943a9820a3ccd467372f81161d7a5409ed8188fa95b0578/68747470733a2f2f62616e6e6572732e6265796f6e64636f2e64652f536f7574682532304166726963616e25323049442e706e673f7468656d653d6c69676874267061636b6167654d616e616765723d636f6d706f7365722b72657175697265267061636b6167654e616d653d73706f6f72736e79253246736f7574682d6166726963616e2d6964267061747465726e3d63697263756974426f617264267374796c653d7374796c655f31266465736372697074696f6e3d412b73656c662d76616c69646174696e672b76616c75652b6f626a6563742b656e63617073756c6174696e672b612b536f7574682b4166726963616e2b676f7665726e6d656e742d6973737565642b706572736f6e616c2b6964656e74696669636174696f6e2b6e756d6265722e266d643d312673686f7757617465726d61726b3d3126666f6e7453697a653d313030707826696d616765733d68747470732533412532462532467777772e7068702e6e6574253246696d616765732532466c6f676f732532466e65772d7068702d6c6f676f2e737667267769647468733d353030) [![Latest Version on Packagist](https://camo.githubusercontent.com/1d4ed55e101308f8ae24aa21c19530fd2be98dc39b2e23439968ff12e44acbc8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f73706f6f72736e792f736f7574682d6166726963616e2d69642e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spoorsny/south-african-id)[![Total Downloads](https://camo.githubusercontent.com/945b7a4b0dceea33054e4f2629ca26594b787a9c439f2836a168a8a0f978447e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f73706f6f72736e792f736f7574682d6166726963616e2d69642e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spoorsny/south-african-id)[![GitHub Tests Action Status](https://camo.githubusercontent.com/a9479d8eace676ce8c3d21f3e61a64f60dc98546395cf0f3ff47bd8d25203ff0/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f73706f6f72736e792f7068702d736f7574682d6166726963616e2d69642f636f6e74696e756f75732d696e746567726174696f6e2e796d6c3f6272616e63683d6d6173746572266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/spoorsny/php-south-african-id/actions?query=workflow%3Acontinuous-integration+branch%3Amaster)[![PHPUnit Code Coverage](https://github.com/spoorsny/php-south-african-id/raw/image-data/coverage.svg)](https://github.com/spoorsny/php-south-african-id/actions?query=workflow%3Acontinuous-integration+branch%3Amaster) South African ID for PHP ======================== [](#south-african-id-for-php) A self-validating value object encapsulating a South African government-issued personal [identification number](https://www.westerncape.gov.za/general-publication/decoding-your-south-african-id-number-0), for PHP. A South African government-issued identity number consists of **13** digits and the following segments: - **birth date:** the first **6** digits represent the person's date of birth in the format *yymmdd*. - **gender:** the next **4** digits indicate that the person is male if the value is **5000** or above; otherwise, female. - **citizenship:** the next single digit shows the person's citizenship status: 0 for a citizen, **1** for a permanent resident. - **race:** the next single digit was historically used to indicate the person's race. - **check digit:** the last digit is used to validate the entire number, to protect against typing errors. It is calculated with the [Luhn Algorithm](https://en.wikipedia.org/wiki/Luhn_algorithm). Install ------- [](#install) Use [Composer](https://getcomposer.org) to install the package. ``` composer require spoorsny/south-african-id ``` Usage ----- [](#usage) The value object can be instantiated by passing a string to its constructor. ``` use Spoorsny\ValueObjects\SouthAfricanId; $idNumber = new SouthAfricanId('9308062469083'); ``` If the string argument is not in the valid format, an `InvalidArgumentException` with a message indicative of the type of error, will be thrown. The value object can used in places where strings are used, because it implements the [`Stringable`](https://php.net/Stringable) interface. For example, a value object can be instantiated by passing another instance to its constructor. ``` $idNumber1 = new SouthAfricanId('4608162219097'); $idNumber2 = new SouthAfricanId($idNumber1); ``` Note The value object always formats the identity number with a single space between the date segment and the gender segment, and a single space between the gender segment and the citizenship segment. It can be used with the `strval()` function and `echo` statement. ``` $idNumber = new SouthAfricanId('4608162219097'); strval($idNumber); // Evaluates to '460816 2219 097'. echo $idNumber; // Prints '460816 2219 097'. ``` Different instances of the class can be checked for equality with the `equals()`method. ``` $idNumber1 = new SouthAfricanId('4608162219097'); $idNumber2 = new SouthAfricanId('4608162219097'); $idNumber3 = new SouthAfricanId('8202277454090'); $idNumber1->equals($idNumber2); // true $idNumber1->equals($idNumber3); // false ``` Even though the identity number starts with the person's birth date, it cannot be used to compare whether one person is older than another. This is due to the century portion being missing from the date. Useful information encoded in the identity number can be extracted, for example: ``` $idNumber->birthMonth(); $idNumber->birthDay(); $idNumber->isFemale(); $idNumber->isMale(); $idNumber->isCitizen(); $idNumber->isPermanentResident(); ``` The different segments of the identity number can be extracted from the value object as follows: ``` $idNumber->dateSegment(); $idNumber->genderSegment(); $idNumber->citizenshipSegment(); $idNumber->raceSegment(); $idNumber->checksumSegment(); ``` Contributing ------------ [](#contributing) To contribute to the package, see the [Contributing Guide](CONTRIBUTING.md). License ------- [](#license) Copyright © 2024 Geoffrey Bernardo van Wyk This file is part of package spoorsny/south-african-id. Package spoorsny/south-african-id is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. Package spoorsny/south-african-id is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with package spoorsny/south-african-id. If not, see . For a copy of the license, see the [LICENSE](LICENSE) file in this repository. ### Health Score 33 — LowBetter than 75% of packages Maintenance34 Infrequent updates — may be unmaintained Popularity17 Limited adoption so far Community9 Small or concentrated contributor base Maturity59 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% 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 ~7 days Total 5 Last Release 644d ago Major Versions v0.1.0 → v1.0.02024-07-12 v1.0.0 → v2.0.02024-08-02 v2.0.0 → v3.0.02024-08-02 ### Community Maintainers ![](https://www.gravatar.com/avatar/3f655900aa4d2538ee47a2c32177238d5d8c9bd2847fc91e7b08d26315f27a3f?d=identicon)[geoffreyvanwyk](/maintainers/geoffreyvanwyk) --- Top Contributors [![geoffreyvanwyk](https://avatars.githubusercontent.com/u/194185?v=4)](https://github.com/geoffreyvanwyk "geoffreyvanwyk (55 commits)") --- Tags identity-numbersouth-africavalue-objectValue ObjectID numberidentity numberspoorsnysouth africanidnumber ### Code Quality TestsPHPUnit Code StylePHP CS Fixer ### Embed Badge ![Health badge](/badges/spoorsny-south-african-id/health.svg) ``` [![Health](https://phpackages.com/badges/spoorsny-south-african-id/health.svg)](https://phpackages.com/packages/spoorsny-south-african-id) ``` ### Alternatives [webmozart/assert Assertions to validate method input/output with nice error messages. 7.6k894.0M1.2k](/packages/webmozart-assert)[swaggest/json-schema High definition PHP structures with JSON-schema based validation 48612.5M73](/packages/swaggest-json-schema)[stevebauman/purify An HTML Purifier / Sanitizer for Laravel 5325.6M19](/packages/stevebauman-purify)[ashallendesign/laravel-config-validator A package for validating your Laravel app's config. 217905.3k5](/packages/ashallendesign-laravel-config-validator)[crazybooot/base64-validation Laravel validators for base64 encoded files 1341.9M8](/packages/crazybooot-base64-validation)[xemlock/htmlpurifier-html5 HTML5 support for HTML Purifier 1052.9M11](/packages/xemlock-htmlpurifier-html5) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)