Parameter Job Bundle Laravel Package

Getting Started

First Steps

1. Installation: Run composer require balkent/parameter-job-bundle in your Symfony project. If not using Flex, manually add the bundle to config/bundles.php:

   Balkent\ParameterJobBundle\BalkentParameterJobBundle::class => ['all' => true],
   

2. Configuration: Publish the default config with:

   php bin/console config:dump-reference BalkentParameterJobBundle
   

   Then customize config/packages/balkent_parameter_job.yaml (if auto-generated) or manually define it in config/packages/.

3. First Use Case: Define a job parameter in config/packages/balkent_parameter_job.yaml:

   balkent_parameter_job:
       jobs:
           my_job:
               parameters:
                   - name: "timeout"
                     value: 30
                     type: "integer"
   

   Access it in a service or command via the container:

   $this->getParameter('balkent_parameter_job.jobs.my_job.parameters.timeout');
   

Implementation Patterns

Workflow Integration

1. Job Parameter Management:

   • Use the bundle to centralize job-specific parameters (e.g., timeouts, retries, payloads) in config/packages/balkent_parameter_job.yaml.
   • Example for a Symfony Messenger job:

     balkent_parameter_job:
         jobs:
             send_email_job:
                 parameters:
                     - name: "max_retries"
                       value: 3
                       type: "integer"
                     - name: "template"
                       value: "emails/welcome"
                       type: "string"
     

   • Inject parameters into job handlers via dependency injection:

     use Symfony\Component\DependencyInjection\ParameterBag\ParameterBagInterface;
     
     public function __construct(
         private ParameterBagInterface $params
     ) {}
     
     public function __invoke(EmailMessage $message): void {
         $maxRetries = $this->params->get('balkent_parameter_job.jobs.send_email_job.parameters.max_retries');
     }
     

2. Dynamic Job Configuration:

   • Override parameters per environment (e.g., config/packages/dev/balkent_parameter_job.yaml):

     balkent_parameter_job:
         jobs:
             send_email_job:
                 parameters:
                     - name: "template"
                       value: "emails/welcome_dev"  # Override for dev
     

3. Validation:

   • Leverage Symfony’s validator to enforce parameter types/values. Extend the bundle’s ParameterValidator (if needed) or validate manually:

     $value = $this->params->get('balkent_parameter_job.jobs.my_job.parameters.timeout');
     assert(is_int($value), 'Timeout must be an integer');
     

4. Command-Line Access:

   • Dump job parameters for debugging:

     php bin/console debug:container | grep balkent_parameter_job
     

Gotchas and Tips

Pitfalls

1. Parameter Naming Collisions:

   • Avoid naming conflicts with existing Symfony parameters. Prefix job parameter names (e.g., balkent_parameter_job.jobs.my_job.parameters.*) to ensure uniqueness.

2. Type Safety:

   • The bundle does not enforce type casting. Validate types manually or extend the bundle’s ParameterLoader to add runtime checks:

     // Example: Extend ParameterLoader to cast values
     use Balkent\ParameterJobBundle\Loader\ParameterLoaderInterface;
     
     class StrictParameterLoader implements ParameterLoaderInterface {
         public function load(array $config): array {
             foreach ($config['jobs'] as &$job) {
                 foreach ($job['parameters'] as &$param) {
                     $param['value'] = $this->castValue($param['value'], $param['type']);
                 }
             }
             return $config;
         }
     
         private function castValue($value, string $type): mixed {
             return match ($type) {
                 'integer' => (int)$value,
                 'boolean' => filter_var($value, FILTER_VALIDATE_BOOLEAN),
                 default => $value,
             };
         }
     }
     

3. Caching:

   • Parameters are loaded once during container compilation. Clear the cache (php bin/console cache:clear) after modifying balkent_parameter_job.yaml.

4. Environment-Specific Overrides:

   • Use Symfony’s %env% placeholders for dynamic values:

     balkent_parameter_job:
         jobs:
             my_job:
                 parameters:
                     - name: "api_key"
                       value: "%env(APP_API_KEY)%"
     

Tips

1. Parameter Groups:

   • Organize parameters by job type (e.g., email_jobs, report_jobs) for better maintainability:

     balkent_parameter_job:
         jobs:
             email_jobs:
                 parameters:
                     - name: "default_from"
                       value: "noreply@example.com"
             report_jobs:
                 parameters:
                     - name: "schedule"
                       value: "0 0 * * *"
     

2. Debugging:

   • Dump all job parameters for debugging:

     $jobParams = $this->getParameter('balkent_parameter_job.jobs');
     dump($jobParams);
     

3. Extension Points:

   • Override the bundle’s ParameterLoader or ParameterValidator to add custom logic (e.g., database-backed parameters, encrypted values).

4. Testing:

   • Mock parameters in tests using Symfony’s ParameterBag:

     $container->setParameter('balkent_parameter_job.jobs.test_job.parameters.timeout', 60);
     

5. Documentation:

   • Add a ParameterJob section to your project’s README to document available job parameters and their purposes.

```markdown
## Extension Points
{Optional: Add this section if the package offers clear extension hooks}

### Custom Parameter Sources
Extend the bundle to load parameters from external sources (e.g., database, API):
1. Implement `Balkent\ParameterJobBundle\Loader\ParameterLoaderInterface`:
   ```php
   class DatabaseParameterLoader implements ParameterLoaderInterface {
       public function load(array $config): array {
           $dbParams = $this->fetchFromDatabase();
           return array_merge_recursive($config, $dbParams);
       }
   }

2. Register the loader in services.yaml:

   services:
       Balkent\ParameterJobBundle\Loader\ParameterLoaderInterface:
           class: App\Service\DatabaseParameterLoader
           tags: ['balkent_parameter_job.loader']
   

Parameter Validation

Add custom validation rules by extending Balkent\ParameterJobBundle\Validator\ParameterValidator:

class CustomParameterValidator extends ParameterValidator {
    public function validate(array $parameters): void {
        parent::validate($parameters);
        // Add custom checks (e.g., API key format)
        if (isset($parameters['api_key']) && !preg_match('/^[a-z0-9]{32}$/', $parameters['api_key'])) {
            throw new \InvalidArgumentException('Invalid API key format');
        }
    }
}

Register the validator in services.yaml:

services:
    Balkent\ParameterJobBundle\Validator\ParameterValidatorInterface:
        class: App\Validator\CustomParameterValidator
        tags: ['balkent_parameter_job.validator']

Dynamic Parameter Reloading

For development, reload parameters without clearing the cache by implementing a custom command:

use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

class ReloadJobParametersCommand extends Command {
    protected function configure(): void {
        $this->setName('app:reload-job-parameters');
    }

    protected function execute(InputInterface $input, OutputInterface $output): int {
        $container = $this->getApplication()->getKernel()->getContainer();
        $loader = $container->get('balkent_parameter_job.loader');
        $container->setParameter('balkent_parameter_job.jobs', $loader->load([]));
        $output->writeln('Job parameters reloaded.');
        return Command::SUCCESS;
    }
}