Skip to main content

Configuration

Configure project settings, permissions, storage, queues, URLs, and other platform behaviour.

In this guide​

What are the available setting types?​

SettingDescription
$group->array(‘allow_list’);Returns an array.
$group->boolean(‘enabled’);Returns a boolean, true or false.
$group->eloquent('order_status', OrderStatus::class);Stores the key of the eloquent model you pass and returns an instance of the model.
$group->encrypted('api_key');Stores a string encrypted and returns the string decrypted.
$group->float('min_value');Returns a number as a float.
$group->integer('per_page');Returns a number as an integer.
$group->string(‘message’);Returns a string.
$group->date('go_live');Returns a Carbon date instance.
$group->dateRange('sale_period');Returns an array with start and end keys that hold a Carbon date instance.

What are the settings available to developers?​

Settings allow you to add dynamic values to your modules that can be modified by admin users easily through the admin.

The values of your settings (unless the value is the default you set) are stored in json files inside of your storage directory.

└─ storage
    └─ app
        └─ settings

How do I access a custom setting?​

You can access a setting by using the setting function that is available in PHP, Blade, and Twig. You simply need to pass your setting group name, a full stop, and then the settings name.

setting(‘acme-my-module.allow_list’)

Do do I set the default value of my custom setting?​

You can add a default value to any setting by using the default method and passing your default value.

<?php

namespace Acme\MyModule;

use Aero\Common\Facades\Settings;
use Aero\Common\Providers\ModuleServiceProvider;
use Aero\Common\Settings\SettingGroup;

class ServiceProvider extends ModuleServiceProvider
{
   public function setup()
   {
       Settings::group('acme-my-module', function (SettingGroup $group) {
           $group->string('denied_message')->default('Access Denied');
           $group->array('allow_list')->default(['admin']);
           $group->boolean('allow_list_enabled')->default(true);
       });
   }
}

How do I register custom settings?​

To register settings you need to use the Aero\Common\Facades\Settings facade from the setup method of your modules service provider. You should call the group method on the facade and pass in a unique name for your settings group and a closure that defines your settings group.

<?php

namespace Acme\MyModule;

use Aero\Common\Facades\Settings;
use Aero\Common\Providers\ModuleServiceProvider;
use Aero\Common\Settings\SettingGroup;

class ServiceProvider extends ModuleServiceProvider
{
   public function setup()
   {
       Settings::group('acme-my-module', function (SettingGroup $group) {
           $group->string('denied_message');
           $group->array('allow_list');
           $group->boolean('allow_list_enabled');
       });
   }
}

How do I configure the admin edit page?​

By default your setting group is editable through the admin by a generated edit page. You cannot remove this generated edit page but you can stop users from being able to edit the settings using it. It’s important to note that if you disable editing through this edit page that users can still edit the settings manually through the storage json file.

To make your setting group not editable you should call the notEditable method when defining your group.

<?php

namespace Acme\MyModule;

use Aero\Common\Facades\Settings;
use Aero\Common\Providers\ModuleServiceProvider;
use Aero\Common\Settings\SettingGroup;

class ServiceProvider extends ModuleServiceProvider
{
   public function setup()
   {
       Settings::group('acme-my-module', function (SettingGroup $group) {
           $group->string('denied_message');
           $group->array('allow_list');
           $group->boolean('allow_list_enabled');
           $group->notEditable();
       });
   }
}

Validation Rules​

These are helper methods that map to their equivalent Laravel Validation Rules. It’s important to note that these validation rules apply when saving through the generated admin edit page. These rules do not stop people from manually editing the settings storage json file to have invalid values.

RuleWorks For
$group->string('key')->required();All
$group->string('key')->between($min, $max);String, Integer, Float, Array, Encrypted
$group->string('key')->min($min);String, Integer, Float, Array, Encrypted
$group->string('key')->max($max);String, Integer, Float, Array, Encrypted
$group->string('key')->size($size);String, Integer, Float, Array, Encrypted
$group->string('key')->greaterThan($size);String, Integer, Float, Array, Encrypted
$group->string('key')->lessThan($size);String, Integer, Float, Array, Encrypted
$group->string('key')->in($needles);String, Integer, Float
$group->string('key')->email();String, Encrypted
$group->string('key')->uuid();String, Encrypted
$group->string('key')->url();String, Encrypted
$group->string('key')->ip();String, Encrypted
$group->string('key')->startsWith($needle);String, Encrypted
$group->string('key')->startsWithOneOf($needles);String, Encrypted
$group->float('key')->step($step);Float
$group->date('key')->beforeToday();Date
$group->date('key')->before($date);Date
$group->date('key')->afterToday();Date
$group->date('key')->after($date);Date

Methods​

MethodForDescription
$group->title($title);-Set the title shown in the list of settings (by default this is generated from the group name).
$group->summary($summary);-Set the summary shown in the list of settings.
$group->notEditable();-Disable editing through the generated admin page.
$group->string('key')->label($label);AllSet the label for the edit field (by default this is generated from the settings key).
$group->string('key')->hint($hint);AllAdd a helpful hint to the edit field.
$group->string('key')->textarea();StringMake the string field appear as a textarea.
$group->string('key')->wysiwyg();StringMake the string field appear as a wysiwyg.
$group->eloquent('order_status', OrderStatus::class)->searchField($field);EloquentDefine the field used for searching in the searchable select.
$group->eloquent('order_status', OrderStatus::class)->searchFields($field);EloquentDefine multiple fields used for searching in the searchable select (first field is the value).
$group->array('key')->associative();ArrayDefine the array as an associative array - an array that has a key and value.
$group->array('key')->definition($definition);ArraySet a custom definition for your array (link:section below this).
Complex Array Definitions​

If you have a complex array (an array of arrays that have multiple keys), you need to define the contents of the array and any validation for each key.

Here is a code example that defines an additional_checkboxes array that is an array of arrays. The child arrays have a text key (that has validation ensuring it is a string and required) and a required key (that has validation ensuring it is a boolean).

Although this example uses the string, required, and boolean rules you can use any Laravel Validation rule.

<?php

namespace Acme\MyModule;

use Aero\Common\Facades\Settings;
use Aero\Common\Providers\ModuleServiceProvider;
use Aero\Common\Settings\SettingGroup;

class ServiceProvider extends ModuleServiceProvider
{
   public function setup()
   {
       Settings::group('acme-my-module', function (SettingGroup $group) {
           $group->array('additional_checkboxes')->definition([
               'text' => ['string', 'required'],
               'required' => ['boolean']
           ]);
       });
   }
}

How do I handle translations?​

When defining your setting groups title/summary, or a settings label/hint you can make use of Laravel Localization for translations.

<?php

namespace Acme\MyModule;

use Aero\Common\Facades\Settings;
use Aero\Common\Providers\ModuleServiceProvider;
use Aero\Common\Settings\SettingGroup;

class ServiceProvider extends ModuleServiceProvider
{
   public function setup()
   {
       Settings::group('acme-my-module', function (SettingGroup $group) {
           $group->title(__('acme-my-module.title'));
           $group->summary(__('acme-my-module.summary'));
           $group->string('message')
               ->label(__('acme-my-module.labels.message'))
               ->hint(__('acme-my-module.hints.message'));
       });
   }
}

How do I register new permissions?​

// add a single permission
\Aero\Admin\Permissions::add('custom');

// add multiple permissions
\Aero\Admin\Permissions::add(['custom', 'custom.view', 'custom.manage']);

How do I check for permissions?​

When checking for permission, you should always be as explicit as you can. For example, checking a user has the custom.view or custom.manage permissions.

Guarding content in a Blade file:

@can('custom.view')
    ...
@endcan

@canany(['orders', 'custom'])
    ...
@endcan

Checking the admin user has permission to access an endpoint:

Route::get('/my-module', [MyModuleController::class, 'index'])
    ->name('admin.modules.my-module')
    ->middleware('can:custom.view');

Route::get('/my-module/manage', [MyModuleController::class, 'manage'])
    ->name('admin.modules.my-module.manage')
    ->middleware('can:custom.manage');

Guarding the execution of code in a Controller:

if ($this->can('custom')) {
    // ...
}

if ($this->canAny(['orders', 'custom'])) {
    // ...
}

How do I store product images on S3​

You need to configure and set up your Laravel project for the S3 storage driver. You can read more about this in the laravel documentation. This involves setting your S3 credentials in your env file (you usually need to add values for AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION, and AWS_BUCKET) and installing a composer package (league/flysystem-aws-s3-v3 ~1.0) that lets Laravel support S3.

Once your project is configured you should set STORE_FILE_DRIVER and STORE_LOCAL_FILE_DRIVER to your S3 driver. If you have followed the Laravel documentation steps above and are using the default S3 disk already created you will simply add this to your env file:

STORE_FILE_DRIVER=s3
STORE_LOCAL_FILE_DRIVER=s3

STORE_FILE_DRIVER This by default is set as public and is the disk used by Aero when uploading files that should be publicly accessible.

STORE_LOCAL_FILE_DRIVER This by default is set as local and is the disk used by Aero when uploading files that should not be publicly accessible directly.

How do I change how order references are generated?​

You can set an order reference generator to define how order references are generated. To do this you need to use the static setReferenceGenerator method on the Aero\Cart\Models\Order model.

The method accepts a closure that accepts the order as a parameter and expects you to return a string (the reference for the order passed into the closure).

If you do not set an order reference generator the default generator will be used that does the following:

<?php

namespace Acme\MyModule;

use Aero\Cart\Models\Order;
use Aero\Common\Providers\ModuleServiceProvider;

class ServiceProvider extends ModuleServiceProvider
{
   public function setup()
   {
       Order::setReferenceGenerator(function (Order $order) {
           $prefix = setting('order_reference_prefix');
           $random = substr(str_shuffle(str_repeat('0123456789', 10)), 1, 3);

           return "{$prefix}{$order->getKey()}-{$random}";
       });
   }
}

What is the robots file and how does it differ from normal?​

The robots.txt file provides instructions for web crawlers and bots that index your store. Aero automatically registers core parts of the store that should avoid being indexed and visited by bots.

In order to extend this file and add modules or store specific restrictions, the robots.txt file is processed as a pipeline, where the content (the text) is made available and can be manipulated.

For ease of access, the $content passed through the pipeline is an Illuminate\Support\Collection, grouped by the user agent.

\Aero\Store\Pipelines\RobotsTxt::extend(static function ($content) {
    if ($agent = $content->get('User-agent: *')) {
        $agent->push('Disallow: /my_module/');
    }
});

What queues does Aero use?​

Queues are used so that HTTP requests can remain snappy and more intensive code can be executed later. You can learn more about queues here.

Queue

Description

search

This queue has search jobs. The majority of these jobs will be responsible for reindexing listings.

email

This queue has email jobs. Whenever an email is sent and queued in your application, it will be in this queue.

subscriptions

This queue has subscription jobs. The majority of these jobs are responsible for creating and processing subscriptions.

default

This queue has any jobs that are not in one of the other queues. These jobs can be anything from order created event handlers to customer created event handlers.

Aero uses four queues so that you can have different workers completing different tasks without a risk of locks or jobs being handled more than once. It’s important to note that some queues should be considered more important than others (for example, processing events such as an order created event is more important than updating your search index). In a production environment you should use tools like Supervisor to manage your queue workers.

You can use the queue work command to run all of or only specific queues (if you adjust the list of queues in the command). It’s important to note that the order of the queues in the command defines their priority.

How do I add a route to the CSRF exception list?​

If you do not want your route to require a valid CSRF token, you can add it to an exceptions list through code or the project's routing configuration file. Typically you would use this for any 3rd party post-back calls.

Code​

To add a route to the exceptions list through code you need to add to the static VerifyCsrfToken::$exceptions array.

<?php

namespace Acme\MyModule;

use Aero\Common\Providers\ModuleServiceProvider;
use Aero\Store\Http\Middleware\VerifyCsrfToken;

class ServiceProvider extends ModuleServiceProvider
{
   public function setup()
   {
       VerifyCsrfToken::$exceptions[] = '/my-route';
   }
}

Configuration​

The routing configuration file has a csrf_exceptions array where you can list routes for the exceptions list.

You can publish the routing configuration file with this command:

php artisan vendor:publish --provider="Aero\Routing\Providers\RoutingServiceProvider"

Once this file is published you can view it by navigating to config/aero/routing.php in your project. You can edit the csrf_exceptions array directly in this file.

You may need to clear the config cache for your changes to take effect.

php artisan config:clear

How do I set up a slug validator?​

You can control if a collection of slugs is valid or not by setting your own validator:

\Aero\Store\Routing\Slugs::setValidator(function ($slugs, $resolver) {
    if ($resolver !== 'listings') return true;

    if ($slugs->count() < 3 && $slugs->where('model_type', 'tag')->count()) return false;

    return true;
});