Registering Options

Modules can be extended with customizable options, enabling developers to configure settings or adapt features without modifying the module’s core code.

Options can be managed either via the CLI or the Administration interface. For detailed usage, see Manage Options.

Informations

• All options are stored in the options table.
• Uninstalling a module automatically deletes its options to prevent leftover configuration.

How to declare your options ?

1. Implement the Interface

   Your module must implement the Epsicube\Support\Contracts\HasOptions interface.

   use Epsicube\Support\Contracts\HasOptions;
   use Epsicube\Schemas\Properties\StringProperty;
   use Epsicube\Schemas\Schema;
   
   class ExternalApiModule extends ServiceProvider implements HasOptions, Module
   {
       //...
       public function options(Schema $schema): void
       {
           $schema->append([
               'api_token' => StringProperty::make()->title('Api Token')->default('XXX-XXXXX-XXX'),
           ]);
       }
   }

2. Understand Options Schema

   Each option is defined through a declarative Schema, which specifies the field types, default values, and the rules applied when options are read or updated.

   The Schema acts as a centralized layer of description: it formalizes the structure of your configuration and ensures consistent behavior across both the CLI and the Administration interface.

   For an in-depth overview of available field types, validation mechanisms, and advanced behaviors, refer to the dedicated section: Defining Schemas.

3. Use Your options

   The Options facade allows you to retrieve, update, and delete options for your module:

   Caution

   Using Options during the registration phase can cause lifecycle issues.
   Avoid using it at this stage.

   use Epsicube\Support\Facades\Options;
   
   // Retrieve all options for a module
   Options::all('your-module-identifier');
   
   // Retrieve a specific option
   Options::get('your-module-identifier', 'api_token');
   
   // Update an option
   Options::set('your-module-identifier', 'api_token', 'new_value');
   
   // Delete an option to revert to default
   Options::delete('your-module-identifier', 'api_token');