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.
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<?php2 3return [4 'enabled' => [5 'dashboard' => false,6 ],7];This is true to all following configuration arrays.
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<?php2 3return [4 'namespace' => 'App',5];You can also change the default variables that control where Twill's admin console is available:
1<?php2 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<?php2 3return [4 'admin_middleware_group' => 'web',5];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];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
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<?php2 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<?php2 3return [4 'load_default_migrations' => true,5];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];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<?php2 3return [4 'publish_date_24h' => false, // enable 24h format in publisher dates5 'publish_date_format' => 'd F Y H:i', // format used by publication date pickers6 'publish_date_display_format' => 'DD MMMM YYYY HH:mm', // format used when displaying the publication date7];1<?php2 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<?php2 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.
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.
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=local2MEDIA_LIBRARY_LOCAL_PATH=uploadsTo 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.
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=s32S3_KEY=S3_KEY3S3_SECRET=S3_SECRET4S3_BUCKET=bucket-nameOptionally, 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_KEY2S3_SECRET=S3_SECRET3S3_BUCKET=bucket-name4S3_ENDPOINT=https://YOUR_S3_DOMAINWhen 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.
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=azure2 3AZURE_ACCOUNT_KEY=AZURE_ACCOUNT_KEY4AZURE_ACCOUNT_NAME=AZURE_ACCOUNT_NAME5AZURE_CONTAINER=AZURE_CONTAINERBy 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=falseThe 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.
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:
If the media cropper is not working, it is advised to add img/* to the cors.php exceptions.
1MEDIA_LIBRARY_ENDPOINT_TYPE=local2MEDIA_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];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.netBy 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=true2IMGIX_SIGN_KEY=You should never store any sort of credentials in source control (eg. Git).
That's exactly why in the case of the Imgix signature key, we do not say that you could provide it to Twill using the sign_key configuration option of the Imgix configuration array.
Always use environment variables for credentials.
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 setslqip_default_params: used by the Low Quality Image Placeholder url functionsocial_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];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.
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=local2FILE_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.
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_KEY2S3_SECRET=S3_SECRET3S3_BUCKET=bucket-nameOptionally, 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 private.
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=falseTwill'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.
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.