{"id":20081727,"url":"https://github.com/theiconic/name-parser","last_synced_at":"2025-04-04T21:06:33.685Z","repository":{"id":31685121,"uuid":"35250697","full_name":"theiconic/name-parser","owner":"theiconic","description":"A universal, language-independent name parser PHP library","archived":false,"fork":false,"pushed_at":"2021-12-29T00:19:37.000Z","size":167,"stargazers_count":126,"open_issues_count":19,"forks_count":30,"subscribers_count":69,"default_branch":"master","last_synced_at":"2025-04-01T02:36:10.439Z","etag":null,"topics":["names","php","string-parsing"],"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/theiconic.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}},"created_at":"2015-05-08T00:45:11.000Z","updated_at":"2025-03-29T19:47:39.000Z","dependencies_parsed_at":"2022-08-24T10:20:08.261Z","dependency_job_id":null,"html_url":"https://github.com/theiconic/name-parser","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theiconic%2Fname-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theiconic%2Fname-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theiconic%2Fname-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theiconic%2Fname-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theiconic","download_url":"https://codeload.github.com/theiconic/name-parser/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247237923,"owners_count":20906364,"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":["names","php","string-parsing"],"created_at":"2024-11-13T15:40:06.940Z","updated_at":"2025-04-04T21:06:33.660Z","avatar_url":"https://github.com/theiconic.png","language":"PHP","readme":"# THE ICONIC Name Parser\n\n[![Build Status](https://travis-ci.org/theiconic/name-parser.svg?branch=master\u0026t=201705161308)](https://travis-ci.org/theiconic/name-parser)\n[![Coverage Status](https://coveralls.io/repos/github/theiconic/name-parser/badge.svg?branch=master\u0026t=201705161308)](https://coveralls.io/github/theiconic/name-parser?branch=master)\n[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/theiconic/name-parser/badges/quality-score.png?b=master\u0026t=201705161308)](https://scrutinizer-ci.com/g/theiconic/name-parser/?branch=master)\n[![Latest Stable Version](https://poser.pugx.org/theiconic/name-parser/v/stable?t=201705161308)](https://packagist.org/packages/theiconic/name-parser)\n[![Total Downloads](https://poser.pugx.org/theiconic/name-parser/downloads?t=201705161308)](https://packagist.org/packages/theiconic/name-parser)\n[![License](https://poser.pugx.org/theiconic/name-parser/license?t=201705161308)](https://packagist.org/packages/theiconic/name-parser)\n\n## Purpose\nThis is a universal, language-independent name parser.\n\nIts purpose is to split a single string containing a full name,\npossibly including salutation, initials, suffixes etc., into\nmeaningful parts like firstname, lastname, initials, and so on.\n\nIt is mostly tailored towards english names but works pretty well\nwith non-english names as long as they use latin spelling.\n\nE.g. **Mr Anthony R Von Fange III** is parsed to\n- salutation: **Mr.**\n- firstname: **Anthony**\n- initials: **R**\n- lastname: **von Fange**\n- suffix: **III**\n\nThis package has been used by The Iconic in production for years,\nsuccessfully processing hundreds of thousands of customer names.\n\n## Features\n\n### Supported patterns\nThis parser is able to handle name patterns with and without comma:\n```\n... [firstname] ... [lastname] ...\n```\n```\n... [lastname] ..., ... [firstname] ...\n```\n```\n... [lastname] ..., ... [firstname] ..., [suffix]\n```\n\n### Supported parts\n- salutations (e.g. Mr, Mrs, Dr, etc.)\n- first name\n- middle names\n- initials (single letters, possibly followed by a dot)\n- nicknames (parts within parenthesis, brackets etc.)\n- last names (also supports prefixes like von, de etc.)\n- suffixes (Jr, Senior, 3rd, PhD, etc.)\n\n### Other features\n- multi-language support for salutations, suffixes and lastname prefixes\n- customizable nickname delimiters\n- customizable normalisation of all output strings\n  (original values remain accessible)\n- customizable whitespace\n\n## Examples\n\nMore than 60 different successfully parsed name patterns can be found in the\n[parser unit test](https://github.com/theiconic/name-parser/blob/master/tests/ParserTest.php#L12-L12).\n\n## Setup\n```$xslt\ncomposer require theiconic/name-parser\n```\n\n## Usage\n\n### Basic usage\n```php\n\u003c?php\n\n$parser = new TheIconic\\NameParser\\Parser();\n\n$name = $parser-\u003eparse($input);\n\necho $name-\u003egetSalutation();\necho $name-\u003egetFirstname();\necho $name-\u003egetLastname();\necho $name-\u003egetMiddlename();\necho $name-\u003egetNickname();\necho $name-\u003egetInitials();\necho $name-\u003egetSuffix();\n\nprint_r($name-\u003egetAll());\n\necho $name;\n```\nAn empty string is returned for missing parts.\n\n### Special part retrieval features\n#### Explicit last name parts\nYou can retrieve last name prefixes and pure last names separately with\n```php\necho $name-\u003egetLastnamePrefix();\necho $name-\u003egetLastname(true); // true enables strict mode for pure lastnames, only\n```\n\n#### Nick names with normalized wrapping\nBy default, `getNickname()` returns the pure string of nick names. However, you can\npass `true` to have the same normalised parenthesis wrapping applied as in `echo $name`:\n```php\necho $name-\u003egetNickname(); // The Giant\necho $name-\u003egetNickname(true); // (The Giant)\n```\n\n#### Re-print given name in the order as entered\nYou can re-print the parts that form a given name (that is first name, middle names and any initials)\nin the order they were entered in while still applying normalisation\nvia `getGivenName()`:\n```php\necho $name-\u003egetGivenName(); // J. Peter M.\n```\n\n#### Re-print full name (actual name parts only)\nYou can re-print the full name, that is the given name as above followed by\nany last name parts (excluding any salutations, nick names or suffixes)\nvia `getFullName()`:\n```php\necho $name-\u003egetFullName(); // J. Peter M. Schluter\n```\n\n### Setting Languages\n```php\n$parser = new TheIconic\\NameParser\\Parser([\n    new TheIconic\\NameParser\\Language\\English(), //default\n    new TheIconic\\NameParser\\Language\\German(),\n])\n```\n\n### Setting nickname delimiters\n```php\n$parser = new TheIconic\\NameParser\\Parser();\n$parser-\u003esetNicknameDelimiters(['(' =\u003e ')']);\n```\n\n### Setting whitespace characters\n```php\n$parser = new TheIconic\\NameParser\\Parser();\n$parser-\u003esetWhitespace(\"\\t _.\");\n```\n\n### Limiting the position of salutations\n```php\n$parser = new TheIconic\\NameParser\\Parser();\n$parser-\u003esetMaxSalutationIndex(2);\n```\nThis will require salutations to appear within the\nfirst two words of the given input string.\nThis defaults to half the amount of words in the input string,\nmeaning that effectively the salutation may occur within\nthe first half of the name parts.\n\n### Adjusting combined initials support\n```php\n$parser = new TheIconic\\NameParser\\Parser();\n$parser-\u003esetMaxCombinedInitials(3);\n```\nCombined initials are combinations of several\nuppercased letters, e.g. `DJ` or `J.T.` without\nseparating spaces. The parser will treat such sequences\nof uppercase letters (with optional dots) as combined\ninitials and parse them into individual initials.\nThis value adjusts the maximum number of uppercase letters\nin a single name part are recognised as comnined initials.\nParts with more than the specified maximum amount of letters\nwill not be parsed into initials and hence will most likely\nbe parsed into first or middle names.\n\nThe default value is 2.\n\nTo disable combined initials support, set this value to 1;\n\n## Tips\n### Provide clean input strings\nIf your input string consists of more than just the name and\ndirectly related bits like salutations, suffixes etc.,\nany additional parts can easily confuse the parser.\nIt is therefore recommended to pre-process any non-clean input\nto isolate the name before passing it to the parser.\n\n### Multi-pass parsing\nWe have not played with this, but you may be able to improve results\nby chaining several parses in sequence. E.g.\n```php\n$parser = new Parser();\n$name = $parser-\u003eparse($input);\n$name = $parser-\u003eparse((string) $name);\n...\n```\nYou can even compose your new input string from individual parts of\na previous pass.\n\n### Dealing with names in different languages\nThe parser is primarily built around the patterns of english names\nbut tries to be compatible with names in other languages. Problems\noccur with different salutations, last name prefixes, suffixes etc.\nor in some cases even with the parsing order.\n\nTo solve problems with salutations, last name prefixes and suffixes\nyou can create a separate language definition file and inject it when\ninstantiating the parser, see 'Setting Languages' above and compare\nthe existing language files as examples.\n\nTo deal with parsing order you may want to reformat the input string,\ne.g. by simply splitting it into words and reversing their order.\nYou can even let the parser run over the original string and then over\nthe reversed string and then pick the best results from either of the\ntwo resulting name objects. E.g. the salutation from the one and the\nlastname from the other.\n\nThe name parser has no in-built language detection. However, you may\nalready ask the user for their nationality in the same form. If you\ndo that you may want to narrow the language definition files passed\ninto the parser to the given language and maybe a fallback like english.\nYou can also use this information to prepare the input string as outlined\nabove.\n\nAlternatively, Patrick Schur as a [PHP language detection library](https://github.com/patrickschur/language-detection)\nthat seems to deliver astonishing results. It won't give you much luck if\nyou run it over the the name input string only, but if you have any more\ntext from the person in their actual language, you could use this to detect\nthe language and then proceed as above.\n\n### Gender detection\nGender detection is outside the scope of this project.\nDetecting the gender from a name often requires large lists of first\nname to gender mappings.\n\nHowever, you can use this parser to extract salutation, first name and\nnick names from the input string and then use these to implement gender\ndetection using another package (e.g. [this one](https://github.com/tuqqu/gender-detector)) or service.\n\n### Having fun with normalisation\nWriting different language files can not only be useful for parsing,\nbut you can remap the normalised versions of salutations, prefixes and suffixes\nto transform them into something totally different.\n\nE.g. you could map `Ms.` to `princess of the kingdom of` and then output\nthe parts in appropriate order to build a pipeline that automatically transforms\ne.g. `Ms. Louisa Lichtenstein` into `Louisa, princess of the kingdom of Lichtenstein`.\nOf course, this is a silly and rather contrived example, but you get the\ngist.\n\nOf course this can also be used in more useful ways, e.g. to spell out\nabbreviated titles, like `Prof.` as `Professor` etc. .\n\n## License\n\nTHE ICONIC Name Parser library for PHP is released under the MIT License.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheiconic%2Fname-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheiconic%2Fname-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheiconic%2Fname-parser/lists"}