Symfony Toolkit Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

   composer require cegeka/symfony-toolkit
   

   Add the bundle to your config/bundles.php (Symfony) or composer.json (Laravel via Symfony bridge):

   Cegeka\SymfonyToolkit\SymfonyToolkitBundle::class => ['all' => true],
   

2. First Use Case: Console Commands The package provides a Command base class for consistent CLI tooling. Create a custom command:

   php bin/console make:command MyCommand
   

   Extend Cegeka\SymfonyToolkit\Command\Command in your command class for built-in helpers (e.g., logging, output formatting).

3. Key Entry Points

   • Console: src/Command/ (for CLI tools).
   • Configuration: config/packages/cegeka_symfony_toolkit.yaml (if using Symfony).
   • Services: src/Service/ (for reusable logic).

Implementation Patterns

Workflows

1. Command-Line Tooling

   • Input/Output: Use $this->output (Symfony’s OutputInterface) for colored, formatted output.

     $this->output->writeln('<info>Success!</info>');
     

   • Arguments/Options: Leverage Symfony’s Argument and Option classes for validation:

     protected function configure(): void
     {
         $this->addArgument('path', InputArgument::REQUIRED, 'File path');
         $this->addOption('force', null, InputOption::VALUE_NONE, 'Force overwrite');
     }
     

2. Service Layer

   • Dependency Injection: Inject services via constructor (Symfony-style):

     public function __construct(private FileSystem $fileSystem) {}
     

   • Reusable Logic: Extract common operations (e.g., file handling, API calls) into services:

     // src/Service/FileService.php
     public function ensureDirectoryExists(string $path): void
     {
         if (!file_exists($path)) {
             mkdir($path, 0777, true);
         }
     }
     

3. Configuration Management

   • Environment-Aware Config: Use Cegeka\SymfonyToolkit\Config\ConfigManager to load environment-specific settings:

     # config/packages/cegeka_symfony_toolkit.yaml
     cegeka_symfony_toolkit:
         environments:
             local:
                 debug: true
     

     Access via:

     $config = $this->getContainer()->get('cegeka_symfony_toolkit.config_manager');
     $debugMode = $config->get('debug'); // Returns `true` in local env.
     

4. Event-Driven Extensions

   • Custom Events: Dispatch events for extensibility:

     $this->getEventDispatcher()->dispatch(
         new MyCustomEvent($data),
         MyCustomEvent::NAME
     );
     

   • Listeners: Register listeners in services.yaml:

     services:
         App\EventListener\MyListener:
             tags:
                 - { name: 'kernel.event_listener', event: 'my_custom_event', method: 'onEvent' }
     

Gotchas and Tips

Pitfalls

1. Symfony vs. Laravel Integration

   • Laravel Users: The package is Symfony-first. Use a bridge like symfony/console or laravel/symfony-bundle for Laravel compatibility.
   • Service Container: Laravel’s container differs from Symfony’s. Alias services in config/app.php:

     'aliases' => [
         'cegeka.config_manager' => App\Services\ConfigManager::class,
     ],
     

2. Configuration Overrides

   • Priority Issues: Toolkit config may override your settings. Use !imports in Symfony’s config/packages/cegeka_symfony_toolkit.yaml to prevent accidental overrides:

     imports:
         - { resource: cegeka_symfony_toolkit.yaml, !ignore_errors }
     

3. Command Autowiring

   • Missing Commands: Ensure commands are tagged as console.command in services.yaml:

     services:
         App\Command\MyCommand:
             tags: ['console.command']
     

Debugging Tips

1. Output Formatting

   • Use $this->output->section() for grouped output:

     $this->output->section('Processing Files');
     $this->output->writeln('File 1: OK');
     

2. Environment Detection

   • Debug environment variables with:

     $env = $this->getContainer()->get('kernel')->getEnvironment();
     $this->output->writeln(sprintf('Environment: <comment>%s</comment>', $env));
     

3. Service Debugging

   • Dump services in a command:

     $services = $this->getContainer()->getServiceIds();
     file_put_contents('services.txt', print_r($services, true));
     

Extension Points

1. Custom Command Helpers

   • Extend Cegeka\SymfonyToolkit\Command\Command to add shared methods:

     // src/Command/BaseCommand.php
     abstract class BaseCommand extends Command
     {
         protected function logProgress(string $message): void
         {
             $this->output->writeln(sprintf('<fg=yellow>%s</>', $message));
         }
     }
     

2. Dynamic Configuration

   • Load config from external sources (e.g., .env):

     $configManager = $this->getContainer()->get('cegeka_symfony_toolkit.config_manager');
     $configManager->addLoader(function () {
         return ['custom_key' => getenv('CUSTOM_VALUE')];
     });
     

3. Event Subscribers

   • Subscribe to kernel events for pre/post hooks:

     // src/EventSubscriber/MySubscriber.php
     class MySubscriber implements EventSubscriberInterface
     {
         public static function getSubscribedEvents(): array
         {
             return [
                 KernelEvents::TERMINATE => 'onTerminate',
             ];
         }
     
         public function onTerminate(KernelEvent $event): void
         {
             // Cleanup logic
         }
     }