PHPackages                             popphp/pop-parser - 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. popphp/pop-parser

ActiveLibrary

popphp/pop-parser
=================

PHP name and address parsing optional component of the Pop PHP Framework

1.0.0(yesterday)037↑2900%BSD-3-ClausePHPPHP >=8.4.0CI passing

Since Jul 31Pushed todayCompare

[ Source](https://github.com/popphp/pop-parser)[ Packagist](https://packagist.org/packages/popphp/pop-parser)[ Docs](http://github.com/popphp/pop-parser)[ RSS](/packages/popphp-pop-parser/feed)WikiDiscussions master Synced today

READMEChangelog (1)Dependencies (1)Versions (4)Used By (0)

pop-parser
==========

[](#pop-parser)

[![Build Status](https://github.com/popphp/pop-parser/workflows/phpunit/badge.svg)](https://github.com/popphp/pop-parser/actions)[![Coverage Status](https://camo.githubusercontent.com/8119db36c6ca166de180329e1313d338b7a787cef95606554e09f0b398973e17/687474703a2f2f63632e706f707068702e6f72672f636f7665726167652e7068703f636f6d703d706f702d706172736572)](http://cc.popphp.org/pop-parser/)

[![Join the chat at https://discord.gg/TZjgT74U7E](https://camo.githubusercontent.com/acad7b0eeb78b78d08ffd2b85681ab243436388b5f86f8bcb956a69246e53739/68747470733a2f2f6d656469612e706f707068702e6f72672f696d672f646973636f72642e737667)](https://discord.gg/TZjgT74U7E)

- [Overview](#overview)
- [Install](#install)
- [Address Parsing](#address-parsing)
- [Name Parsing](#name-parsing)

Overview
--------

[](#overview)

Pop Parser is a simple set of parsers for names and addresses. It ships two independent, native parsers - no third-party parsing dependencies required:

- `Pop\Parser\Address\AddressParser` - parses free-form US/CA street addresses into their component parts (street number, street name, route type, direction, unit, city, state, postal code, country, PO Box detection).
- `Pop\Parser\Name\NameParser` - parses personal names into their component parts (salutation, first/middle/last name, lastname prefix, initials, nickname, suffix), including comma-separated "Last, First" format.

Both parsers extend the same `Pop\Parser\AbstractParser` base class and share a consistent shape: construct with or without data, call `parse()`, then read the results off via `get*()`/`has*()`methods, `toArray()`, or by casting to a string.

[Top](#pop-parser)

Install
-------

[](#install)

Install `pop-parser` using Composer.

```
composer require popphp/pop-parser

```

Or, require it in your composer.json file

```
"require": {
    "popphp/pop-parser" : "^1.0.0"
}

```

[Top](#pop-parser)

Address Parsing
---------------

[](#address-parsing)

`Pop\Parser\Address\AddressParser` parses a free-form US or Canadian street address string into its component parts. Addresses can be passed as a single comma/semicolon/newline-delimited string, or built up over multiple lines - both a "123 Main St, Springfield, IL 62704" one-liner and a multi-line mailing-label style address parse the same way.

### Basic usage

[](#basic-usage)

```
use Pop\Parser\Address\AddressParser;

$parser = new AddressParser();
$parser->parse('123 Main St Apt 4B, Springfield, IL 62704');

$parser->getStreetNumber(); // '123'
$parser->getStreetName();   // 'Main'
$parser->getRouteType();    // 'St'
$parser->getUnit();         // 'Apt 4B'
$parser->getCity();         // 'Springfield'
$parser->getStateCode();    // 'IL'
$parser->getStateName();    // 'Illinois'
$parser->getPostalCode();   // '62704'
$parser->getCountry();      // 'US'
```

The address string can also be passed to the constructor, or set separately with `setData()`before calling `parse()` with no argument:

```
$parser = new AddressParser('123 Main St, Springfield, IL 62704');
$parser->parse();
```

### Directions and route types

[](#directions-and-route-types)

A leading or trailing directional (`N`, `S`, `E`, `W`, `NE`, `SW`, ...) is recognized and kept separate from the street name. `getStreetName()` includes it by default; pass `false` to get the bare street name without it:

```
$parser = new AddressParser();
$parser->parse('456 N Elm Street, Chicago, IL 60601');

$parser->getDirection();          // 'N'
$parser->getStreetName();         // 'N Elm'
$parser->getStreetName(false);    // 'Elm'
$parser->getRouteType();          // 'Street'
```

### PO Boxes

[](#po-boxes)

PO Box addresses ("PO Box 1234", "P.O. Box 1234", "POB 1234", "Box 1234") are recognized directly - the box number is returned via `getStreetName()`, `getStreetNumber()` stays `null`, and `isPoBox()` reports the match:

```
$parser = new AddressParser();
$parser->parse('PO Box 1234, Springfield, IL 62704');

$parser->isPoBox();       // true
$parser->getStreetName(); // 'PO Box 1234'
$parser->getCity();       // 'Springfield'
```

### Full address, array output, and string casting

[](#full-address-array-output-and-string-casting)

```
$parser->getFullAddress();
// '123 Main St, Apt 4B, Springfield, IL 62704'

// Options: delimiter, whether to use the state code vs. full state name, whether to include the country
$parser->getFullAddress(', ', false, true);
// '123 Main St, Apt 4B, Springfield, Illinois 62704, US'

$parser->toArray();
// [
//     'streetNumber' => '123', 'streetName' => 'Main', 'routeType' => 'St',
//     'direction' => null, 'unit' => 'Apt 4B', 'city' => 'Springfield',
//     'postalCode' => '62704', 'zip4' => null, 'stateName' => 'Illinois',
//     'stateCode' => 'IL', 'country' => 'US',
// ]

(string) $parser; // same as getFullAddress()
```

Every component getter (`getStreetNumber()`, `getStreetName()`, `getRouteType()`, `getDirection()`, `getUnit()`, `getCity()`, `getPostalCode()`, `getZip4()`, `getStateName()`, `getStateCode()`, `getCountry()`) has a matching `has*()` method (e.g. `hasUnit()`, `hasZip4()`) that returns `true`only when that part was actually found.

### Reference data

[](#reference-data)

`Pop\Parser\Address\AddressValues` exposes the underlying lookup/validation data the parser uses

- route type abbreviations (`getRouteTypes()`, `getCommonRouteTypes()`), directions (`getDirections()`), unit types (`getUnitTypes()`), and US/Canadian states and provinces (`getStates()`, `getStateCodes()`, `getStateNames()`) - useful if you want to validate or build your own address-related form fields against the same data the parser relies on.

### Errors

[](#errors)

Calling `parse()` with no data set (neither passed to the constructor, `setData()`, nor `parse()`itself) throws a `Pop\Parser\Exception`.

[Top](#pop-parser)

Name Parsing
------------

[](#name-parsing)

`Pop\Parser\Name\NameParser` parses a free-form personal name string into its component parts. It supports plain space-separated names ("John Smith") as well as comma-separated "Last, First Middle\[, Suffix\]" format, and recognizes salutations, suffixes, initials, lastname prefixes ("van", "de", "von", ...), and parenthetical/quoted nicknames along the way.

### Basic usage

[](#basic-usage-1)

```
use Pop\Parser\Name\NameParser;

$parser = new NameParser();
$parser->parse('Dr. John Michael Smith Jr.');

$parser->getSalutation(); // 'Dr.'
$parser->getFirstname();  // 'John'
$parser->getMiddlename(); // 'Michael'
$parser->getLastname();   // 'Smith'
$parser->getSuffix();     // 'Jr'
$parser->getFullName();   // 'John Michael Smith'
(string) $parser;         // 'Dr. John Michael Smith Jr'
```

As with `AddressParser`, the name string can be passed to the constructor instead of `parse()`:

```
$parser = new NameParser('John Smith');
$parser->parse();
```

### Comma-separated format

[](#comma-separated-format)

A comma anywhere in the input switches to "Last, First Middle\[, Suffix\]" parsing automatically:

```
$parser = new NameParser();
$parser->parse('Smith, John Michael, Jr');

$parser->getFirstname();  // 'John'
$parser->getMiddlename(); // 'Michael'
$parser->getLastname();   // 'Smith'
$parser->getSuffix();     // 'Jr'
```

### Lastname prefixes

[](#lastname-prefixes)

Recognized lastname-prefix words ("van", "von", "de", "della", "st", ...) are split out into their own field rather than left attached to the lastname:

```
$parser = new NameParser();
$parser->parse('Ludwig van Beethoven');

$parser->getLastnamePrefix(); // 'van'
$parser->getLastname();       // 'Beethoven'
$parser->getFullName();       // 'Ludwig van Beethoven'
```

### Initials and nicknames

[](#initials-and-nicknames)

A single letter (with or without a trailing period) is treated as an initial rather than a first or middle name, and a parenthetical or quoted segment anywhere in the name is pulled out as a nickname:

```
$parser = new NameParser();
$parser->parse('J.R. "Bob" Smith');

$parser->getFirstname();    // 'J'
$parser->getInitials();     // 'R'
$parser->getNickname();     // 'Bob'
$parser->getNickname(true); // '(Bob)'
$parser->getLastname();     // 'Smith'
```

### Full name, given name, array output, and string casting

[](#full-name-given-name-array-output-and-string-casting)

```
$parser->getGivenName(); // firstname + initials + middlename, whichever are present
$parser->getFullName();  // given name + lastname prefix + lastname

$parser->toArray();
// [
//     'salutation' => null, 'firstname' => 'John', 'initials' => null,
//     'middlename' => 'Michael', 'nickname' => null, 'lastnamePrefix' => null,
//     'lastname' => 'Smith', 'suffix' => 'Jr',
// ]

(string) $parser; // salutation + given name + nickname + lastname prefix + lastname + suffix
```

Every component getter (`getSalutation()`, `getFirstname()`, `getMiddlename()`, `getNickname()`, `getInitials()`, `getLastnamePrefix()`, `getLastname()`, `getSuffix()`) has a matching `has*()`method (e.g. `hasSuffix()`, `hasNickname()`) that returns `true` only when that part was actually found.

### Reference data

[](#reference-data-1)

`Pop\Parser\Name\NameValues` exposes the underlying lookup data the parser uses - salutations (`getSalutations()`), suffixes (`getSuffixes()`), lastname prefixes (`getLastnamePrefixes()`), and recognized nickname-wrapping delimiter pairs (`getNicknameDelimiters()`).

### Errors

[](#errors-1)

Calling `parse()` with no data set (neither passed to the constructor, `setData()`, nor `parse()`itself), or with data that normalizes to an empty string, throws a `Pop\Parser\Exception`.

[Top](#pop-parser)

###  Health Score

45

—

FairBetter than 91% of packages

Maintenance100

Actively maintained with recent releases

Popularity11

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity53

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

Unknown

Total

1

Last Release

1d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/c19dee900e9e20039c723cc403f76b5c22ac2dddb3f86773ae64fb082d4949e2?d=identicon)[nicksagona](/maintainers/nicksagona)

---

Top Contributors

[![nicksagona](https://avatars.githubusercontent.com/u/898670?v=4)](https://github.com/nicksagona "nicksagona (21 commits)")

---

Tags

phppoppop phpname parsingaddress parsing

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/popphp-pop-parser/health.svg)

```
[![Health](https://phpackages.com/badges/popphp-pop-parser/health.svg)](https://phpackages.com/packages/popphp-pop-parser)
```

###  Alternatives

[popphp/pop-db

Pop Db Component for Pop PHP Framework

1816.5k13](/packages/popphp-pop-db)[popphp/pop-pdf

PHP PDF library for generating and importing PDF documents. A component of the Pop PHP Framework

208.8k1](/packages/popphp-pop-pdf)[popphp/pop-http

Pop Http Component for Pop PHP Framework

1020.5k14](/packages/popphp-pop-http)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)