{"id":21189365,"url":"https://github.com/artnum/idz","last_synced_at":"2025-03-14T20:42:41.718Z","repository":{"id":237103893,"uuid":"793816989","full_name":"artnum/idz","owner":"artnum","description":"Humand readable (random or not) ID","archived":false,"fork":false,"pushed_at":"2024-12-10T15:22:56.000Z","size":14,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-21T13:25:35.576Z","etag":null,"topics":["creditor-reference","human-readable","id","nanoid","random","reference"],"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/artnum.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-29T23:28:12.000Z","updated_at":"2024-12-10T15:23:28.000Z","dependencies_parsed_at":"2024-05-02T09:43:39.297Z","dependency_job_id":"0ad9ee66-7399-45e7-bac2-557c34fa1448","html_url":"https://github.com/artnum/idz","commit_stats":null,"previous_names":["artnum/idz"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artnum%2Fidz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artnum%2Fidz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artnum%2Fidz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artnum%2Fidz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/artnum","download_url":"https://codeload.github.com/artnum/idz/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243646522,"owners_count":20324582,"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":["creditor-reference","human-readable","id","nanoid","random","reference"],"created_at":"2024-11-20T18:52:04.935Z","updated_at":"2025-03-14T20:42:41.685Z","avatar_url":"https://github.com/artnum.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IDZ - Human readable ID\n\nProvide human-readable ID with checksum. It avoids similar looking chars and\nadd a cheksum (crc8) at the end. When using random generation, it tries to avoid\nhaving two same characters in a row.\n\nRandom generator is inspired/comes from [nanoid](https://github.com/ai/nanoid).\n\nIt is a _trait_ with only static methods so it can be used to compose a class \nand be used without any class instances.\n\nUse this to generate ID like customer ID that would be exchange on the phone. ID\ncan be used in [Creditor Reference](https://en.wikipedia.org/wiki/Creditor_Reference)\nfor billing. Can be used for ticketing system or anything where the ID is exposed\nto a human and might be manipulated by human.\n\n## Why use this kind of ID ?\n\nThis has been developped to solve a problem that people living in a single-language\ncountry might not meet. But when your country is made of three languages, like\ngerman, french and italian, ID made of numbers can be confusing.\n\nFor example, in french, number like 97 can be said \"ninety seven\" (90 + 7) or\n\"four twenty seventeen\" (4 * 20 + 17). And when you are over the phone speaking \nto a german-speaking person trying to say \"018-197-4\" you could say \"zero eighteen\none hundred four twenty seventeen four\" or \"zero eighteen one hundred nine seven\nfour\" or goes \"zero one eight one nine seven four\", it might become quite messy :\ngerman-speaking people could have learned either \"ninety seven\" or \"four twenty \nseventeen\" version of 97 (depending of the school).\n\nGoing the version by spelling out each number individually can be a pain when you\nhave number like \"0010-1777-3770-0000\", repeating the same number several time\ngoes like \"zero zero one zero one seven seven seven, yes three times seven, three\nseven zero zero zero zero zero, yes that five times zero\".\n\nWith that kind of ID, you have 28 bits integer encoded in string like \n\"DCA-3U9-2CZ\", you have 7 ID charactes, 2 checksum characters which give us \na number of possibilites, as chars can be repeated in row, of 182'250'000, 16 *\n(15 ^ 6). Which is large enough for many application.\n\nFor example, Swiss social security number is in a form of _756.xxxx.xxxx.xcc_, 9 \nrandom int (x), a checksum (c) and 756 as country code ID, it is 1'000'000'000 \nposibilities. You can get more than twice the number of ID with the shorter\n_CH-xxxx-xxxx-cc_ : 16 * (15 ^ 7) = 2'733'750'000 and still be used in billing\nwith Creditor Reference. Unfortunately, the Swiss social security number was\nintroduced in 2019 so it's unlikely it will be soon replaced by this solution.\n\n## The alphabet\n\nThe choosen alphabet is\n\n  * **2** =\u003e 0x0, 0\n  * **3** =\u003e 0x1, 1\n  * **4** =\u003e 0x2, 2\n  * **5** =\u003e 0x3, 3\n  * **9** =\u003e 0x4, 4\n  * **A** =\u003e 0x5, 5\n  * **C** =\u003e 0x6, 6\n  * **D** =\u003e 0x7, 7\n  * **H** =\u003e 0x8, 8\n  * **L** =\u003e 0x9, 9\n  * **R** =\u003e 0xA, 10\n  * **T** =\u003e 0xB, 11\n  * **U** =\u003e 0xC, 12\n  * **X** =\u003e 0xD, 13\n  * **Y** =\u003e 0xE, 14\n  * **Z** =\u003e 0xF, 15\n\n## Usage\n\n```php\n\nclass MyUserClass {\n    use idz;\n    function create ($firstname, $lastname) {\n        /* 44 bits long id */\n        $id = $this-\u003egenerate(9); /* for example 4XT3ACHCA */\n        $this-\u003epdo-\u003eprepare('INSERT INTO usertable (id, lastname, firstname) VALUES(:id, :lastname, :firstname)');\n        /* db id is int 12265547877 */\n        $this-\u003epdo-\u003ebindValue(':id', $this-\u003etoint($id), PDO::PARAM_INT);\n        /* ... */\n\n        return $this-\u003eformat($id); /* return 4XT-3AC-HCA */\n    }\n}\n\n```\n\n## Documentation\n\nSource code is documented\n\n## Todo\n\n  * Unit test.\n  * Certainly bug fix.\n\n## License\n\n[MIT license](https://opensource.org/license/mit), see LICENSE file.\n\n## Authors\n\n  * Etienne Bagnoud \u003cetienne@artnum.ch\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fartnum%2Fidz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fartnum%2Fidz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fartnum%2Fidz/lists"}