Documentation

NameParser extends AbstractParser
in package

Pop

Parser

Name parser class

Properties

$data : mixed: Data to parse
$error : bool: Error flag
$errorMessage : string|null: Error message
$firstname : string|null: First name
$initials : string|null: Initials
$initialsQueue : array<string|int, mixed>: Queue of raw tokens claimed as initials during extraction, before the first one is (potentially) promoted back to firstname by finalizeInitials()
$lastname : string|null: Last name
$lastnamePrefix : string|null: Lastname prefix
$middlename : string|null: Middle name
$nickname : string|null: Nickname
$result : mixed: Parsed result
$salutation : string|null: Salutation
$suffix : string|null: Suffix

Methods

__construct() : mixed: Constructor
__toString() : string: To string method
clean() : string: Clean method
getData() : mixed: Get data
getErrorMessage() : string|null: Get error message
getFirstname() : string|null: Method to get first name
getFullName() : string|null: Method to get the full name (given name plus lastname prefix and lastname)
getGivenName() : string|null: Method to get the given name (first name, initials and middle name, in that order)
getInitials() : string|null: Method to get initials
getLastname() : string|null: Method to get last name
getLastnamePrefix() : string|null: Method to get lastname prefix
getMiddlename() : string|null: Method to get middle name
getNickname() : string|null: Method to get nickname
getResult() : mixed: Get parsed result
getSalutation() : string|null: Method to get salutation
getSuffix() : string|null: Method to get suffix
hasError() : bool: Check if there is an error
hasFirstname() : bool: Has first name
hasInitials() : bool: Has initials
hasLastname() : bool: Has last name
hasLastnamePrefix() : bool: Has lastname prefix
hasMiddlename() : bool: Has middle name
hasNickname() : bool: Has nickname
hasSalutation() : bool: Has salutation
hasSuffix() : bool: Has suffix
parse() : static: Parse method
setData() : static: Set data
toArray() : array<string|int, mixed>: To array method
absorbLeftovers() : void: Absorb any tokens no extraction step claimed: the first time this is called with a non-empty leftover, it becomes firstname (since every name needs one); after that, leftovers are appended to middlename. This is a deliberate difference from theiconic/name-parser, which can silently drop an unrecognized leading word (e.g. "The" in "The Rev. Mark Williams") - here nothing is ever discarded.
extractFirstname() : array<string|int, mixed>: Extract firstname
extractInitials() : array<string|int, mixed>: Extract initials
extractLastname() : array<string|int, mixed>: Extract lastname (with prefix folding)
extractMiddlename() : array<string|int, mixed>: Extract middlename
extractNickname() : array<string|int, mixed>: Extract nickname
extractSalutation() : array<string|int, mixed>: Extract salutation
extractSuffix() : array<string|int, mixed>: Extract suffix
finalizeInitials() : void: If no raw token ever became firstname but one or more initials were set aside, promote the FIRST claimed initial back to firstname - handles "J. B. Hunt" (firstname="J.", initials="B.", lastname="Hunt"), since a name consisting only of initials plus a lastname still needs a firstname.
normalizeCase() : string: Normalize the case of a single word: an all-uppercase or all-lowercase word gets title-cased ("MACDONALD" / "macdonald" -> "Macdonald"); a word with any existing mixed case (e.g. "MacDonald", "McDonald", "O'Brien") is left exactly as typed, since that mixed case is almost always deliberate.
normalizeWords() : string: Normalize the case of each word in an array and join them with a space
parseCommaMode() : void: Parse comma-separated "Last, First Middle[, Suffix]" format
tokenize() : array<string|int, mixed>: Tokenize method

$data

Data to parse


        protected
            mixed
    $data
     = null

$error

Error flag


        protected
            bool
    $error
     = false

$errorMessage

Error message


        protected
            string|null
    $errorMessage
     = null

$firstname

First name


        protected
            string|null
    $firstname
     = null

$initials

Initials


        protected
            string|null
    $initials
     = null

$initialsQueue

Queue of raw tokens claimed as initials during extraction, before the first one is (potentially) promoted back to firstname by finalizeInitials()


        protected
            array<string|int, mixed>
    $initialsQueue
     = []

$lastname

Last name


        protected
            string|null
    $lastname
     = null

$lastnamePrefix

Lastname prefix


        protected
            string|null
    $lastnamePrefix
     = null

$middlename

Middle name


        protected
            string|null
    $middlename
     = null

$nickname

Nickname


        protected
            string|null
    $nickname
     = null

$result

Parsed result


        protected
            mixed
    $result
     = null

$salutation

Salutation


        protected
            string|null
    $salutation
     = null

$suffix

Suffix


        protected
            string|null
    $suffix
     = null

__construct()

Constructor


    public
                    __construct([mixed $data = null ]) : mixed

Instantiate the parse object

Parameters

$data : mixed = null

__toString()

To string method


    public
                    __toString() : string

Return values

string

clean()

Clean method


    public
                    clean(string $name) : string

Parameters

$name : string

Return values

string

getData()

Get data


    public
                    getData() : mixed

getErrorMessage()

Get error message


    public
                    getErrorMessage() : string|null

Return values

string|null

getFirstname()

Method to get first name


    public
                    getFirstname() : string|null

Return values

string|null

getFullName()

Method to get the full name (given name plus lastname prefix and lastname)


    public
                    getFullName() : string|null

Return values

string|null

getGivenName()

Method to get the given name (first name, initials and middle name, in that order)


    public
                    getGivenName() : string|null

Return values

string|null

getInitials()

Method to get initials


    public
                    getInitials() : string|null

Return values

string|null

getLastname()

Method to get last name


    public
                    getLastname() : string|null

Return values

string|null

getLastnamePrefix()

Method to get lastname prefix


    public
                    getLastnamePrefix() : string|null

Return values

string|null

getMiddlename()

Method to get middle name


    public
                    getMiddlename() : string|null

Return values

string|null

getNickname()

Method to get nickname


    public
                    getNickname([bool $wrap = false ]) : string|null

Parameters

$wrap : bool = false

Return values

string|null

getResult()

Get parsed result


    public
                    getResult() : mixed

getSalutation()

Method to get salutation


    public
                    getSalutation() : string|null

Return values

string|null

getSuffix()

Method to get suffix


    public
                    getSuffix() : string|null

Return values

string|null

hasError()

Check if there is an error


    public
                    hasError() : bool

Return values

bool

hasFirstname()

Has first name


    public
                    hasFirstname() : bool

Return values

bool

hasInitials()

Has initials


    public
                    hasInitials() : bool

Return values

bool

hasLastname()

Has last name


    public
                    hasLastname() : bool

Return values

bool

hasLastnamePrefix()

Has lastname prefix


    public
                    hasLastnamePrefix() : bool

Return values

bool

hasMiddlename()

Has middle name


    public
                    hasMiddlename() : bool

Return values

bool

hasNickname()

Has nickname


    public
                    hasNickname() : bool

Return values

bool

hasSalutation()

Has salutation


    public
                    hasSalutation() : bool

Return values

bool

hasSuffix()

Has suffix


    public
                    hasSuffix() : bool

Return values

bool

parse()

Parse method


    public
                    parse([string|null $name = null ]) : static

Parameters

$name : string|null = null

Return values

static

setData()

Set data


    public
                    setData(mixed $data) : static

Parameters

$data : mixed

Return values

static

toArray()

To array method


    public
                    toArray() : array<string|int, mixed>

Return values

array<string|int, mixed>

absorbLeftovers()

Absorb any tokens no extraction step claimed: the first time this is called with a non-empty leftover, it becomes firstname (since every name needs one); after that, leftovers are appended to middlename. This is a deliberate difference from theiconic/name-parser, which can silently drop an unrecognized leading word (e.g. "The" in "The Rev. Mark Williams") - here nothing is ever discarded.


    protected
                    absorbLeftovers(array<string|int, mixed> $tokens) : void

Parameters

$tokens : array<string|int, mixed>

extractFirstname()

Extract firstname


    protected
                    extractFirstname(array<string|int, mixed> $tokens) : array<string|int, mixed>

If exactly one raw token remains, it's the firstname outright; otherwise the first remaining token becomes firstname.

Parameters

$tokens : array<string|int, mixed>

Return values

array<string|int, mixed>

extractInitials()

Extract initials


    protected
                    extractInitials(array<string|int, mixed> $tokens, bool $matchLastPart, NameValues $nameValues) : array<string|int, mixed>

A remaining single letter (optionally with a trailing period) is an initial. An all-caps 2-letter run (e.g. "JR") is split into two separate initials first - unless that run is also a recognized lastname prefix ("DE", "LA", "ST", ...), in which case it's left alone so extractLastname() can fold it as a prefix; without this guard, all-caps input like "JAMES DE LUCA" would have "DE" shredded into two fake initials before extractLastname() ever saw it. The very last remaining token is never treated as an initial unless $matchLastPart is true.

Parameters

$tokens : array<string|int, mixed>
$matchLastPart : bool
$nameValues : NameValues

Return values

array<string|int, mixed>

extractLastname()

Extract lastname (with prefix folding)


    protected
                    extractLastname(array<string|int, mixed> $tokens, NameValues $nameValues[, bool $singlePartOk = false ][, int|null $originalCount = null ]) : array<string|int, mixed>

Scans remaining tokens from the end backward, claiming them as lastname. A claimed run immediately preceded by a recognized lastname-prefix word, with at least one unclaimed token still before it, folds the prefix into lastnamePrefix. Stops once it hits a word long enough to look like a complete lastname on its own with more still unclaimed before it - what keeps a middle name from being swallowed into the lastname.

$originalCount is the token count BEFORE any earlier extraction step ran; it (not the current, shrunk token count) determines whether there was ever more than one word in this name to begin with, since a name reduced to a single remaining token by earlier steps (e.g. "J. B. Hunt" -> "Hunt" once both initials are claimed) should still have that token claimed as lastname.

Parameters

$tokens : array<string|int, mixed>
$nameValues : NameValues
$singlePartOk : bool = false
$originalCount : int|null = null

Return values

array<string|int, mixed>

extractMiddlename()

Extract middlename


    protected
                    extractMiddlename(array<string|int, mixed> $tokens) : array<string|int, mixed>

Whatever raw tokens remain after firstname extraction join as middlename.

Parameters

$tokens : array<string|int, mixed>

Return values

array<string|int, mixed>

extractNickname()

Extract nickname


    protected
                    extractNickname(array<string|int, mixed> $tokens, NameValues $nameValues) : array<string|int, mixed>

Scans for a token starting with an opening delimiter and collects tokens until one ends with the matching closing delimiter (supports multi-word nicknames).

Parameters

$tokens : array<string|int, mixed>
$nameValues : NameValues

Return values

array<string|int, mixed>

extractSalutation()

Extract salutation


    protected
                    extractSalutation(array<string|int, mixed> $tokens, NameValues $nameValues) : array<string|int, mixed>

Scans from the start of the tokens (bounded to roughly the first half) for matches against the salutation list, checked as both single tokens and multi-word phrases. Multiple consecutive salutations (e.g. "Rev. Dr John Doe") are all claimed.

Parameters

$tokens : array<string|int, mixed>
$nameValues : NameValues

Return values

array<string|int, mixed>

extractSuffix()

Extract suffix


    protected
                    extractSuffix(array<string|int, mixed> $tokens, NameValues $nameValues[, int $reservedParts = 2 ][, bool $matchSinglePart = false ][, bool $reserveLastToken = false ]) : array<string|int, mixed>

Scans from the end backward while trailing tokens keep matching the suffix list, stopping before it would eat into the reserved leading tokens (or, in single-part mode, matches only when exactly one token remains).

Parameters

$tokens : array<string|int, mixed>
$nameValues : NameValues
$reservedParts : int = 2
$matchSinglePart : bool = false
$reserveLastToken : bool = false

Return values

array<string|int, mixed>

finalizeInitials()

If no raw token ever became firstname but one or more initials were set aside, promote the FIRST claimed initial back to firstname - handles "J. B. Hunt" (firstname="J.", initials="B.", lastname="Hunt"), since a name consisting only of initials plus a lastname still needs a firstname.


    protected
                    finalizeInitials() : void

normalizeCase()

Normalize the case of a single word: an all-uppercase or all-lowercase word gets title-cased ("MACDONALD" / "macdonald" -> "Macdonald"); a word with any existing mixed case (e.g. "MacDonald", "McDonald", "O'Brien") is left exactly as typed, since that mixed case is almost always deliberate.


    protected
                    normalizeCase(string $word) : string

Parameters

$word : string

Return values

string

normalizeWords()

Normalize the case of each word in an array and join them with a space


    protected
                    normalizeWords(array<string|int, mixed> $words) : string

Parameters

$words : array<string|int, mixed>

Return values

string

parseCommaMode()

Parse comma-separated "Last, First Middle[, Suffix]" format


    protected
                    parseCommaMode(string $name, NameValues $nameValues) : void

Parameters

$name : string
$nameValues : NameValues

tokenize()

Tokenize method


    protected
                    tokenize(string $name) : array<string|int, mixed>

Parameters

$name : string

Return values

array<string|int, mixed>

NameParser extends AbstractParser in package Pop Parser

Tags

Table of Contents

Properties

Methods

Properties

$data

$error

$errorMessage

$firstname

$initials

$initialsQueue

$lastname

$lastnamePrefix

$middlename

$nickname

$result

$salutation

$suffix

Methods

__construct()

Parameters

__toString()

Return values

clean()

Parameters

Return values

getData()

getErrorMessage()

Return values

getFirstname()

Return values

getFullName()

Return values

getGivenName()

Return values

getInitials()

Return values

getLastname()

Return values

getLastnamePrefix()

Return values

getMiddlename()

Return values

getNickname()

Parameters

Return values

getResult()

getSalutation()

Return values

getSuffix()

Return values

hasError()

Return values

hasFirstname()

Return values

hasInitials()

Return values

hasLastname()

Return values

hasLastnamePrefix()

Return values

hasMiddlename()

Return values

hasNickname()

Return values

hasSalutation()

Return values

hasSuffix()

Return values

parse()

Parameters

Tags

Return values

setData()

Parameters

Return values

toArray()

Return values

absorbLeftovers()

NameParser extends AbstractParser
in package

Pop

Parser