grnspc/addressable

Laravel Addressable is a polymorphic Laravel package, for addressbook management. You can add addresses to any eloquent model with ease.

v2.0.1 2022-01-28 00:02 UTC

Requires

• php: ^8.0.0
• illuminate/console: ^8.0.0 || ^9.0.0
• illuminate/database: ^8.0.0 || ^9.0.0
• illuminate/support: ^8.0.0 || ^9.0.0
• jackpopp/geodistance: ^1.2.0
• rinvex/countries: ^8.1

Requires (Dev)

• codedungeon/phpunit-result-printer: ^0.30.0
• illuminate/container: ^8.0.0 || ^9.0.0
• phpunit/phpunit: ^9.5.0

MIT

• Nathan Robinson
• Rinvex LLC

README

GrnSpc Addresses is a polymorphic Laravel package, for addressbook management. You can add addresses to any eloquent model with ease.

Installation

1. Install the package via composer:

   composer require grnspc/addresses

2. Publish resources (migrations and config files):

   php artisan grnspc:publish:addresses

3. Execute migrations via the following command:

   php artisan grnspc:migrate:addresses

4. Done!

Usage

To add addresses support to your eloquent models simply use \Grnspc\Addresses\Traits\HasAddress trait.

<?php 

namespace App\Models;

use Grnspc\Addresses\Traits\HasAddresses;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    use HasAddresses;

    // ...
}

Adding an Address to a Model.

1. Method 1 - Via addAddress() Method

   This method does a valadation check.

   use App\Models\User;
   
   $user = User::find(1);
   $user->addAddress([
       'label'         => 'Default Address',
       'given_name'    => 'Nathan',
       'family_name'   => 'Robinson',
       'organization'  => 'GrnSpc',
       'line_1'        => '117 Banff Ave',
       'line_2'        => null,
       'city'          => 'Banff',
       'province'      => 'Alberta',
       'postal_code'   => 'T1L 1A4',
       'country_code'  => 'ca',
       'extra'         => [
                           'buzz_code' => '1234'    
                       ],
       'latitude'      => '51.1754012',
       'longitude'     => '-115.5715499',
       'is_primary'    => true,
       'is_billing'    => true,
       'is_shipping'   => true,
   ]);

2. Method 2 - Via Eloquent Relationship

   use App\Models\User;
   
   $user = User::find(1);
   $user->addresses()->create([
       'label'         => 'Default Address',
       'given_name'    => 'Nathan',
       'family_name'   => 'Robinson',
       'organization'  => 'GrnSpc',
       'line_1'        => '117 Banff Ave',
       'line_2'        => null,
       'city'          => 'Banff',
       'province'      => 'Alberta',
       'postal_code'   => 'T1L 1A4',
       'country_code'  => 'ca',
       'extra'         => [
                           'buzz_code' => '1234'    
                       ],
       'latitude'      => '51.1754012',
       'longitude'     => '-115.5715499',
       'is_primary'    => true,
       'is_billing'    => true,
       'is_shipping'   => true,
   ]);

3. Method 3 - Create multiple new addresses

   use App\Models\User;
   
   $user = User::find(1);
   $user->addresses()->createMany([
       [...],
       [...],
       [...],
   ]);

Updating an Address on a Model

1. Method 1 - Via updateAddress() Method

   $address = $user->addresses()->first();
   $newAttributes = [
       'label' => 'Default Work Address',
   ];
   $user->updateAddress($address, $newAttributes);

2. Method 2 - Via Eloquent Relationship

   $address = $user->addresses()->first();
   $address->update([
       'label' => 'Default Work Address',
   ]);

Deleting an Address on a Model

Delete a Single Address

1. Method 1 - Via deleteAddress() Method

   $address = $user->addresses()->first();
   
   $user->deleteAddress($address);

2. Method 2 - Via Eloquent Relationship

   $address = $user->addresses()->first();
   $address->delete();

   Alternative way of address deletion

   $user->addresses()->firstWhere('id', 123)->delete();

Delete a All Address

1. Method 1 - Via flushAddress() Method

   $user->flushAddresses();

2. Method 2 - Via Eloquent Relationship

   $user->addresses()->delete();

Address Facade

use Grnspc\Addresses\Facades\Address;

$addresses = Address::all();

Manage your Addresses on Model

The API is intuitive and very straight forward, so let's give it a quick look:

Check if a Model has Addresses

if ($user->hasAddresses()) {
    // Do something
}

Get all Addresses for a Model

// Method 1 (Collection)
$addresses = $user->addresses;

// Method 2 (Collection)
$addresses = $user->addresses()->get();

// Method 3 (Query Builder)
$addresses = $user->addresses();

// if a model only has one address

Get Latest Addresses for a Model

// address in order: only1 > is_primary > latest 
$address = $user->address;

// billing address in order: only1 > is_billing > latest
$address = $user->billing_address;

// shipping address in order: only1 > is_shipping > latest
$address = $user->shipping_address;

Scoping and Getting Primary Addresses

// return all primary addresses
$addresses = Address::isPrimary()->get()

// return all primary addresses for a model
$addresses = $user->addresses->isPrimary()->get();

Scoping and Getting Billing Addresses

// return all billing addresses
$addresses = Address::isBilling()->get()

// return all billing addresses for a model
$addresses = $user->addresses->isBilling()->get();

Scoping and Getting Shipping Addresses

// return all shipping addresses
$addresses = Address::isShipping()->get()

// return all shipping addresses for a model
$addresses = $user->addresses->isShipping()->get();

Scoping Addresses by Country

// return all addresses in country
$addresses = Address::InCountry('ca')->get()

Find all addresses within 5 kilometers radius from the latitude/longitude 51.1754012/-115.5715499

$fiveKmAddresses = User::findByDistance(5, 'kilometers', '51.1754012', '-115.5715499')->get();

// Alternative method to find users within certain radius
$user = new \App\Models\User();
$users = $user->lat('51.1754012')->lng('-115.5715499')->within(5, 'kilometers')->get();

Changelog

Refer to the Changelog for a full history of the project.

Contributing & Protocols

Thank you for considering contributing to this project! The contribution guide can be found in CONTRIBUTING.md.

Bug reports, feature requests, and pull requests are very welcome.

• Versioning
• Pull Requests
• Coding Standards
• Feature Requests
• Git Flow

Security Vulnerabilities

If you discover a security vulnerability within this project, please submit an issue. All security vulnerabilities will be promptly addressed.

License

This software is released under The MIT License (MIT).

(c) 2014-2022 GrnSpc, Some rights reserved.