PHPackages                             rainlab/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. rainlab/location-plugin

ActiveOctober-plugin[Utility & Helpers](/categories/utility)

rainlab/location-plugin
=======================

Location plugin for October CMS

v2.0.3(2mo ago)2123.5k↑33.3%473proprietaryPHPPHP ^8.0.2CI passing

Since Oct 5Pushed 1mo ago8 watchersCompare

[ Source](https://github.com/rainlab/location-plugin)[ Packagist](https://packagist.org/packages/rainlab/location-plugin)[ Docs](https://octobercms.com/plugin/rainlab-location)[ RSS](/packages/rainlab-location-plugin/feed)WikiDiscussions master Synced 4w ago

READMEChangelog (3)Dependencies (2)Versions (17)Used By (3)

Location plugin
===============

[](#location-plugin)

This plugin adds location based features to [October CMS](https://octobercms.com).

- Easily add Country and State to any model
- Form widget for address lookups (Google API)

View this plugin on the October CMS marketplace:

-

### Extended features

[](#extended-features)

To integrate locations with front-end users, consider also installing the `RainLab.UserPlus` plugin.

-

### Google API key requirement

[](#google-api-key-requirement)

Using 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->bigInteger('country_id')->unsigned()->nullable()->index();
$table->bigInteger('state_id')->unsigned()->nullable()->index();
```

Then implement the **RainLab\\Location\\Traits\\LocationModel** trait in the model class:

```
use \RainLab\Location\Traits\LocationModel;
```

This will automatically create two "belongs to" relationships:

1. **state** - relation for RainLab\\Location\\Models\\State
2. **country** - relation for RainLab\\Location\\Models\\Country

### Back-end usage

[](#back-end-usage)

#### Forms

[](#forms)

You are free to add the following form field definitions:

```
country:
    label: Country
    type: dropdown
    span: left
    placeholder: -- select country --

state:
    label: State
    type: dropdown
    span: right
    dependsOn: country
    placeholder: -- select state --
```

#### Lists

[](#lists)

For the list column definitions, you can use the following snippet:

```
country:
    label: Country
    searchable: true
    relation: country
    select: name
    sortable: false

state:
    label: State
    searchable: true
    relation: state
    select: name
    sortable: false
```

### Front-end usage

[](#front-end-usage)

The front-end can also use the relationships by rendering the `@form-select-country` and `@form-select-state` partials provided by the location component. Before proceeding, make sure you have the `location` component attached to the page or layout.

```

    Country
    {% partial '@form-select-country' countryId=user.country_id %}

    State
    {% partial '@form-select-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();
```

### Tailor Content Fields

[](#tailor-content-fields)

This plugin provides `country` and `state` content field types for use in Tailor blueprints. These fields render as dropdowns populated with countries and states from the location database.

#### Country Field

[](#country-field)

```
fields:
    country:
        label: Country
        type: country
        span: auto
        placeholder: -- select country --
```

#### State Field

[](#state-field)

The state field automatically depends on a country field to filter its options.

```
fields:
    state:
        label: State
        type: state
        span: auto
        countryFrom: country
        placeholder: -- select state --
```

The `countryFrom` option specifies which country field to source the country from (defaults to `country`). The `dependsOn` attribute is applied automatically.

#### Full Example

[](#full-example)

```
fields:
    country:
        label: Country
        type: country
        span: auto

    state:
        label: State
        type: state
        span: auto
        countryFrom: country
```

### 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)).

By default the `street` mapper places the house number before the street name. However in some countries the number is commonly placed after the street name. You can reverse the order by using the `reverseStreetNumber: true` option.

Usage:

```
# ===================================
#  Form Field Definitions
# ===================================

fields:
    address:
        label: Address
        type: addressfinder
        countryRestriction: 'us,ch'
        reverseStreetNumber: false
        fieldMap:
            latitude: latitude
            longitude: longitude
            city: city
            zip: zip
            street: street
            country: country_code
            state: state_code
            vicinity: vicinity

    city:
        label: City
    zip:
        label: Zip
    street:
        label: Street
    country_code:
        label: Country
    state_code:
        label: State
    latitude:
        label: Latitude
    longitude:
        label: Longitude
    vicinity:
        label: Vicinity
```

### License

[](#license)

This plugin is an official extension of the October CMS platform and is free to use if you have a platform license. See [EULA license](LICENSE.md) for more details.

###  Health Score

63

—

FairBetter than 99% of packages

Maintenance91

Actively maintained with recent releases

Popularity40

Moderate usage in the ecosystem

Community36

Small or concentrated contributor base

Maturity76

Established project with proven stability

 Bus Factor1

Top contributor holds 57.1% of commits — single point of failure

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 ~200 days

Recently: every ~306 days

Total

15

Last Release

61d ago

Major Versions

1.x-dev → v2.0.02024-05-01

PHP version history (2 changes)v1.0.8PHP >=5.5.9

v2.0.0PHP ^8.0.2

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/106532?v=4)[october](/maintainers/october)[@october](https://github.com/october)

---

Top Contributors

[![daftspunk](https://avatars.githubusercontent.com/u/1392869?v=4)](https://github.com/daftspunk "daftspunk (88 commits)")[![LukeTowers](https://avatars.githubusercontent.com/u/7253840?v=4)](https://github.com/LukeTowers "LukeTowers (8 commits)")[![acasar](https://avatars.githubusercontent.com/u/6329543?v=4)](https://github.com/acasar "acasar (5 commits)")[![inalto](https://avatars.githubusercontent.com/u/6382732?v=4)](https://github.com/inalto "inalto (5 commits)")[![octoberapp](https://avatars.githubusercontent.com/u/6543374?v=4)](https://github.com/octoberapp "octoberapp (5 commits)")[![vojtasvoboda](https://avatars.githubusercontent.com/u/374917?v=4)](https://github.com/vojtasvoboda "vojtasvoboda (4 commits)")[![Eoler](https://avatars.githubusercontent.com/u/680032?v=4)](https://github.com/Eoler "Eoler (4 commits)")[![gergo85](https://avatars.githubusercontent.com/u/2959112?v=4)](https://github.com/gergo85 "gergo85 (4 commits)")[![samgeorges](https://avatars.githubusercontent.com/u/4927493?v=4)](https://github.com/samgeorges "samgeorges (4 commits)")[![oscarnevarezleal](https://avatars.githubusercontent.com/u/129272?v=4)](https://github.com/oscarnevarezleal "oscarnevarezleal (2 commits)")[![gabsource](https://avatars.githubusercontent.com/u/1851314?v=4)](https://github.com/gabsource "gabsource (2 commits)")[![ribsousa](https://avatars.githubusercontent.com/u/2750974?v=4)](https://github.com/ribsousa "ribsousa (2 commits)")[![StrangerPings](https://avatars.githubusercontent.com/u/22084825?v=4)](https://github.com/StrangerPings "StrangerPings (2 commits)")[![LucasZdv](https://avatars.githubusercontent.com/u/7346040?v=4)](https://github.com/LucasZdv "LucasZdv (2 commits)")[![alxy](https://avatars.githubusercontent.com/u/2057062?v=4)](https://github.com/alxy "alxy (2 commits)")[![vosco88](https://avatars.githubusercontent.com/u/14372933?v=4)](https://github.com/vosco88 "vosco88 (1 commits)")[![voveson](https://avatars.githubusercontent.com/u/6799654?v=4)](https://github.com/voveson "voveson (1 commits)")[![WebVPF](https://avatars.githubusercontent.com/u/61043464?v=4)](https://github.com/WebVPF "WebVPF (1 commits)")[![ametad](https://avatars.githubusercontent.com/u/1582541?v=4)](https://github.com/ametad "ametad (1 commits)")[![boyfromhell](https://avatars.githubusercontent.com/u/4071890?v=4)](https://github.com/boyfromhell "boyfromhell (1 commits)")

---

Tags

locationoctoberoctobercms

### Embed Badge

![Health badge](/badges/rainlab-location-plugin/health.svg)

```
[![Health](https://phpackages.com/badges/rainlab-location-plugin/health.svg)](https://phpackages.com/packages/rainlab-location-plugin)
```

###  Alternatives

[helsingborg-stad/municipio

A bootstrap theme for creating municipality sites.

4028.6k10](/packages/helsingborg-stad-municipio)[rainlab/builder-plugin

Builder plugin for October CMS

17147.8k1](/packages/rainlab-builder-plugin)[rainlab/blog-plugin

Blog plugin for October CMS

17159.3k](/packages/rainlab-blog-plugin)[october/rain

October Rain Library

1601.7M99](/packages/october-rain)[mediawiki/maps

Adds various mapping features to MediaWiki

85155.1k3](/packages/mediawiki-maps)[rainlab/user-plugin

User plugin for October CMS

11955.3k15](/packages/rainlab-user-plugin)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)