Download the PHP package ecourty/platform-parameter-bundle without Composer

Platform Parameter Bundle

A Symfony bundle for managing global platform parameters with type-safe access and caching.
Supports PHP 8.3+, Symfony 7.x and 8.x.

Table of Contents

• Features
• Installation
  • Optional: EasyAdmin Integration
  • Register the bundle
  • Configuration
  • Database Setup
• Configuration Reference
• Usage
  • Basic Usage
  • Available Methods
  • Cache Management
  • Parameter Types
  • Updating Parameters
  • Creating Parameters
  • Error Handling
  • CLI Commands
  • EasyAdmin CRUD Interface
  • Twig Integration
• Extending the Entity
  • Step 1: Create Your Custom Entity
  • Step 2: Configure the Bundle
  • Step 3: Update Database Schema
  • Step 4: (Optional) Create Custom EasyAdmin CRUD Controller
  • Benefits of Extending
• Development
  • Running Tests
  • Code Quality
• License

Features

• 🎯 Type-safe parameter access - Methods for STRING, INTEGER, BOOLEAN, JSON, LIST, FLOAT, and DATETIME types
• ✍️ Type-safe parameter updates - Writer service for updating values from code with validation
• ⚡ PSR-6 caching - Built-in cache support for optimal performance
• 🔧 Easy integration - Simple Symfony bundle with simple configuration
• 📦 Doctrine ORM - Entity-based storage
• 🎪 Event system - React to parameter changes with Symfony events
• 🛠️ CLI commands - Manage parameters from the command line
• 🧩 EasyAdmin support - Optional CRUD controller for EasyAdmin integration
• 🌿 Twig integration - Optional Twig functions for direct use in templates
• 🧱 Extensible entity - Create custom entities with additional fields

Installation

Optional: EasyAdmin Integration

If your project uses EasyAdmin, the bundle includes a ready-to-use CRUD controller:

Register the bundle

If you're not using Symfony Flex, add the bundle to config/bundles.php:

Important: The bundle automatically configures Doctrine ORM mappings for the entity class specified in your configuration. No manual Doctrine mapping configuration is required - just configure entity_class in your bundle settings, and the mapping is handled automatically.

Configuration

Create a configuration file config/packages/platform_parameter.yaml:

Cache Adapter Resolution

The bundle automatically creates a TagAware cache pool (platform_parameter.cache) for optimal performance out-of-the-box.

Cache adapter priority:

1. Custom adapter (if cache_adapter is specified in config)
2. Auto-created TagAware pool (platform_parameter.cache - created by default)
3. Default (cache.app as ultimate fallback)

No configuration needed! The bundle works optimally by default with TagAware support.

Example - Using a custom Redis cache pool:

Example - Overriding the default pool:

Database Setup

Run Doctrine migrations to create the platform_parameter table:

Note: This works seamlessly with custom entities extending AbstractPlatformParameter. Doctrine will automatically detect all fields (base + custom) when generating migrations.

Configuration Reference

All available configuration options with their default values:

Configuration Options Details

Usage

Basic Usage

Inject the PlatformParameterProviderInterface into your services:

Available Methods

DateTime Format Support

The getDateTime() method automatically tries these formats:

• ISO 8601: 2026-01-21T15:30:00+00:00
• MySQL datetime: 2026-01-21 15:30:00
• Date only: 2026-01-21
• French format: 21/01/2026 or 21/01/2026 15:30:00
• Unix timestamp: 1737472200
• Native parser: next monday, +1 week, etc.

Or specify a custom format:

Cache Management

The bundle automatically caches all parameters to minimize database queries. When you access a parameter (e.g., getString('site_name')), it's fetched from the database once and cached for subsequent requests. This significantly reduces database load, especially for frequently accessed parameters. The cache TTL is configurable (default: 3600 seconds / 1 hour).

Automatic Cache Clearing (Default Behavior)

By default, the bundle automatically clears the cache when you create, update, or delete a parameter using a Doctrine entity listener:

This is enabled by default via the clear_cache_on_parameter_update: true configuration option. The bundle uses a Doctrine listener that automatically wipes the cache for the parameter whenever the entity is persisted, updated, or removed.

Reacting to Parameter Changes with Events

The bundle dispatches Symfony events whenever parameters are created, updated, or deleted. This provides a simple way to react to parameter changes without configuring Doctrine listeners.

Available Events:

Example: Send notifications when parameters change

Event Details:

• PlatformParameterCreatedEvent: Contains the newly created parameter entity

  • getParameter(): AbstractPlatformParameter

• PlatformParameterUpdatedEvent: Contains the parameter entity, old value, and new value

  • getParameter(): AbstractPlatformParameter
  • getOldValue(): string - The value before the update
  • getNewValue(): string - The value after the update
• PlatformParameterDeletedEvent: Contains the parameter entity (before deletion)
  • getParameter(): AbstractPlatformParameter

Events are always dispatched, regardless of the clear_cache_on_parameter_update configuration. They work with:

• Console commands (platform-parameter:set, platform-parameter:delete)
• Direct Doctrine operations ($em->persist(), $em->flush(), $em->remove())
• EasyAdmin CRUD operations
• Any other method of modifying parameters (as long as Doctrine ORM is used)

To disable automatic cache clearing (but keep event dispatching):

Note: Disabling cache clearing means you'll need to manually call $parameterProvider->clearCache() or handle cache invalidation via event subscribers.

Manual Cache Clearing

You can still manually clear the cache when needed:

Note: When clearing all caches, the bundle:

1. If using TagAwareAdapter: Uses tags for efficient invalidation
2. Otherwise: Fetches all parameters from DB and deletes their cache items individually

Optimizing Cache Performance

The bundle automatically creates a TagAware cache pool for optimal performance. No additional configuration is needed!

Benefits:

• ✅ Efficient bulk cache invalidation via tags
• ✅ clearCache() without parameters is O(1) instead of O(n)
• ✅ Works out-of-the-box without manual configuration

Advanced - Using Redis for better performance:

The bundle will automatically use your custom platform_parameter.cache pool if defined.

Parameter Types

The bundle supports 7 parameter types:

Updating Parameters

The bundle provides a PlatformParameterWriter service for updating parameter values from your code with type safety:

Writer Methods:

Important Notes:

• The Writer only updates existing parameters - it does not create new ones
• Type validation: throws ParameterTypeMismatchException if you try to set a value with the wrong type (e.g., setInt() on a STRING parameter)
• Throws ParameterNotFoundException if the parameter doesn't exist

Why no auto-creation? If you use a custom entity extending AbstractPlatformParameter with additional required fields (category, icon, etc.), the Writer doesn't know how to populate them. Parameter creation must be explicit.

Creating Parameters

Parameters must be created using Doctrine entities directly:

This is the only way to create parameters. It ensures:

• All required fields are populated (key, value, type, label)
• Custom entity fields are properly initialized
• You have full control over parameter metadata

Error Handling

If a parameter doesn't exist and no default value is provided, a ParameterNotFoundException is thrown:

CLI Commands

The bundle provides convenient console commands to manage parameters:

List all parameters

Displays a table with all parameters showing their key, value (truncated if too long), type, and label.

View a specific parameter

Shows all metadata for a parameter including ID, key, value, type, label, description, and timestamps.

Update a parameter value

Behavior:

• Updates the value of an existing parameter
• Automatically detects parameter type and converts value accordingly
• Returns error if parameter doesn't exist

Note: This command only updates existing parameters. To create new parameters, use Doctrine entities directly (see "Creating Parameters" section).

Delete a parameter

Asks for confirmation before deletion (unless --force is used).

Clear parameter cache

Manually clears the cache for one or all parameters. Useful if automatic cache clearing is disabled.

EasyAdmin CRUD Interface

If you have EasyAdmin installed, you can use the included CRUD controller to manage parameters.

Register the controller in your EasyAdmin dashboard:

The CRUD controller includes:

• ✅ All CRUD operations (Create, Read, Update, Delete)
• ✅ Field validation and help text
• ✅ Badge colors for parameter types
• ✅ Truncated value display in list view

Optional - Customizing the Controller:

If you need to customize the controller behavior (e.g., change titles, add custom fields, modify permissions), you can extend it:

Then reference your custom controller in the dashboard instead:

Twig Integration

If Twig is installed in your project, the bundle automatically registers a Twig extension providing functions to read parameters directly in templates. No additional configuration is needed.

Available Twig functions:

All functions return null (instead of throwing an exception) when the parameter is not found and no default is provided.

Examples:

Extending the Entity

The bundle is designed to be extensible. You can create your own entity that extends the base AbstractPlatformParameter to add custom fields.

Step 1: Create Your Custom Entity

Step 2: Configure the Bundle

Update your platform_parameter.yaml configuration:

Step 3: Update Database Schema

Step 4: (Optional) Create Custom EasyAdmin CRUD Controller

If you added custom fields and want them in EasyAdmin:

Benefits of Extending

• ✅ Add custom metadata: category, tags, sort order, icon, etc.
• ✅ Keep core functionality: All bundle methods work with your custom entity
• ✅ Type-safe access: The provider continues to work seamlessly
• ✅ No code duplication: Inherit all base fields and methods
• ✅ EasyAdmin compatible: Custom fields integrate naturally

Development

Running Tests

Code Quality

License

MIT License - see LICENSE file for details.