Addresses
Free-form addresses manager for Laravel Enso
This package works exclusively within the Enso ecosystem.
There is a front end implementation for this this api in the accessories package.
For live examples and demos, you may visit laravel-enso.com
Installation
Comes pre-installed in Enso.
Features
- can be used to attach addresses to any entity, via a polymorphic relationship
- allows saving of multiple addresses for an addresable entity
- features an easy flow for setting the default address
- comes with an additional table for Countries, with all the countries pre-populated
- brings its own free-form form for the edit and creation of addresses
- has a publishable configuration file where you can customize the module to your liking
- includes an
Addressable
trait, for defining relationships and attributes - the package as whole is designed to be extendable, so you could create custom versions for specific countries
Usage
- you may publish the configuration and customize the options as needed
- use the package's
Addresable
trait for the models you want to make addressable - insert the
Addreses
vue component where required in your pages/components, see the front end implementation docs for the available options
Configuration
Inside the config/enso/addresses.php
file, you'll find several customization options:
onDelete
, string, option that manages the case when the commentable entity is deleted and it has attached discussions. Valid options arecascade
,restrict
| default iscascade
With the cascade option, when a discussable model is deleted, the discussions attached to it are also deleted. With the restrict option, when attempting to delete a discussable model with attached discussions, an exception is thrown.
loggableMorph
, the list of entities using the addressable functionality, each mapped to its respective loggable attribute. For example:'addressable' => [ Company::class => 'name', ],
streetTypes
, the list of street types shown in the form's street type selectbuildingTypes
, same as above, for buildingslabel
, label configuration options:separator
, the separator used when composing labels, default-
attributes
, the list of attributes used for the label, default:'localityName', 'street', 'number'
Extending the addresses
In your project you may have the need to alter and or extend the addresses structure by adding/removing table columns. To achieve this, you'd need to:
- add migration(s) to your local project, making the necessary changes. Note that if using sqlite for testing, some of the migration commands may not be available
- create a local model which extends the package model and set the proper
$fillable
attribute, define relations, etc. - create a local template and set the path in addresses configuration,
under the
enso.addresses.formTemplate
key. Also, you may mark any form fields as custom and then customize them in your page, using slots (like for the VueForm). - create a new form builder, extend the one in the package (
AddressForm
), and specify theTemplatePath
to your previously created template. - create a new request validation and extend the one in the package (
ValidateAddressRequest
) - bind your local implementations of the model, request and the form builder to their package counterparts
in your local
AppServiceProvider
class AppServiceProvider extends ServiceProvider
{
public $bindings = [
ValidateAddressRequest::class => MyValidateddressRequest::class,
AddressForm::class => MyForm::class,
Address::class => MyAddress::class,
];
...
}
Note that if you just want to customize the label for the address, you may simply publish and customize the
label
section of the config (see the Configuration section above).
Publishes
php artisan vendor:publish --tag=addresses-seeder
- the seeder used for countriesphp artisan vendor:publish --tag=enso-seeders
- a common alias for when wanting to update the seeders once a newer version is released, usually used with--force
php artisan vendor:publish --tag=addresses-factory
- the factory used for addressphp artisan vendor:publish --tag=enso-seeders
- a common alias for when wanting to update the seeders once a newer version is released, usually used with--force
php artisan vendor:publish --tag=addresses-config
- configuration filephp artisan vendor:publish --tag=enso-config
- a common alias for when wanting to update the config, once a newer version is released, usually used with--force
Contributions
are welcome. Pull requests are great, but issues are good too.
License
This package is released under the MIT license.