Getting Started

Minimal Steps

Installation

composer require acs/acspanel-settings

Add to AppKernel.php (Laravel 5.x) or config/bundles.php (Laravel 6+):

ACS\ACSPanelSettingsBundle\ACSACSPanelSettingsBundle::class,

Define Settings Create app/main/config/panel_settings.yml with your structure:

user_settings:
  - { setting_key: 'theme', label: 'Theme', field_type: 'choice', choices: { light: 'Light', dark: 'Dark' } }
system_settings:
  - { setting_key: 'maintenance_mode', label: 'Maintenance Mode', field_type: 'boolean' }

First Use Case Trigger setting generation by visiting /settings (or your configured route). The bundle auto-creates database entries for new fields.

Implementation Patterns

Core Workflows

Field Types & Validation Leverage built-in field types (choice, boolean, text, number) or extend via custom Doctrine types. Example for a custom field:
```
user_settings:
  - { setting_key: 'custom_color', label: 'Custom Color', field_type: 'text', validation: 'color' }
```

Context-Based Settings Use context to scope settings (e.g., admin, user):

user_settings:
  - { setting_key: 'notifications', label: 'Email Notifications', context: 'user', field_type: 'boolean' }

Dynamic Defaults Set defaults in YAML or override via SettingManager:

$this->getSettingManager()->setDefault('system', 'maintenance_mode', false);

Route Integration Register routes in routing.yml:

acs_panel_settings:
    resource: "@ACSACSPanelSettingsBundle/Resources/config/routing.yml"
    prefix:   /admin

Twig Integration Access settings in templates:

{% if app.settings.get('theme') == 'dark' %}
    <body class="dark-mode">
{% endif %}

Advanced Patterns

Event Listeners Hook into acs_panel_settings.save to react to changes:

$eventDispatcher->addListener('acs_panel_settings.save', function ($event) {
    // Log or broadcast changes
});

API Endpoints Expose settings via API:

Route::get('/api/settings', function () {
    return response()->json($this->getSettingManager()->getAll());
});

Gotchas and Tips

Pitfalls

Database Schema Mismatch
- If panel_settings.yml changes, clear cache and visit /settings to regenerate entries.
- Use migrations for critical schema changes:
```
php bin/console doctrine:migrations:diff
```

Caching Issues

Settings are cached by default. Bypass with:

$this->getSettingManager()->get('key', [], true); // Force refresh

Permission Handling

System settings require ROLE_SUPER_ADMIN. Validate in controllers:

if (!$this->get('security.authorization_checker')->isGranted('ROLE_SUPER_ADMIN')) {
    throw $this->createAccessDeniedException();
}

YAML Syntax Errors
- Validate YAML with:
```
php -m yaml panel_settings.yml
```

Debugging Tips

Log Missing Settings Enable debug mode and check var/log/dev.log for missing keys or contexts.

Dump All Settings

dd($this->getSettingManager()->getAll());

Extension Points

Custom Field Types Extend ACS\ACSPanelSettingsBundle\Form\Type\SettingType for new field types.

Override Templates Copy Resources/views/Settings/ to your bundle and override:

{# app/Resources/ACSACSPanelSettingsBundle/views/Settings/index.html.twig #}

Modify SettingManager Override ACS\ACSPanelSettingsBundle\Doctrine\SettingManager for custom logic (e.g., encryption):
```
acsacs_panel_settings:
    settings_class: AppBundle\Doctrine\CustomSettingManager
```

Acspanel Settings Laravel Package