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.1(12mo ago)2123.1k↓62.5%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 2w ago

READMEChangelog (3)Dependencies (1)Versions (16)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

57

—

FairBetter than 98% of packages

Maintenance72

Regular maintenance activity

Popularity38

Limited adoption so far

Community36

Small or concentrated contributor base

Maturity75

Established project with proven stability

 Bus Factor1

Top contributor holds 55.7% 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 ~189 days

Recently: every ~236 days

Total

14

Last Release

360d 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 (83 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.3k10](/packages/helsingborg-stad-municipio)[rainlab/blog-plugin

Blog plugin for October CMS

17158.6k](/packages/rainlab-blog-plugin)[rainlab/builder-plugin

Builder plugin for October CMS

17147.5k1](/packages/rainlab-builder-plugin)[rainlab/sitemap-plugin

Sitemap plugin for October CMS

2280.9k1](/packages/rainlab-sitemap-plugin)

PHPackages © 2026

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