PHPackages winter/wn-location-plugin - 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. [Utility & Helpers](/categories/utility) 4. / 5. winter/wn-location-plugin ActiveWinter-plugin[Utility & Helpers](/categories/utility) winter/wn-location-plugin ========================= Location plugin for Winter CMS v2.2.0(9mo ago)66.2k↓25%6[1 issues](https://github.com/wintercms/wn-location-plugin/issues)2MITPHPPHP >=8.1CI passing Since Jul 19Pushed 9mo ago4 watchersCompare [ Source](https://github.com/wintercms/wn-location-plugin)[ Packagist](https://packagist.org/packages/winter/wn-location-plugin)[ Docs](https://github.com/wintercms/wn-location-plugin)[ GitHub Sponsors](https://github.com/wintercms)[ Fund](https://opencollective.com/wintercms)[ RSS](/packages/winter-wn-location-plugin/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (4)Dependencies (3)Versions (6)Used By (2) Location Plugin =============== [](#location-plugin) [![MIT License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](https://github.com/wintercms/wn-location-plugin/blob/main/LICENSE) This plugin adds location based features to [Winter CMS](https://wintercms.com). Supports: - Easily add Country and State to any model - Form widget for address lookups (Google API) Installation ------------ [](#installation) This plugin is available for installation via [Composer](http://getcomposer.org/). ``` composer require winter/wn-location-plugin ``` After 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). ``` php artisan migrate ``` ### Google API key requirement [](#google-api-key-requirement) As of June 22, 2016 the Google Maps service requires an API key. You may generate a key from the following link: - [Get a Google API key](https://developers.google.com/maps/documentation/javascript/get-api-key) Copy the key and enter it in the **Settings > 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=_). ### Add Country and State to any model [](#add-country-and-state-to-any-model) This plugin provides an easy way to add location fields, country and state, to any model. Simply add these columns to the database table: ``` $table->integer('country_id')->unsigned()->nullable()->index(); $table->integer('state_id')->unsigned()->nullable()->index(); ``` Then implement the **Winter.Location.Behaviors.LocationModel** behavior in the model class: ``` public $implement = ['Winter.Location.Behaviors.LocationModel']; ``` This will automatically create two "belongs to" relationships: 1. **state** - relation for Winter\\Location\\Models\\State 2. **country** - relation for Winter\\Location\\Models\\Country ### Back-end usage [](#back-end-usage) #### Forms [](#forms) You are free to add the following form field definitions: ``` country: label: winter.location::lang.country.label type: dropdown span: left placeholder: winter.location::lang.country.select state: label: winter.location::lang.state.label type: dropdown span: right dependsOn: country placeholder: winter.location::lang.state.select ``` #### Lists [](#lists) For the list column definitions, you can use the following snippet: ``` country: label: winter.location::lang.country.label searchable: true relation: country select: name sortable: false state: label: winter.location::lang.state.label searchable: true relation: state select: name sortable: false ``` ### Front-end usage [](#front-end-usage) The front-end can also use the relationships by creating a partial called **country-state** with the content: ``` {% set countryId = countryId|default(form_value('country_id')) %} {% set stateId = stateId|default(form_value('state_id')) %} Country {{ form_select_country('country_id', countryId, { id: 'accountCountry', class: 'form-control', emptyOption: '', 'data-request': 'onInit', 'data-request-update': { 'country-state': '#partialCountryState' } }) }} State {{ form_select_state('state_id', countryId, stateId, { id: 'accountState', class: 'form-control', emptyOption: '' }) }} ``` This partial can be rendered in a form with the following: ``` {% partial 'country-state' countryId=user.country_id stateId=user.state_id %} ``` ### Short code accessors [](#short-code-accessors) The 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. ``` // Softly looks up and sets the country_id and state_id // for these Country and State relations. $model->country_code = "US"; $model->state_code = "FL"; $model->save(); ``` ### ISO 3166-1 accessors [](#iso-3166-1-accessors) The 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). Availables 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). ``` $usCountry = \Winter\Location\Models\Country::whereCode('US')->first(); $usCountry->iso_name; // (string) "United States of America" $usCountry->iso_alpha3; // (string) "USA" $usCountry->iso_numeric; // (string) "840" $usCountry->iso_currencies; // (array) [ 0 => "USD" ] $usCountry->iso; // (array) [ // "name" => "United States of America" // "alpha2" => "US" // "alpha3" => "USA" // "numeric" => "840" // "currency" => [ // 0 => "USD" // ] // ] ``` ### Address Finder Form Widget [](#address-finder-form-widget) This 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. Available mappings: - street - city - zip - state - country - country-long - latitude - longitude - vicinity Available options: You 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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). Usage: ``` # =================================== # Form Field Definitions # =================================== fields: address: label: Address type: addressfinder countryRestriction: 'us,ch' fieldMap: latitude: latitude longitude: longitude city: city zip: zip country: country_code state: state_code vicinity: vicinity city: label: City zip: label: Zip country_code: label: Country state_code: label: State latitude: label: Latitude longitude: label: Longitude vicinity: label: Vicinity ``` ### Health Score 48 — FairBetter than 94% of packages Maintenance53 Moderate activity, may be stable Popularity30 Limited adoption so far Community29 Small or concentrated contributor base Maturity71 Established project with proven stability Bus Factor2 2 contributors hold 50%+ of commits 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 Every ~549 days Total 5 Last Release 291d ago Major Versions v1.1.5 → v2.0.02021-04-22 PHP version history (3 changes)v1.1.5PHP >=5.5.9 v2.0.0PHP >=7.2 v2.2.0PHP >=8.1 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/7253840?v=4)[Luke Towers](/maintainers/LukeTowers)[@LukeTowers](https://github.com/LukeTowers) --- Top Contributors [![daftspunk](https://avatars.githubusercontent.com/u/1392869?v=4)](https://github.com/daftspunk "daftspunk (44 commits)")[![mjauvin](https://avatars.githubusercontent.com/u/2013630?v=4)](https://github.com/mjauvin "mjauvin (31 commits)")[![LukeTowers](https://avatars.githubusercontent.com/u/7253840?v=4)](https://github.com/LukeTowers "LukeTowers (27 commits)")[![vojtasvoboda](https://avatars.githubusercontent.com/u/374917?v=4)](https://github.com/vojtasvoboda "vojtasvoboda (4 commits)")[![gergo85](https://avatars.githubusercontent.com/u/2959112?v=4)](https://github.com/gergo85 "gergo85 (4 commits)")[![Eoler](https://avatars.githubusercontent.com/u/680032?v=4)](https://github.com/Eoler "Eoler (3 commits)")[![WebVPF](https://avatars.githubusercontent.com/u/61043464?v=4)](https://github.com/WebVPF "WebVPF (2 commits)")[![alxy](https://avatars.githubusercontent.com/u/2057062?v=4)](https://github.com/alxy "alxy (2 commits)")[![gabsource](https://avatars.githubusercontent.com/u/1851314?v=4)](https://github.com/gabsource "gabsource (2 commits)")[![LucasZdv](https://avatars.githubusercontent.com/u/7346040?v=4)](https://github.com/LucasZdv "LucasZdv (2 commits)")[![oscarnevarezleal](https://avatars.githubusercontent.com/u/129272?v=4)](https://github.com/oscarnevarezleal "oscarnevarezleal (2 commits)")[![ribsousa](https://avatars.githubusercontent.com/u/2750974?v=4)](https://github.com/ribsousa "ribsousa (2 commits)")[![RomainMazB](https://avatars.githubusercontent.com/u/53976837?v=4)](https://github.com/RomainMazB "RomainMazB (2 commits)")[![StrangerPings](https://avatars.githubusercontent.com/u/22084825?v=4)](https://github.com/StrangerPings "StrangerPings (2 commits)")[![acasar](https://avatars.githubusercontent.com/u/6329543?v=4)](https://github.com/acasar "acasar (2 commits)")[![ametad](https://avatars.githubusercontent.com/u/1582541?v=4)](https://github.com/ametad "ametad (1 commits)")[![mohammed-alsiddeeq](https://avatars.githubusercontent.com/u/5040354?v=4)](https://github.com/mohammed-alsiddeeq "mohammed-alsiddeeq (1 commits)")[![TheServat](https://avatars.githubusercontent.com/u/12908537?v=4)](https://github.com/TheServat "TheServat (1 commits)")[![priitperna](https://avatars.githubusercontent.com/u/2284196?v=4)](https://github.com/priitperna "priitperna (1 commits)")[![pvullioud](https://avatars.githubusercontent.com/u/3446410?v=4)](https://github.com/pvullioud "pvullioud (1 commits)") --- Tags hacktoberfestcmslocationwintercms ### Embed Badge ![Health badge](/badges/winter-wn-location-plugin/health.svg) ``` [![Health](https://phpackages.com/badges/winter-wn-location-plugin/health.svg)](https://phpackages.com/packages/winter-wn-location-plugin) ``` ### Alternatives [winter/wn-seo-plugin Winter CMS plugin for managing SEO tags 106.3k](/packages/winter-wn-seo-plugin)[winter/wn-tailwindui-plugin Provides a TailwindUI-based skin for the Winter CMS backend. 1812.8k](/packages/winter-wn-tailwindui-plugin)[interaction-design-foundation/laravel-geoip Support for multiple Geographical Location services. 17221.0k3](/packages/interaction-design-foundation-laravel-geoip)[winter/wn-sitemap-plugin Sitemap plugin for Winter CMS 1042.6k1](/packages/winter-wn-sitemap-plugin)[getkirby/geo Kirby Geo 223.5k](/packages/getkirby-geo)[responsiv/currency-plugin Currency plugin for October CMS 171.3k1](/packages/responsiv-currency-plugin) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)