From 7aa98a6cb6de3a093788a63c69cb3a52cd5915e7 Mon Sep 17 00:00:00 2001 From: Duncan McClean Date: Wed, 9 Jul 2025 11:09:56 +0100 Subject: [PATCH 1/6] Add "Settings" section to Addons doc --- content/collections/extending-docs/addons.md | 60 ++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/content/collections/extending-docs/addons.md b/content/collections/extending-docs/addons.md index 578d9de42..a79414814 100644 --- a/content/collections/extending-docs/addons.md +++ b/content/collections/extending-docs/addons.md @@ -548,6 +548,66 @@ if ($addon->edition() === 'pro') { You don't need to check whether a license is valid, Statamic does that automatically for you. ::: +## Settings + +Laravel config files are great for storing application settings, but they're not ideal for settings you might want users to edit through the Control Panel. + +You can register a settings blueprint in your addon to give users a friendly interface for managing settings. Drop a blueprint file in `resources/blueprints/settings.yaml` or register it in your service provider like this: + +```php +public function bootAddon() +{ + $this->registerSettingsBlueprint([ + 'tabs' => [ + 'main' => [ + 'sections' => [ + [ + 'display' => __('API'), + 'fields' => [ + [ + 'handle' => 'api_key', + 'field' => ['type' => 'text', 'display' => 'API Key', 'validate' => 'required'], + ], + // ... + ], + ], + ], + ], + ], + ]); +} +``` + +Your addon's settings page will show up in the Control Panel under **Tools -> Addons**. Pretty convenient. + +You can even reference config options (and by extension environment variables) in your settings blueprint using Antlers, like so: `{{ config:app:url }}`. + +Settings are stored as YAML files in `resources/addons` by default, but can be moved to the database if you prefer. Just run the `php please install:eloquent-driver` command and you're all set. + +You can retrieve the settings using the `Addon` facade: + +```php +use Statamic\Facades\Addon; + +$addon = Addon::get('vendor/package'); + +// Getting settings... +$addon->settings()->get('api_key'); + +$addon->settings()->values(); +$addon->settings()->rawValues(); // Doesn't evaluate Antlers + +// Setting values... +$addon->settings()->set('api_key', '{{ config:services:example:api_key }}'); + +$addon->settings()->values([ + 'website_name' => 'My Awesome Site', + 'api_key' => '{{ config:services:example:api_key }}', +]); + +// Saving... +$addon->settings()->save(); +``` ## Update Scripts From f9244c69a3e2f95fb2fd7b3b96c72e50cb2c0e30 Mon Sep 17 00:00:00 2001 From: Duncan McClean Date: Wed, 9 Jul 2025 11:13:57 +0100 Subject: [PATCH 2/6] Add addons directory to Git tracked paths example --- content/collections/docs/git-automation.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/collections/docs/git-automation.md b/content/collections/docs/git-automation.md index 163a43e51..036d465a5 100644 --- a/content/collections/docs/git-automation.md +++ b/content/collections/docs/git-automation.md @@ -54,6 +54,7 @@ You are free to define the tracked paths to be considered when staging and commi 'paths' => [ base_path('content'), base_path('users'), + resource_path('addons'), resource_path('blueprints'), resource_path('fieldsets'), resource_path('forms'), From 8bfec711d1e09f4ed34d9ecad759586a74551736 Mon Sep 17 00:00:00 2001 From: Duncan McClean Date: Wed, 9 Jul 2025 12:04:31 +0100 Subject: [PATCH 3/6] Document addon settings events --- content/collections/extending-docs/events.md | 24 ++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/content/collections/extending-docs/events.md b/content/collections/extending-docs/events.md index f259161bd..fd73b910b 100644 --- a/content/collections/extending-docs/events.md +++ b/content/collections/extending-docs/events.md @@ -41,6 +41,30 @@ If you're creating an addon, you can quickly [register event listeners or subscr ## Available Events +### AddonSettingsSaved +`Statamic\Events\AddonSettingsSaved` + +Dispatched after an addon's settings have been saved. + +``` php +public function handle(AddonSettingsSaved $event) +{ + $event->addonSettings; +} +``` + +### AddonSettingsSaving +`Statamic\Events\AddonSettingsSaving` + +Dispatched before an addon's settings are saved. You can return `false` to prevent them from being saved. + +``` php +public function handle(AddonSettingsSaving $event) +{ + $event->addonSettings; +} +``` + ### AssetContainerBlueprintFound `Statamic\Events\AssetContainerBlueprintFound` From e5d6974038d357be724e3897e89c314cc4c675aa Mon Sep 17 00:00:00 2001 From: Duncan McClean Date: Mon, 14 Jul 2025 10:37:29 +0100 Subject: [PATCH 4/6] Composer commands aren't visible from the CP anymore. --- content/collections/docs/addons.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/collections/docs/addons.md b/content/collections/docs/addons.md index b49387712..fd9e2f8b1 100644 --- a/content/collections/docs/addons.md +++ b/content/collections/docs/addons.md @@ -19,7 +19,7 @@ You can use Composer to install any addon: composer require vendor/package ``` -The command can be found on the addon's page in the Control Panel or the Statamic Marketplace. +The command can be found on the addon's page in the [Statamic Marketplace](https://statamic.com/addons). :::tip Some first party addons – such as the Static Site Generator or Eloquent Driver - have their own dedicated commands which will be noted on the same pages. From 8832c2a79a3b74a78ea9d02cd2215ec658c24e85 Mon Sep 17 00:00:00 2001 From: Duncan McClean Date: Mon, 14 Jul 2025 16:47:58 +0100 Subject: [PATCH 5/6] You can't switch editions in the CP anymore --- content/collections/docs/addons.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/content/collections/docs/addons.md b/content/collections/docs/addons.md index fd9e2f8b1..d0fa6e223 100644 --- a/content/collections/docs/addons.md +++ b/content/collections/docs/addons.md @@ -49,6 +49,4 @@ You can choose which edition is installed by entering it into your `config/stata 'addons' => [ 'vendor/package' => 'pro', // e.g., 'jezzdk/statamic-google-maps' => 'pro' ] -``` - -Or, by choosing it from an addon's details view in the Control Panel. \ No newline at end of file +``` \ No newline at end of file From ce04e30ae5947d802999fc36588d29cb39f16482 Mon Sep 17 00:00:00 2001 From: Duncan McClean Date: Thu, 24 Jul 2025 13:07:17 +0100 Subject: [PATCH 6/6] update example --- content/collections/extending-docs/addons.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/collections/extending-docs/addons.md b/content/collections/extending-docs/addons.md index a79414814..be7cb2111 100644 --- a/content/collections/extending-docs/addons.md +++ b/content/collections/extending-docs/addons.md @@ -594,13 +594,13 @@ $addon = Addon::get('vendor/package'); // Getting settings... $addon->settings()->get('api_key'); -$addon->settings()->values(); -$addon->settings()->rawValues(); // Doesn't evaluate Antlers +$addon->settings()->all(); +$addon->settings()->raw(); // Doesn't evaluate Antlers // Setting values... $addon->settings()->set('api_key', '{{ config:services:example:api_key }}'); -$addon->settings()->values([ +$addon->settings()->set([ 'website_name' => 'My Awesome Site', 'api_key' => '{{ config:services:example:api_key }}', ]);