Getting Started

Minimal Setup

Installation Add the bundle via Composer:

composer require chamilo/settings-bundle

return [
    // ...
    Chamilo\SettingsBundle\ChamiloSettingsBundle::class => ['all' => true],
];

Configuration Define settings in config/packages/chamilo_settings.yaml:

chamilo_settings:
    channels:
        default:
            settings:
                app_name: { type: text, value: 'My App' }
                max_upload_size: { type: integer, value: 10 }

First Use Case Access a setting in a controller:

use Chamilo\SettingsBundle\Settings\SettingsInterface;

public function index(SettingsInterface $settings)
{
    $appName = $settings->get('default', 'app_name');
    return new Response($appName);
}

Admin Interface Enable the admin panel by adding the route:

# config/routes.yaml
chamilo_settings_admin:
    resource: "@ChamiloSettingsBundle/Resources/config/routing/admin.yaml"
    prefix: /admin/settings

Access /admin/settings to edit settings via UI.

Implementation Patterns

Workflows

Structured Settings Organize settings by channels (e.g., default, api, frontend):

chamilo_settings:
    channels:
        api:
            settings:
                rate_limit: { type: integer, value: 100 }

Access via:

$settings->get('api', 'rate_limit');

Dynamic Types Support for text, integer, boolean, select, textarea, and custom types. Extend with:
```
custom_types:
    color: Chamilo\SettingsBundle\Type\ColorType
```

Validation Add validation rules in YAML:

settings:
    max_users: { type: integer, value: 50, validation: { min: 10, max: 100 } }

Environment Overrides Override settings per environment (e.g., config/packages/dev/chamilo_settings.yaml):

chamilo_settings:
    channels:
        default:
            settings:
                debug_mode: { type: boolean, value: true }

Event Listeners React to setting changes via events:

// src/EventListener/SettingsListener.php
public function onSettingsUpdate(SettingsUpdateEvent $event)
{
    $channel = $event->getChannel();
    $name = $event->getName();
    // Logic here
}

services:
    App\EventListener\SettingsListener:
        tags:
            - { name: kernel.event_listener, event: chamilo.settings.update, method: onSettingsUpdate }

Caching Enable caching for performance:

chamilo_settings:
    cache: true
    cache_pool: cache.app

Gotchas and Tips

Pitfalls

Channel Mismatches
- Issue: Forgetting to specify a channel when accessing settings.
```
// ❌ Throws exception
$settings->get('nonexistent_channel', 'key');
```
- Fix: Always validate channels exist in YAML or dynamically.
Type Casting
- Issue: Incorrect type handling (e.g., select values not validated).
```
settings:
    theme: { type: select, value: 'dark', choices: ['light', 'dark'] }
```
- Fix: Ensure choices are exhaustive and use validation for strict checks.
Admin Route Conflicts
- Issue: Overlapping routes with other bundles (e.g., Symfony’s config).
- Fix: Customize the admin prefix or use _controller in routing.
Serialization Errors
- Issue: Complex objects (e.g., arrays with non-scalar values) failing to serialize.
- Fix: Use json type for complex data or flatten structures.
Cache Invalidation
- Issue: Settings not updating after changes due to stale cache.
- Fix: Clear cache manually or use cache:clear:
```
php bin/console cache:clear
```

Debugging Tips

Dump All Settings Use a twig function or controller to debug:

$settings->all(); // Returns array of all channels/settings

Or in Twig:

{{ dump(app('chamilo_settings.settings').all()) }}

Check Event Dispatching Enable debug mode to verify events fire:
```
framework:
    ide: phpstorm
```
Add a dd() in your listener to confirm triggers.
Validate YAML Use Symfony’s validator to catch YAML errors:
```
php bin/console debug:config chamilo_settings
```

Extension Points

Custom Types Create a new type class (e.g., JsonType):

namespace App\Settings\Type;

use Chamilo\SettingsBundle\Type\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\TextareaType;

class JsonType extends AbstractType
{
    public function getFormType()
    {
        return TextareaType::class;
    }

    public function getValue($value)
    {
        return json_decode($value, true);
    }
}

custom_types:
    json: App\Settings\Type\JsonType

Override Templates Customize the admin UI by overriding templates:

templates/
    ChamiloSettingsBundle/
        admin/
            settings/
                index.html.twig

Database Backend Extend to use a database (e.g., Doctrine) instead of YAML:

use Chamilo\SettingsBundle\Settings\SettingsInterface;
use Doctrine\DBAL\Connection;

class DatabaseSettings implements SettingsInterface
{
    public function __construct(private Connection $connection) {}

    public function get(string $channel, string $name, $default = null)
    {
        $stmt = $this->connection->prepare('SELECT value FROM settings WHERE channel = ? AND name = ?');
        $stmt->execute([$channel, $name]);
        return $stmt->fetchColumn() ?? $default;
    }
    // Implement other methods...
}

Bind in services.yaml:

chamilo_settings.settings:
    class: App\Settings\DatabaseSettings
    arguments:
        - '@database_connection'

API Access Expose settings via API using Symfony’s Serializer:

use Symfony\Component\Serializer\SerializerInterface;

public function getSettingsApi(SettingsInterface $settings, SerializerInterface $serializer)
{
    $data = $settings->all();
    return new JsonResponse($serializer->serialize($data, 'json'));
}

Environment-Specific Defaults Use %kernel.environment% in YAML for dynamic defaults:
```
settings:
    environment: { type: text, value: '%kernel.environment%' }
```

Settings Bundle Laravel Package