Download the PHP package awaisjameel/laravel-address-parser without Composer

Laravel Address Parser

Smart, opinionated parsing of single‑line US postal addresses into structured components for Laravel.

Laravel Address Parser helps you take messy user‑submitted single line US addresses and split them into reliable fields: address1, address2 (unit), city, state, zip and optionally county. It applies pragmatic heuristics—street suffix detection, unit indicator extraction, normalization (whitespace + periods), and validation of state + ZIP formats—without depending on external APIs. Ideal for form ingestion, ETL pipelines, quick data cleanup, and pre‑validation before geocoding.

Not a USPS CASS certified normalizer. It doesn't validate that an address physically exists; it simply parses and validates format.

Table of Contents

1. Features
2. Requirements
3. Installation
4. Quick Start
5. Usage Examples
6. Facade, DI & Helper Patterns
7. Parsing Logic & Heuristics
8. County Parsing
9. Validation Utilities
10. Formatting Addresses
11. Configuration
12. Error Handling
13. Edge Cases & Limitations
14. Testing
15. Performance
16. Roadmap
17. Contributing
18. Security
19. Support Us
20. Credits
21. License

Features

• ✅ Parse single‑line US addresses with or without commas
• ✅ Detect and extract unit indicators (APT, STE, #12, FLOOR, etc.)
• ✅ Supports ZIP (5‑digit) and ZIP+4 (extended) formats
• ✅ Validates US state abbreviations (full 50 + DC)
• ✅ Optional county parsing via comma‑separated form
• ✅ Normalizes periods after abbreviations (St. → St), collapses excess whitespace
• ✅ Graceful formatting back to a one‑line address
• ✅ Clear, typed exception (AddressParsingException) for invalid cases
• ✅ Simple, framework‑friendly (pure static methods), zero external API calls
• ✅ Battle‑tested with Pest test suite

Requirements

Installation

Install via Composer:

The package auto‑discovers. No manual provider registration required.

Optional: Publish Config

Currently the config file is a placeholder for future tuning (custom suffixes, unit indicators, etc.). You can publish it now:

Published file at config/address-parser.php:

No migrations or views are shipped (ignore earlier generic template tags).

Quick Start

Usage Examples

1. Basic Parsing (No Commas)

2. Comma‑Separated

3. With County (If Provided)

4. County Method Without County

5. Format Back to One Line

6. Validation Helpers

Facade, DI & Helper Patterns

Because all methods are static, you can call the class directly. A facade alias LaravelAddressParser is registered; if you prefer the facade style:

Dependency injection is not required, but you can wrap this in your own service if you want to enforce non‑static boundaries for test isolation.

Parsing Logic & Heuristics

1. Normalize input: trim, collapse whitespace, remove trailing punctuation, strip periods after known abbreviations.
2. Extract trailing STATE ZIP using regex. Validate both.
3. Before the state/ZIP segment:
   • If no commas: locate rightmost known street suffix, everything after → city.
   • If commas: last comma part → city; remaining → address lines.
4. Unit detection:
   • Detect explicit unit parts after street suffix (e.g. Apt 4B, #12).
   • Handles units embedded at end of address1 or separated by comma.
5. Normalizes unit casing (except leading #).
6. Returns structured array including a nullable county when parsed via county method.

Recognized street suffixes (subset): ST, AVE, RD, DR, LN, CT, CIR, BLVD, PKWY, TRAIL, HWY, WAY, PL, LOOP, TER, EXPY, etc.

Recognized unit indicators: APT, SUITE, STE, UNIT, FLOOR, ROOM, BLDG, #, LOT, SPACE, etc.

County Parsing

Use parseAddressStringWithCounty() for either format:

1. Street, City, County, ST ZIP
2. Street, City, ST ZIP (county omitted → county => null)

If fewer than 3 comma‑separated parts exist (excluding state/ZIP) an exception is thrown.

Validation Utilities

These do not consult external APIs; they are format checks only.

Formatting Addresses

formatAddress(array $components): string builds a single line string from parsed parts. Missing address2 is skipped; missing address1 results in City, ST ZIP only.

Configuration

Currently no runtime options are exposed. Future versions may allow:

• Extending street suffix list
• Extending unit indicator list
• Custom validation strategy or USPS API integration hooks

Feel free to open an issue with your use case.

Error Handling

Parsing failures throw Awaisjameel\LaravelAddressParser\AddressParsingException with a human‑readable message. Common triggers:

• Empty or "0" input
• Cannot locate valid trailing STATE ZIP
• Invalid state abbreviation (e.g. ZZ)
• Invalid ZIP format
• Missing city segment
• Cannot identify street suffix when required

Always wrap user‑submitted data:

Edge Cases & Limitations

Not a full canonicalizer: it won't expand NW to Northwest, or validate delivery points.

Testing

Run the full test suite (Pest):

Or with coverage:

Static analysis:

Code style (Laravel Pint):

Performance

All operations are in‑memory string functions & a few regex matches. Suitable for real‑time form handling. For bulk ETL (hundreds of thousands of rows) you can batch process safely; memory footprint is minimal.

Micro‑optimizations (e.g. caching compiled regex) are intentionally deferred until a real hotspot is demonstrated.

Roadmap

• Optional configuration for custom suffix/unit lists
• USPS address standardization adapter
• Geocoding integration hooks
• Bulk parsing helper with per‑record error collection
• Locale expansion (Canadian, UK parsing) via strategy interfaces

Have a request? Open an issue.

Contributing

Contributions are welcome! Please:

1. Fork & create a feature branch
2. Add/adjust tests for new behavior
3. Run: composer analyse, composer format, composer test
4. Open a PR describing rationale & trade‑offs

For architectural changes, open an issue first for discussion.

Security

If you discover a security vulnerability (e.g. pathological regex input leading to DoS), please email the author or open a private advisory. Avoid posting exploits publicly until a fix is released.

This library does not execute external processes or perform network calls, and stores no secrets.

Support Us

If you find this package useful, consider supporting its development make sure to give a star on GitHub!

Credits

• awaisjameel
• Inspired by pragmatic parsing approaches in many OSS data-cleanup tools

License

Released under the MIT License. See LICENSE.md.

FAQ

Does it validate an address actually exists?

No. It validates format only. For existence use USPS, Smarty, Google, etc.

Will it parse multi‑line addresses?

Only single‑line strings. Pre‑join lines ("address1 address2") before parsing, or use the county method if needed.

Why static methods?

Low ceremony; no state. You can wrap them if you prefer dependency injection.

Is the heuristics list exhaustive?

It covers common US street suffixes & unit indicators. You can extend in the future via config once exposed.

Can I disable normalization?

Not yet. Planned via config.

Example End‑to‑End Form Handling

Happy parsing! 📨