{"id":13606339,"url":"https://github.com/wintercms/wn-location-plugin","last_synced_at":"2025-10-08T17:13:09.167Z","repository":{"id":49865541,"uuid":"345013675","full_name":"wintercms/wn-location-plugin","owner":"wintercms","description":"Location plugin for Winter CMS","archived":false,"fork":false,"pushed_at":"2025-05-03T02:26:14.000Z","size":177,"stargazers_count":6,"open_issues_count":3,"forks_count":6,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-06T23:49:07.931Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"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/wintercms.png","metadata":{"funding":{"github":"wintercms","open_collective":"wintercms"},"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-06T05:28:17.000Z","updated_at":"2025-04-27T04:16:41.000Z","dependencies_parsed_at":"2023-12-19T09:47:19.347Z","dependency_job_id":"2e01b630-21e1-45ac-8ca3-b4babe004282","html_url":"https://github.com/wintercms/wn-location-plugin","commit_stats":{"total_commits":114,"total_committers":42,"mean_commits":"2.7142857142857144","dds":0.7543859649122807,"last_synced_commit":"895490eb3467b201d969fa3a8a0951276e65f4fb"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wintercms%2Fwn-location-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wintercms%2Fwn-location-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wintercms%2Fwn-location-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wintercms%2Fwn-location-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wintercms","download_url":"https://codeload.github.com/wintercms/wn-location-plugin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253981791,"owners_count":21994337,"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","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":["hacktoberfest"],"created_at":"2024-08-01T19:01:08.258Z","updated_at":"2025-10-08T17:13:04.133Z","avatar_url":"https://github.com/wintercms.png","language":"PHP","funding_links":["https://github.com/sponsors/wintercms","https://opencollective.com/wintercms"],"categories":["Uncategorized"],"sub_categories":["Uncategorized"],"readme":"# Location Plugin\n\n[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/wintercms/wn-location-plugin/blob/main/LICENSE)\n\nThis plugin adds location based features to [Winter CMS](https://wintercms.com).\n\nSupports:\n- Easily add Country and State to any model\n- Form widget for address lookups (Google API)\n\n## Installation\n\nThis plugin is available for installation via [Composer](http://getcomposer.org/).\n\n```bash\ncomposer require winter/wn-location-plugin\n```\n\nAfter installing the plugin you will need to run the migrations and (if you are using a [public folder](https://wintercms.com/docs/develop/docs/setup/configuration#using-a-public-folder)) [republish your public directory](https://wintercms.com/docs/develop/docs/console/setup-maintenance#mirror-public-files).\n\n```bash\nphp artisan migrate\n```\n\n### Google API key requirement\n\nAs of June 22, 2016 the Google Maps service requires an API key. You may generate a key from the following link:\n\n- [Get a Google API key](https://developers.google.com/maps/documentation/javascript/get-api-key)\n\nCopy the key and enter it in the **Settings \u003e Location settings** area. If you find the address finder is not working, you may need to enable the [Places API](https://console.developers.google.com/apis/api/places_backend/overview?project=_) and the [Maps JavaScript API](https://console.developers.google.com/apis/api/maps_backend/overview?project=_).\n\n### Add Country and State to any model\n\nThis plugin provides an easy way to add location fields, country and state, to any model. Simply add these columns to the database table:\n\n```php\n$table-\u003einteger('country_id')-\u003eunsigned()-\u003enullable()-\u003eindex();\n$table-\u003einteger('state_id')-\u003eunsigned()-\u003enullable()-\u003eindex();\n```\n\nThen implement the **Winter.Location.Behaviors.LocationModel** behavior in the model class:\n\n```php\npublic $implement = ['Winter.Location.Behaviors.LocationModel'];\n```\n\nThis will automatically create two \"belongs to\" relationships:\n\n1. **state** - relation for Winter\\Location\\Models\\State\n1. **country** - relation for Winter\\Location\\Models\\Country\n\n### Back-end usage\n\n#### Forms\n\nYou are free to add the following form field definitions:\n\n```yaml\ncountry:\n    label: winter.location::lang.country.label\n    type: dropdown\n    span: left\n    placeholder: winter.location::lang.country.select\n\nstate:\n    label: winter.location::lang.state.label\n    type: dropdown\n    span: right\n    dependsOn: country\n    placeholder: winter.location::lang.state.select\n```\n\n#### Lists\n\nFor the list column definitions, you can use the following snippet:\n\n```yaml\ncountry:\n    label: winter.location::lang.country.label\n    searchable: true\n    relation: country\n    select: name\n    sortable: false\n\nstate:\n    label: winter.location::lang.state.label\n    searchable: true\n    relation: state\n    select: name\n    sortable: false\n```\n### Front-end usage\n\nThe front-end can also use the relationships by creating a partial called **country-state** with the content:\n\n```twig\n{% set countryId = countryId|default(form_value('country_id')) %}\n{% set stateId = stateId|default(form_value('state_id')) %}\n\n\u003cdiv class=\"form-group\"\u003e\n    \u003clabel for=\"accountCountry\"\u003eCountry\u003c/label\u003e\n    {{ form_select_country('country_id', countryId, {\n        id: 'accountCountry',\n        class: 'form-control',\n        emptyOption: '',\n        'data-request': 'onInit',\n        'data-request-update': {\n            'country-state': '#partialCountryState'\n        }\n    }) }}\n\u003c/div\u003e\n\n\u003cdiv class=\"form-group\"\u003e\n    \u003clabel for=\"accountState\"\u003eState\u003c/label\u003e\n    {{ form_select_state('state_id', countryId, stateId, {\n        id: 'accountState',\n        class: 'form-control',\n        emptyOption: ''\n    }) }}\n\u003c/div\u003e\n```\n\nThis partial can be rendered in a form with the following:\n\n```twig\n\u003cdiv id=\"partialCountryState\"\u003e\n    {% partial 'country-state' countryId=user.country_id stateId=user.state_id %}\n\u003c/div\u003e\n```\n\n### Short code accessors\n\nThe behavior will also add a special short code accessor and setter to the model that converts `country_code` and `state_code` to their respective identifiers.\n\n```php\n// Softly looks up and sets the country_id and state_id\n// for these Country and State relations.\n\n$model-\u003ecountry_code = \"US\";\n$model-\u003estate_code = \"FL\";\n$model-\u003esave();\n```\n### ISO 3166-1 accessors\n\nThe behavior will also add the ISO-3166-1 values as accessors to the model (data sourced from the [league/iso3166](https://github.com/thephpleague/iso3166) package).  \nAvailables accessors are `iso_name` (country name), `iso_alpha3` (three-letter code), `iso_numeric` (three-digit code), `iso_currencies` (three-digit currencies code) and `iso` (array of all iso attributes).\n\n```php\n$usCountry = \\Winter\\Location\\Models\\Country::whereCode('US')-\u003efirst();\n\n$usCountry-\u003eiso_name;\n// (string) \"United States of America\"\n\n$usCountry-\u003eiso_alpha3;\n// (string) \"USA\"\n\n$usCountry-\u003eiso_numeric;\n// (string) \"840\"\n\n$usCountry-\u003eiso_currencies;\n// (array) [ 0 =\u003e \"USD\" ]\n\n$usCountry-\u003eiso;\n// (array) [\n//     \"name\" =\u003e \"United States of America\"\n//     \"alpha2\" =\u003e \"US\"\n//     \"alpha3\" =\u003e \"USA\"\n//     \"numeric\" =\u003e \"840\"\n//     \"currency\" =\u003e [\n//         0 =\u003e \"USD\"\n//     ]\n// ]\n\n```\n\n### Address Finder Form Widget\n\nThis plugin introduces an address lookup form field called `addressfinder`. The form widget renders a Google Maps autocomplete address field that automatically populates mapped fields based on the value entered and selected in the address.\n\nAvailable mappings:\n\n- street\n- city\n- zip\n- state\n- country\n- country-long\n- latitude\n- longitude\n- vicinity\n\nAvailable options:\n\nYou can restrict the address lookup to certain countries by defining the `countryRestriction` option. The option accepts a comma separated list of ISO 3166-1 ALPHA-2 compatible country codes (see: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).\n\nUsage:\n\n```yaml\n# ===================================\n#  Form Field Definitions\n# ===================================\n\nfields:\n    address:\n        label: Address\n        type: addressfinder\n        countryRestriction: 'us,ch'\n        fieldMap:\n            latitude: latitude\n            longitude: longitude\n            city: city\n            zip: zip\n            country: country_code\n            state: state_code\n            vicinity: vicinity\n\n    city:\n        label: City\n    zip:\n        label: Zip\n    country_code:\n        label: Country\n    state_code:\n        label: State\n    latitude:\n        label: Latitude\n    longitude:\n        label: Longitude\n    vicinity:\n        label: Vicinity\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwintercms%2Fwn-location-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwintercms%2Fwn-location-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwintercms%2Fwn-location-plugin/lists"}