{"id":22889604,"url":"https://github.com/dillingham/locality","last_synced_at":"2025-07-30T08:09:13.850Z","repository":{"id":56969105,"uuid":"410679446","full_name":"dillingham/locality","owner":"dillingham","description":"Proof of concept. doesn't work fully","archived":false,"fork":false,"pushed_at":"2022-01-13T22:33:08.000Z","size":53,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-05-20T17:59:23.185Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":false,"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/dillingham.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null},"funding":{"github":"dillingham"}},"created_at":"2021-09-26T22:47:03.000Z","updated_at":"2021-11-06T00:44:37.000Z","dependencies_parsed_at":"2022-08-21T06:40:27.285Z","dependency_job_id":null,"html_url":"https://github.com/dillingham/locality","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":"dillingham/package-skeleton-laravel","purl":"pkg:github/dillingham/locality","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dillingham%2Flocality","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dillingham%2Flocality/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dillingham%2Flocality/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dillingham%2Flocality/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dillingham","download_url":"https://codeload.github.com/dillingham/locality/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dillingham%2Flocality/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267834806,"owners_count":24151642,"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","status":"online","status_checked_at":"2025-07-30T02:00:09.044Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-12-13T21:56:20.615Z","updated_at":"2025-07-30T08:09:13.822Z","avatar_url":"https://github.com/dillingham.png","language":"PHP","funding_links":["https://github.com/sponsors/dillingham"],"categories":[],"sub_categories":[],"readme":"# Locality\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/dillingham/locality.svg?style=flat-square)](https://packagist.org/packages/dillingham/locality)\n[![GitHub Tests Action Status](https://img.shields.io/github/workflow/status/dillingham/locality/run-tests?label=tests)](https://github.com/dillingham/locality/actions?query=workflow%3Arun-tests+branch%3Amain)\n[![GitHub Code Style Action Status](https://img.shields.io/github/workflow/status/dillingham/locality/Check%20\u0026%20fix%20styling?label=code%20style)](https://github.com/dillingham/locality/actions?query=workflow%3A\"Check+%26+fix+styling\"+branch%3Amain)\n[![Total Downloads](https://img.shields.io/packagist/dt/dillingham/locality.svg?style=flat-square)](https://packagist.org/packages/dillingham/locality)\n\n---\n\nA Laravel package that automatically normalizes address data. Instead of storing city state \u0026 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.\n\n---\n\n## Installation\n\nYou can install the package via composer:\n\n```bash\ncomposer require dillingham/locality\n```\n\nYou can publish the config file with:\n```bash\nphp artisan vendor:publish --provider=\"Dillingham\\Locality\\LocalityServiceProvider\" --tag=\"locality-config\"\n```\n\nAdd the following columns to your model's migration:\n\n```php\n$table-\u003eaddAddress();\n```\nWhich is just a shorthand for adding these columns:\n\n| column | nullable | indexed | description |\n|--------|----------|---------|-------------|\n| address_1 | yes | no | street and building number |\n| address_2 | yes | no | optional unit number |\n| admin_level_3_id | yes | yes | the neighborhood political region |\n| admin_level_2_id | no | yes | the city political region |\n| admin_level_1_id | no | yes | the state political region |\n| postal_code_id | no | yes | the postal foreign key |\n| country_id | yes | no | the country foreign key |\n| formatted_address | no | no | static address without queries |\n\nThe 5 tables will be migrated:\n```\nphp artisan migrate\n```\n\nThen add the `HasAddress` trait:\n\n```php\n\u003c?php\n\nnamespace App\\Models;\n\nuse Dillingham\\Locality\\HasAddress;\n\nclass Profile extends Model\n{\n  use HasAddress;\n}\n```\n\n## Usage\n\n```php\nProfile::create([\n    'address_1' =\u003e '104 India St',\n    'address_2' =\u003e 'Apt #3L',\n    'admin_level_2' =\u003e 'Brookyln',    \n    'admin_level_1' =\u003e 'NY',\n    'postal_code' =\u003e '11222',\n]);\n```\nAutomatically the trait will use firstOrCreate when storing Profile\n\n```php\n'admin_level_2' =\u003e 'Brookyln'\n```\nbecomes the foreign id of Brooklyn in the `admin_level_2` table\n\n```php\n'admin_level_2_id' =\u003e 332\n```\n\n## Access Values\n\nAccess the string values of the relationships via accessors:\n\n```php\n$profile-\u003eadmin_level_2 == 'Brooklyn'\n$profile-\u003eadmin_level_1 == 'NY'\n```\n\u003e These accessors call relationships behind the scenes, eager load in collections\n\nNote: the full address formatting is statically stored while saving:\n```php\n$profile-\u003eformatted_address == '104 India St, #3l Brooklyn, NY 11222`\n```\n\n# Bonus\n\nThe following are opt in loosely related features;\n\n### Dependent Filters\n\nHere are some api routes for filtering models by localtion info\n\n```php\nRoute::localityDepenentOptions();\n```\n\u003e The following assumes routes/api.php and prefixed from RouteServiceProvider.php\n```\nGET /api/locality/countries\n```\n```json\n{\n    \"data\": [\n        {\n            \"value\": 1,\n            \"display\": \"US\"\n        }\n    ]\n}\n```\n```\nGET /api/locality/admin_level_2?country_id=1\n```\n```json\n{\n    \"data\": [\n        {\n            \"value\": 1,\n            \"display\": \"NY\"\n        }\n    ]\n}\n```\n```\nGET /api/locality/admin_level_1?admin_level_2_id=1\n```\n```json\n{\n    \"data\": [\n        {\n            \"value\": 1,\n            \"display\": \"Brooklyn\"\n        }\n    ]\n}\n```\n```\nGET /api/locality/postal_code?admin_level_1_id=1\n```\n```json\n{\n    \"data\": [\n        {\n            \"value\": 1,\n            \"display\": \"11222\"\n        }\n    ]\n}\n```\n\n## Testing\n\n```bash\ncomposer test\n```\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.\n\n## Contributing\n\nPlease see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.\n\n## Security Vulnerabilities\n\nPlease review [our security policy](../../security/policy) on how to report security vulnerabilities.\n\n## Credits\n\n- [Brian Dillingham](https://github.com/dillingham)\n- [All Contributors](../../contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdillingham%2Flocality","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdillingham%2Flocality","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdillingham%2Flocality/lists"}