Configuration

Twill's default configuration allows you to get up and running quickly by providing environment variables.

Of course, you can override any of Twill's provided configurations values from the empty config/twill.php file that was published in your app when you ran the twill:install command.

# Enabled features

You can opt-in or opt-out from certain Twill features using the enabled array in your config/twill.php file. Values presented in the following code snippet are Twill's defaults:

 1<?php
 2 
 3return [
 4    'enabled' => [
 5        'users-management' => true,
 6        'media-library' => true,
 7        'file-library' => true,
 8        'block-editor' => true,
 9        'buckets' => true,
10        'users-image' => false,
11        'settings' => true,
12        'dashboard' => true,
13        'search' => true,
14        'users-description' => false,
15        'activitylog' => true,
16        'users-2fa' => false,
17        'users-oauth' => false,
18        'permissions-management' => false,
19    ],
20];

You do not need to override entire arrays of configuration options. For example, if you only want to disable Twill's dashboard, you do not need to include to entire enabled array to your own config/twill.php configuration file:

1<?php
2 
3return [
4    'enabled' => [
5        'dashboard' => false,
6    ],
7];

This is true to all following configuration arrays.

# Global configuration

By default, Twill uses Laravel default application namespace App. You can provide your own using the namespace configuration in your config/twill.php file:

1<?php
2 
3return [
4    'namespace' => 'App',
5];

You can also change the default variables that control where Twill's admin console is available:

1<?php
2 
3return [
4    'admin_app_url' => env('ADMIN_APP_URL', null),
5    'admin_app_path' => ltrim(env('ADMIN_APP_PATH', env('ADMIN_APP_URL', null) ? '' : 'admin'), '/'),
6    'admin_app_strict' => env('ADMIN_APP_STRICT', false),
7];

If you have specific middleware needs, you can specify a custom middleware group for Twill's admin console routes:

1<?php
2 
3return [
4    'admin_middleware_group' => 'web',
5];

Twill registers its own exception handler in all controllers. If you need to customize it (to report errors on a 3rd party service like Sentry or Rollbar for example), you can opt-out from it in your config/twill.php file:

1<?php
2 
3return [
4    'bind_exception_handler' => false,
5];

And then extend it from your own app/Exceptions/Handler.php class:

 1<?php
 2 
 3namespace App\Exceptions;
 4 
 5use A17\Twill\Exceptions\Handler as ExceptionHandler;
 6use Exception;
 7use Illuminate\Auth\AuthenticationException;
 8 
 9class Handler extends ExceptionHandler
10...

If you would like to provide custom tables names, use the following configuration options:

 1<?php
 2 
 3return [
 4    'blocks_table' => 'twill_blocks',
 5    'features_table' => 'twill_features',
 6    'fileables_table' => 'twill_fileables',
 7    'files_table' => 'twill_files',
 8    'mediables_table' => 'twill_mediables',
 9    'medias_table' => 'twill_medias',
10    'password_resets_table' => 'twill_password_resets',
11    'related_table' => 'twill_related',
12    'settings_table' => 'twill_settings',
13    'tagged_table' => 'twill_tagged',
14    'tags_table' => 'twill_tags',
15    'users_oauth_table' => 'twill_users_oauth',
16    'users_table' => 'twill_users',
17];

# TwillConfig Facade

As of Twill 3.x we are slowly transitioning to a new way of setting config. While this will not be added for all options some can be set using the TwillConfig facade in your app service provider:

 1...
 2use A17\Twill\Facades\TwillConfig;
 3 
 4class AppServiceProvider extends ServiceProvider
 5{
 6    public function register(): void
 7    {
 8        TwillConfig::maxRevisions(5);
 9    }
10}

Possible options are:

TwillConfig::maxRevisions(int): Limits the max amount of revision for all revisionable content. This can be overwritten on a model level, see setting model revisions

# Migrations configuration

Since Laravel 5.8, migrations generated by Laravel use big integers on the id column. Twill migrations helpers can be configured to use regular integers for backwards compatibility.

1<?php
2 
3return [
4    'migrations_use_big_integers' => true,
5];

Since Twill 2.0, migrations are not published anymore but loaded automatically in Twill's service provider. Set to false to prevent this from happening if you need to customize Twill's tables.

1<?php
2 
3return [
4    'load_default_migrations' => true,
5];

# Locale configuration

Since Twill 2.0, Twill's own UI can be translated using lang files. Users can choose their own preferred languages in their own settings, but you might actually want to default to another language than English for all your users. You can use the following configuration for example to set Twill's default CMS language to French:

1return [
2    'locale' => 'fr',
3    'fallback_locale' => 'en',
4];

# Publisher date and time format configuration

To change the format of the publication fields when using publish_start_date and publish_end_date on your model you can change these keys in twill.php.

1<?php
2 
3return [
4    'publish_date_24h' => false, // enable 24h format in publisher dates
5    'publish_date_format' => 'd F Y H:i', // format used by publication date pickers
6    'publish_date_display_format' => 'DD MMMM YYYY HH:mm', // format used when displaying the publication date
7];

# Multiple subdomains CMS routing

1<?php
2 
3return [
4    'support_subdomain_admin_routing' => false,
5    'admin_app_subdomain' => 'admin',
6    'active_subdomain' => null,
7];

Enabling this allows adding top level keys to Twill's navigation and dashboard modules configuration, mapping to a subdomain. This is a very simple way to implement multi-tenant CMS/sites in Twill. A navigation array looking like the following would expose your CMS on the admin.subdomain1.app-url.test and admin.subdomain2.app-url.test urls, with its corresponding links:

 1<?php
 2 
 3return [
 4    'subdomain1' => [
 5        'module1' => [...],
 6        ...
 7    ],
 8    'subdomain2' => [
 9        'module2' => [...]
10        ...
11    ]
12];

App name can be set per subdomain using the 'twill.app_names' configuration array. For our example above:

1<?php
2 
3return [
4  'app_names' => [
5    'subdomain1' => 'App 1 name',
6    'subdomain2' => 'App 2 name',
7  ],
8];

Subdomain configuration nesting also applies to the dashboard modules key.

You can also provide a custom block_single_layout per subdomain by creating a Blade file under resources/views/subdomain/layouts/blocks.

# Media library

The media_library configuration array in config/twill.php allows you to provide Twill with your configuration for the media library disk, endpoint type and others options depending on your endpoint type. Most options can be controlled through environment variables, as you can see in the default configuration provided:

 1<?php
 2 
 3return [
 4    'media_library' => [
 5        'disk' => 'twill_media_library',
 6        'endpoint_type' => env('MEDIA_LIBRARY_ENDPOINT_TYPE', 'local'),
 7        'cascade_delete' => env('MEDIA_LIBRARY_CASCADE_DELETE', false),
 8        'local_path' => env('MEDIA_LIBRARY_LOCAL_PATH', 'uploads'),
 9        'image_service' => env('MEDIA_LIBRARY_IMAGE_SERVICE', 'A17\Twill\Services\MediaLibrary\Glide'),
10        'acl' => env('MEDIA_LIBRARY_ACL', 'private'),
11        'filesize_limit' => env('MEDIA_LIBRARY_FILESIZE_LIMIT', 50),
12        'allowed_extensions' => ['svg', 'jpg', 'gif', 'png', 'jpeg'],
13        'init_alt_text_from_filename' => true,
14        'prefix_uuid_with_local_path' => config('twill.file_library.prefix_uuid_with_local_path', false),
15        'translated_form_fields' => false,
16        'show_file_name' => false,
17        'media_caption_use_wysiwyg' => false,
18        'media_caption_wysiwyg_options' => [
19            'modules' => [
20                'toolbar' => [
21                    'bold',
22                    'italic',
23                ],
24            ],
25        ],
26    ],
27];

Twill's media library supports the following endpoint types: s3, azure and local.

# Local endpoint

By default, Twill stores media and files in the local filesystem, if you want you can specify this using the following environment variables.

1MEDIA_LIBRARY_ENDPOINT_TYPE=local
2MEDIA_LIBRARY_LOCAL_PATH=uploads

To avoid running into too large errors when uploading to your server, you can choose to limit uploads through Twill using the MEDIA_LIBRARY_FILESIZE_LIMIT environment variable or filesize_limit configuration option. It is set to 50mb by default. Make sure to setup your PHP and webserver (apache, nginx, ....) to allow for the upload size specified here.

When using the s3 endpoint type, uploads are not limited in size.

# S3 endpoint

As an alternative, Twill can use the s3 endpoint type to store your uploads on an AWS S3 bucket. To authorize uploads to S3, provide your application with the following environment variables:

1MEDIA_LIBRARY_ENDPOINT_TYPE=s3
2S3_KEY=S3_KEY
3S3_SECRET=S3_SECRET
4S3_BUCKET=bucket-name

Optionally, you can use the S3_REGION variable to specify a region other than S3's default region (us-east-1).

If you prefer to use another S3 compliant storage such as Minio, provide your application with the following environment variables:

1S3_KEY=S3_KEY
2S3_SECRET=S3_SECRET
3S3_BUCKET=bucket-name
4S3_ENDPOINT=https://YOUR_S3_DOMAIN

When uploading images to S3, Twill sets the acl parameter to private. This is because images in your bucket should not be publicly accessible when using a service like Imgix on top of it. Only Imgix should have read-only access to your bucket, while your application obviously needs to have write access. If you intend to access images uploaded to S3 directly, set the MEDIA_LIBRARY_ACL variable or acl configuration option to public-read.

# Azure endpoint

Twill supports azure endpoint type to store your uploads on an Microsoft Azure container.

To authorize uploads to Azure, provide your application with the following environment variables:

1MEDIA_LIBRARY_ENDPOINT_TYPE=azure
2 
3AZURE_ACCOUNT_KEY=AZURE_ACCOUNT_KEY
4AZURE_ACCOUNT_NAME=AZURE_ACCOUNT_NAME
5AZURE_CONTAINER=AZURE_CONTAINER

# Cascading uploads deletions

By default, Twill will not delete images when deleting from Twill's media library UI, wether it is on S3 or locally.

You can decide to physically delete uploaded images using the cascade_delete option, which is also controlled through the MEDIA_LIBRARY_CASCADE_DELETE boolean environment variable:

1MEDIA_LIBRARY_CASCADE_DELETE=false

# Allowed extensions

The allowed_extensions configuration option is an array of file extensions that Twill's media library's uploader will accept. By default, svg, jpg, gif, png and jpeg extensions are allowed.

# Images rendering

To render uploaded images, Twill's preferred service is Imgix.

If you do not want or cannot use a third party service, or have very limited image rendering needs, Twill also provides a (default) local image rendering service powered by Glide. The following .env variables should get you up and running:

1MEDIA_LIBRARY_ENDPOINT_TYPE=local
2MEDIA_LIBRARY_IMAGE_SERVICE="A17\Twill\Services\MediaLibrary\Glide"

If you want to add support for other image formats, which aren't covered by Glide, you can specify an array of extensions. For files matching the ending, the original media URL will be returned, instead of the modified one. For this, you can specify the following configuration key: glide.original_media_for_extensions

 1<?php
 2 
 3return [
 4    'source' => env('GLIDE_SOURCE', storage_path('app/public/' . config('twill.media_library.local_path'))),
 5    'source_path_prefix' => env('GLIDE_SOURCE_PATH_PREFIX', null),
 6    'cache' => env('GLIDE_CACHE', storage_path('app')),
 7    'cache_path_prefix' => env('GLIDE_CACHE_PATH_PREFIX', 'glide_cache'),
 8    'base_url' => env('GLIDE_BASE_URL', config('app.url')),
 9    'base_path' => env('GLIDE_BASE_PATH', 'img'),
10    'use_signed_urls' => env('GLIDE_USE_SIGNED_URLS', false),
11    'sign_key' => env('GLIDE_SIGN_KEY'),
12    'driver' => env('GLIDE_DRIVER', 'gd'),
13    'add_params_to_svgs' => false,
14    'default_params' => [
15        'fm' => 'jpg',
16        'q' => '80',
17        'fit' => 'max',
18    ],
19    'lqip_default_params' => [
20        'fm' => 'gif',
21        'blur' => 100,
22        'dpr' => 1,
23    ],
24    'social_default_params' => [
25        'fm' => 'jpg',
26        'w' => 900,
27        'h' => 470,
28        'fit' => 'crop',
29    ],
30    'cms_default_params' => [
31        'q' => '60',
32        'dpr' => '1',
33    ],
34    'presets' => [],
35    'original_media_for_extensions' => ['svg'],
36];

# Imgix

As noted above, Twill can use and recommends using Imgix to transform, optimize, and intelligently cache your uploaded images.

Specify your Imgix source url using the IMGIX_SOURCE_HOST environment variable or source_host configuration option.

1MEDIA_LIBRARY_IMAGE_SERVICE="A17\Twill\Services\MediaLibrary\Imgix"
2IMGIX_SOURCE_HOST=source.imgix.net

By default, Twill will render Imgix urls with the https scheme. We do not see any reason why you would do so nowadays, but you can decide to opt-out using the IMGIX_USE_HTTPS environment variable or use_https configuration option.

Imgix offers the ability to use signed urls to prevent users from accessing images without parameters or different parameters than the ones you choose to use in your own application. You can enable that feature in Twill using the IMGIX_USE_SIGNED_URLS environment variable or use_signed_urls configuration option. If you enable signed urls, Imgix provides you with a signature key. Provide it to Twill using the IMGIX_SIGN_KEY environment variable.

1IMGIX_USE_SIGNED_URLS=true
2IMGIX_SIGN_KEY=

Finally, Twill's default Imgix configuration includes 4 different image transformation parameter sets that are used by helpers you will find in the media library's documentation:

• default_params: used by all image url functions in A17\Twill\Services\MediaLibrary\Imgix but overridden by the following parameter sets
• lqip_default_params: used by the Low Quality Image Placeholder url function
• social_default_params: used by the social image url function (for Facebook, Twitter, ... shares)
• cms_default_params: used by the CMS image url function. This only affects rendering of images in Twill's admin console (eg. in the media library and image fields).

See Imgix's API reference for more information about those parameters.

 1<?php
 2 
 3return [
 4    'imgix' => [
 5        'source_host' => env('IMGIX_SOURCE_HOST'),
 6        'use_https' => env('IMGIX_USE_HTTPS', true),
 7        'use_signed_urls' => env('IMGIX_USE_SIGNED_URLS', false),
 8        'sign_key' => env('IMGIX_SIGN_KEY'),
 9        'add_params_to_svgs' => false,
10        'default_params' => [
11            'fm' => 'jpg',
12            'q' => '80',
13            'auto' => 'compress,format',
14            'fit' => 'min',
15        ],
16        'lqip_default_params' => [
17            'fm' => 'gif',
18            'auto' => 'compress',
19            'blur' => 100,
20            'dpr' => 1,
21        ],
22        'social_default_params' => [
23            'fm' => 'jpg',
24            'w' => 900,
25            'h' => 470,
26            'fit' => 'crop',
27            'crop' => 'entropy',
28        ],
29        'cms_default_params' => [
30            'q' => 60,
31            'dpr' => 1,
32        ],
33    ],
34];

# File library

The file_library configuration array in config/twill.php allows you to provide Twill with your configuration for the file library disk, endpoint type and other options depending on your endpoint type. Most options can be controlled through environment variables, as you can see in the default configuration provided:

 1<?php
 2 
 3return [
 4    'file_library' => [
 5        'disk' => 'twill_file_library',
 6        'endpoint_type' => env('FILE_LIBRARY_ENDPOINT_TYPE', 'local'),
 7        'cascade_delete' => env('FILE_LIBRARY_CASCADE_DELETE', false),
 8        'local_path' => env('FILE_LIBRARY_LOCAL_PATH', 'uploads'),
 9        'file_service' => env('FILE_LIBRARY_FILE_SERVICE', 'A17\Twill\Services\FileLibrary\Disk'),
10        'acl' => env('FILE_LIBRARY_ACL', 'public-read'),
11        'filesize_limit' => env('FILE_LIBRARY_FILESIZE_LIMIT', 50),
12        'allowed_extensions' => [],
13        'prefix_uuid_with_local_path' => false,
14    ],
15];

Twill's file library supports the following endpoint types: s3, azure, and local.

# Local endpoint

This is the default configration in Twill. But you can still define the FILE_LIBRARY_LOCAL_PATH environment variable or the file_library.local_path configuration option to provide Twill with your preferred upload path. Always include a trailing slash like in the following example:

1FILE_LIBRARY_ENDPOINT_TYPE=local
2FILE_LIBRARY_LOCAL_PATH=uploads/

To avoid running into too large errors when uploading to your server, you can choose to limit uploads through Twill using the FILE_LIBRARY_FILESIZE_LIMIT environment variable or filesize_limit configuration option. It is set to 50mb by default. Make sure to setup your PHP and webserver (apache, nginx, ....) to allow for the upload size specified here. When using the s3 endpoint type, uploads are not limited in size.

# S3 endpoint

As alternative you can use the s3 endpoint type to store your uploads on an AWS S3 bucket. To authorize uploads to S3, provide your application with the following environment variables:

1S3_KEY=S3_KEY
2S3_SECRET=S3_SECRET
3S3_BUCKET=bucket-name

Optionally, you can use the S3_REGION variable to specify a region other than S3's default region (us-east-1).

When uploading files to S3, Twill sets the acl parameter to public-read. This is because Twill's default file service produces direct S3 urls. If you do not intend to access files uploaded to S3 directly, set the FILE_LIBRARY_ACL variable or acl configuration option to public-read.

# Cascading uploads deletions

By default, Twill will not delete files when deleting from Twill's file library's UI, wether it is on S3 or locally.

You can decide to physically delete uploaded files using the cascade_delete option, which is also controlled through the FILE_LIBRARY_CASCADE_DELETE boolean environment variable:

1FILE_LIBRARY_CASCADE_DELETE=false

# Files url service

Twill's provided service for files creates direct urls to the disk they were uploaded to (ie. S3 urls or urls on your domain depending on your endpoint type). You can change the default service using the FILE_LIBRARY_FILE_SERVICE environment variable or the file_library.file_service configuration option.

See the file library's documentation for more information.

# Allowed extensions

The allowed_extensions configuration option is an array of file extensions that Twill's file library uploader will accept. By default, it is empty, all extensions are allowed.