Option Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require creavo/option-bundle
   

   Add to config/bundles.php (Symfony 4+):

   return [
       // ...
       Creavo\OptionBundle\CreavoOptionBundle::class => ['all' => true],
   ];
   

2. Configure (config/packages/creavo_option.yaml):

   creavo_option:
       fetch_all: false  # Set to `true` if you need all options loaded eagerly
       simple_cache_service: 'cache.app'  # Optional: PSR-16 cache service
   

3. Run migrations:

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

First Use Case

Set a basic option via CLI:

php bin/console crv:ob:set site_maintenance_mode "false" boolean system

Retrieve it in PHP:

$maintenanceMode = $this->get('crv.option')->get('site_maintenance_mode');

Implementation Patterns

Core Workflows

1. Service Integration:

   • Inject crv.option service into controllers/services:

     public function __construct(private OptionService $optionService) {}
     

   • Use set()/get() for dynamic values:

     $this->optionService->set('feature_flag.new_ui', true, 'boolean', 'features');
     $isEnabled = $this->optionService->get('feature_flag.new_ui');
     

2. Twig Integration:

   • Access options directly in templates:

     {% if crv_ob_setting('feature_flag.new_ui') %}
         <div class="new-ui">...</div>
     {% endif %}
     

3. Console Automation:

   • Batch-set options via CLI:

     # Set multiple options from a file
     while IFS= read -r line; do
         php bin/console crv:ob:set "$line"
     done < options.txt
     

Advanced Patterns

• Caching Strategies:

  • Disable caching for volatile options:

    $this->optionService->getUnCached('live_stats.refresh_rate');
    

  • Use fetch_all: true in config for read-heavy apps (reduces DB queries).

• Type-Safe Values:

  • Leverage types (boolean, integer, dateTime) for validation:

    $this->optionService->set('max_retries', 3, 'integer', 'limits');
    

• Section-Based Organization:

  • Group related options (e.g., system, features, limits) for logical separation.

Gotchas and Tips

Common Pitfalls

1. Cache Invalidation:

   • getUnCached() bypasses cache but hits the DB. Use sparingly in performance-critical paths.
   • Clear cache manually if options are updated externally:

     php bin/console cache:clear
     

2. Type Mismatches:

   • Incorrect types (e.g., storing "true" as boolean) cause runtime errors. Validate types during set():

     if (!is_bool($value)) {
         throw new \InvalidArgumentException('Value must be boolean');
     }
     

3. Schema Updates:

   • After updating the bundle, run migrations:

     php bin/console doctrine:migrations:execute 'DoctrineMigrations\VersionYYYYMMDDHHMMSS'
     

Debugging Tips

• Inspect Options:

  php bin/console crv:ob:list  # List all options
  php bin/console crv:ob:get option_name  # Debug a specific option
  

• Query Logging: Enable Doctrine logging to trace DB queries:

  # config/packages/dev/doctrine.yaml
  doctrine:
      dbal:
          logging: true
  

Extension Points

1. Custom Cache Backend:

   • Implement Psr\SimpleCache\CacheInterface and inject via config:

     creavo_option:
         simple_cache_service: 'my_custom_cache'
     

2. Event Listeners:

   • Extend functionality by subscribing to option.set/option.get events (if the bundle supports them; check source for hooks).

3. Validation Rules:

   • Override the Option entity to add custom validation (e.g., regex for strings):

     // src/Entity/Option.php
     use Symfony\Component\Validator\Constraints as Assert;
     
     /**
      * @Assert\Regex("/^[a-z0-9_-]+$/i")
      */
     private $name;