Getting Started

Minimal Setup

Install via Composer

composer require brazilianfriendsofsymfony/settings-management-bundle:dev-master

(Note: Use dev-master as the package lacks stable releases.)

Register the Bundle Add to app/AppKernel.php:

new BFOS\SettingsManagementBundle\BFOSSettingsManagementBundle(),

Enable Routes Import in app/config/routing.yml:

bfos_settings_management:
    resource: "@BFOSSettingsManagementBundle/Resources/config/routing.yml"

Configure Security Roles Define in app/config/config.yml:

bfos_settings_management:
    security:
        admin_role: ROLE_ADMIN
        super_admin_role: ROLE_SUPER_ADMIN

First Use Case Access the admin panel at /admin/settings (requires ROLE_ADMIN). The bundle provides a UI for CRUD operations on settings stored in the database.

Implementation Patterns

Core Workflow

Define Settings Structure Extend the bundle’s Setting entity (located at src/BFOS/SettingsManagementBundle/Entity/Setting.php) or create a custom entity mapping to a table like settings with columns:
- name (string, unique)
- value (text)
- type (string, e.g., text, boolean, array)
- group (string, for categorization).
Integrate with Twig Fetch settings in templates:
```
{{ app.settings.get('site_name') }}
```
(Requires a service to bridge the bundle’s storage with Twig; see Extension Points.)
Admin Panel Usage
- Add/Edit Settings: Use the built-in UI at /admin/settings.
- Grouping: Organize settings by group (e.g., site, mail) for better UX.
- Validation: Leverage Symfony’s validation constraints (e.g., @Assert\NotBlank) on the value field.
Frontend Integration The bundle relies on jQuery, RequireJS, and ckEditor for the admin UI. Ensure these are loaded in your base template:
```
{{ include('BFOSSettingsManagementBundle::scripts.html.twig') }}
```

Caching Settings Cache frequently accessed settings in a service:

// src/AppBundle/Service/SettingsService.php
class SettingsService {
    private $settings;
    public function __construct(SettingRepository $repo) {
        $this->settings = $repo->findAll();
    }
    public function get($name) { /* ... */ }
}

Advanced Patterns

Dynamic Forms: Override the admin template (BFOSSettingsManagementBundle:Settings:edit.html.twig) to customize input types (e.g., dropdowns for type="select").
Environment-Specific Settings: Use Symfony’s parameter system to override settings per environment (e.g., parameters.yml).

Event Listeners: Subscribe to settings.updated events to trigger actions (e.g., cache invalidation):

// src/AppBundle/EventListener/SettingsListener.php
class SettingsListener {
    public function onSettingsUpdated(SettingsEvent $event) {
        // Clear cache for updated setting.
    }
}

Gotchas and Tips

Pitfalls

Missing Dependencies
- The bundle requires jQuery, RequireJS, and ckEditor for the admin UI. If these are missing, the frontend will fail silently.
- Fix: Include them in your base template or configure the bundle to use alternatives (e.g., TinyMCE instead of ckEditor).
Database Schema Mismatch
- The bundle assumes a settings table with specific columns. If your schema differs, override the Setting entity or create a custom repository.
- Fix: Dump the schema from the bundle’s migrations (if provided) or inspect Entity/Setting.php.
Permission Issues
- The admin panel enforces ROLE_ADMIN/ROLE_SUPER_ADMIN. If users lack these roles, they’ll see a 403 error.
- Fix: Adjust the security config or grant roles in your firewall.
No Built-in API
- The bundle provides a UI but no REST API for settings. Fetching settings programmatically requires custom code.
- Fix: Create a controller or API platform resource to expose settings.
Lack of Documentation
- The package has minimal docs. Key classes like SettingRepository or event dispatchers are undocumented.
- Fix: Inspect the source (e.g., Entity/Setting.php, Event/SettingsEvent.php) or enable Xdebug for reverse-engineering.

Debugging Tips

Check Routes: Verify routes are loaded with:
```
php bin/console debug:router | grep bfos
```

Database Dump: Inspect the settings table:

php bin/console doctrine:schema:dump --entity="BFOS\SettingsManagementBundle\Entity\Setting"

Frontend Errors: Enable Symfony’s profiler to catch JS/CSS errors from missing dependencies.

Extension Points

Custom Entities Extend the Setting entity to add fields (e.g., created_at, updated_at):

// src/AppBundle/Entity/CustomSetting.php
class CustomSetting extends Setting {
    // Add custom fields/methods.
}

Override Templates Copy templates from vendor/brazilianfriendsofsymfony/settings-management-bundle/Resources/views/ to app/Resources/BFOSettingsManagementBundle/views/ to customize the admin UI.

Add Validation Extend the Setting entity with constraints:

use Symfony\Component\Validator\Constraints as Assert;

class Setting {
    /**
     * @Assert\Length(max=255)
     */
    private $name;
}

Event Dispatching Listen for settings.updated events to react to changes:

# app/config/services.yml
services:
    app.settings_listener:
        class: AppBundle\EventListener\SettingsListener
        tags:
            - { name: kernel.event_listener, event: settings.updated, method: onUpdate }

Twig Integration Create a custom Twig extension to simplify access:

// src/AppBundle/Twig/SettingsExtension.php
class SettingsExtension extends \Twig_Extension {
    public function getFunction($name) {
        return new \Twig_SimpleFunction('setting', [$this->settingsService, 'get']);
    }
}

{{ setting('site_name') }}

Configuration Quirks

Security Roles: The bundle uses ROLE_ADMIN/ROLE_SUPER_ADMIN by default. Customize in config.yml:

bfos_settings_management:
    security:
        admin_role: ROLE_CONFIGURATOR  # Override default.

Setting Types: The type field (e.g., text, boolean) controls how values are rendered in the admin UI. Extend this logic if you need custom types (e.g., color picker).

Settings Management Bundle Laravel Package