Download the PHP package divineomega/laravel-addresses without Composer

Laravel Addresses

Laravel Addresses is a package that lets you associate addresses with your Laravel Eloquent models.

Features:

• Automatic geocoding of addresses on change, provided by the Google Maps API
• Validation of address details (country, postcode)
• Conversion of ISO country code to country name
• Ability to store meta data about addresses - e.g. ['type' => 'delivery', 'name' => 'home_address']

Compatibility

This package supports Laravel versions 5.6 through 13.

Installation

To install Laravel Addresses, just run the following Composer command.

Configuration

Run the following Artisan command to publish the configuration file.

This will create the default configuration file at config/addresses.php.

Custom address model

To add relationships, accessors, or other application-specific behaviour to addresses, extend the package model and set the model configuration value to your class:

The relationship traits and model observer will both use the configured class. Custom models must extend JordJD\LaravelAddresses\Models\Address.

Note that by default, you require a Google Maps API key in order to provide address geocoding and distance calculations. If you do not wish to use geocoding, this can be disabled in the configuration.

Strict geocoding

By default, geocoding is configured as "lenient"; if, for example, the name of a real city is given but the postcode and street address refer to a nonexistent place, it will geocode as the center of that city.

Set the geocoding.strict flag to true in the configuration file to instead fail to geocode in this scenario.

Usage

Assign the HasAddresses trait to a model that can have multiple associated addresses. For example, you could give the default User model addresses, as shown below.

Retrieve addresses

One address per model

Use HasAddress instead when a model should have a single polymorphic address:

The trait provides an address() relationship:

Create new address

Geocoding

Geocoding is automatic when an address is created or updated. You can check if an address was successfully geocoding using the isGeocoded method.

You can also manually geocode the address if needed.

Note that geocoding can fail, in which case, you can detect that it failed by checking whether the address is geocoded after attempting geocoding:

If there was an existing latitude/longitude set and geocoding fails, these are cleared.

Validation

Validation is automatic when an address is created or updated. You can expect an appropriate exception to be thrown if validation fails.

• InvalidCountryException - Provided country_code is not a valid ISO 3166-1 alpha-3 country code.
• InvalidUKPostcodeException - If the address is within the UK, the provided postcode is not a valid UK postcode.

You can also manually validate the address if needed.

Distance calculation

The distance between two different addresses can be calculated using the distanceTo method.

By default the direct distance is calculated (as the crow flies). If you want, you can specify a different type of distance calculation, such as driving distance.