https://github.com/dillingham/locality
Proof of concept. doesn't work fully
https://github.com/dillingham/locality
Last synced: 11 months ago
JSON representation
Proof of concept. doesn't work fully
- Host: GitHub
- URL: https://github.com/dillingham/locality
- Owner: dillingham
- License: mit
- Created: 2021-09-26T22:47:03.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2022-01-13T22:33:08.000Z (over 4 years ago)
- Last Synced: 2025-05-20T17:59:23.185Z (about 1 year ago)
- Language: PHP
- Homepage:
- Size: 51.8 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
# Locality
[](https://packagist.org/packages/dillingham/locality)
[](https://github.com/dillingham/locality/actions?query=workflow%3Arun-tests+branch%3Amain)
[](https://github.com/dillingham/locality/actions?query=workflow%3A"Check+%26+fix+styling"+branch%3Amain)
[](https://packagist.org/packages/dillingham/locality)
---
A Laravel package that automatically normalizes address data. Instead of storing city state & zipcodes repeatedly, create tables and reference the foreign key. This package accepts the string representation, checks if it exists or creates it and adds the relationship. This package also provides accessors to make it feel as though you aren't even normalizing.
---
## Installation
You can install the package via composer:
```bash
composer require dillingham/locality
```
You can publish the config file with:
```bash
php artisan vendor:publish --provider="Dillingham\Locality\LocalityServiceProvider" --tag="locality-config"
```
Add the following columns to your model's migration:
```php
$table->addAddress();
```
Which is just a shorthand for adding these columns:
| column | nullable | indexed | description |
|--------|----------|---------|-------------|
| address_1 | yes | no | street and building number |
| address_2 | yes | no | optional unit number |
| admin_level_3_id | yes | yes | the neighborhood political region |
| admin_level_2_id | no | yes | the city political region |
| admin_level_1_id | no | yes | the state political region |
| postal_code_id | no | yes | the postal foreign key |
| country_id | yes | no | the country foreign key |
| formatted_address | no | no | static address without queries |
The 5 tables will be migrated:
```
php artisan migrate
```
Then add the `HasAddress` trait:
```php
'104 India St',
'address_2' => 'Apt #3L',
'admin_level_2' => 'Brookyln',
'admin_level_1' => 'NY',
'postal_code' => '11222',
]);
```
Automatically the trait will use firstOrCreate when storing Profile
```php
'admin_level_2' => 'Brookyln'
```
becomes the foreign id of Brooklyn in the `admin_level_2` table
```php
'admin_level_2_id' => 332
```
## Access Values
Access the string values of the relationships via accessors:
```php
$profile->admin_level_2 == 'Brooklyn'
$profile->admin_level_1 == 'NY'
```
> These accessors call relationships behind the scenes, eager load in collections
Note: the full address formatting is statically stored while saving:
```php
$profile->formatted_address == '104 India St, #3l Brooklyn, NY 11222`
```
# Bonus
The following are opt in loosely related features;
### Dependent Filters
Here are some api routes for filtering models by localtion info
```php
Route::localityDepenentOptions();
```
> The following assumes routes/api.php and prefixed from RouteServiceProvider.php
```
GET /api/locality/countries
```
```json
{
"data": [
{
"value": 1,
"display": "US"
}
]
}
```
```
GET /api/locality/admin_level_2?country_id=1
```
```json
{
"data": [
{
"value": 1,
"display": "NY"
}
]
}
```
```
GET /api/locality/admin_level_1?admin_level_2_id=1
```
```json
{
"data": [
{
"value": 1,
"display": "Brooklyn"
}
]
}
```
```
GET /api/locality/postal_code?admin_level_1_id=1
```
```json
{
"data": [
{
"value": 1,
"display": "11222"
}
]
}
```
## Testing
```bash
composer test
```
## Changelog
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
## Contributing
Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.
## Security Vulnerabilities
Please review [our security policy](../../security/policy) on how to report security vulnerabilities.
## Credits
- [Brian Dillingham](https://github.com/dillingham)
- [All Contributors](../../contributors)
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.