Parameter Objects Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony/Dependency Injection (DI) Alignment: The bundle leverages Symfony’s autowiring system to replace traditional scalar/array parameters with typed Parameter Objects (POs). This aligns well with modern Symfony (5.4+) architectures where strict typing and immutability are prioritized.
• Domain-Driven Design (DDD) Synergy: POs encapsulate configuration/parameters as domain-specific objects, improving readability and maintainability—especially in large applications with complex parameter sets (e.g., API clients, feature flags, or multi-tenant configs).
• Alternative to Config Services: Reduces reliance on ParameterBag or Container for non-environment-specific parameters, promoting separation of concerns between runtime configs (e.g., parameters.yaml) and domain logic.

Integration Feasibility

• Low Friction for Symfony Apps: Designed as a Symfony Bundle, integration follows standard practices (composer install, bundle enablement). No PHP version constraints beyond Symfony’s LTS support.
• Backward Compatibility: Non-breaking changes for existing autowiring (scalars/arrays still work). Migration can be incremental (see Integration Approach).
• Tooling Support: Works with Symfony’s autowiring analyzer and PHPStan for static type checking.

Technical Risk

• Overhead for Simple Apps: Adds complexity for projects with trivial parameter needs (e.g., a single DATABASE_URL). Risk of YAGNI violation if not justified by scale.
• Debugging Complexity: PO-based parameters may obscure runtime overrides (e.g., env vars) if not explicitly handled. Requires discipline in constructor injection vs. service overrides.
• Symfony Version Lock: Tied to Symfony’s DI component; potential deprecation risk if Symfony shifts autowiring strategies (e.g., PHP 8.2+ attributes).

Key Questions

1. Parameter Complexity: How many parameters are currently managed as scalars/arrays? Are they domain-specific (e.g., PaymentGatewayConfig) or infrastructure (e.g., CacheSettings)?
2. Team Maturity: Does the team use strict typing and autowiring extensively? Resistance may stem from unfamiliarity with PO patterns.
3. Override Mechanisms: How are parameters currently overridden (env vars, config files)? Will POs require custom merge strategies?
4. Testing Impact: Will POs simplify or complicate parameter-based tests (e.g., mocking configs in unit tests)?
5. Performance: For high-throughput apps, does PO instantiation add measurable overhead compared to scalar access?

Integration Approach

Stack Fit

• Symfony Ecosystem: Native support for Symfony 5.4+ (LTS). Compatible with:
  • Autowiring: Replaces autowire: true for services with PO parameters.
  • Framework Bundles: Works alongside Mercure, API Platform, or Messenger for config-heavy features.
  • PHP 8.0+: Leverages named arguments and constructor property promotion for cleaner POs.
• Non-Symfony PHP: Limited utility; bundle is Symfony-specific. For vanilla PHP, consider standalone PO classes with manual DI.

Migration Path

1. Assessment Phase:
   • Audit parameters used in service constructors (via phpstan or symfony/var-dumper).
   • Categorize by complexity (e.g., ['timeout' => 30, 'retries' => 3] → ConnectionConfig PO).
2. Incremental Rollout:
   • Step 1: Replace simple scalars (e.g., int $timeout) with POs in new services.
   • Step 2: Refactor legacy services using decorators or interface segregation to avoid big-bang changes.
   • Step 3: Replace array configs (e.g., ['driver' => 'pdo']) with immutable POs.
3. Tooling:
   • Use PHPStan to enforce PO usage in constructors.
   • Generate initial POs via script (e.g., parse services.yaml for scalar/array params).

Compatibility

• Symfony Features:
  • ParameterBag: POs can coexist but should replace dynamic configs (e.g., parameter('app.some_config') → new AppConfig()).
  • Env Vars: Use %env(int)% in PO constructors for runtime overrides.
  • Compiler Passes: Extendable for dynamic PO generation (e.g., from YAML).
• Third-Party Risks:
  • Libraries using ContainerInterface directly may need updates to accept POs.
  • Doctrine or Monolog configs: Replace config: YAML with POs where applicable.

Sequencing

Operational Impact

Maintenance

• Pros:
  • Self-Documenting: PO names (e.g., S3BucketConfig) clarify purpose vs. magic strings.
  • Immutable by Design: Reduces bugs from accidental parameter mutation.
  • IDE Support: Autocomplete for PO properties (e.g., $config->timeout).
• Cons:
  • Boilerplate: Requires defining classes for every parameter group.
  • Merge Conflicts: PO changes may affect multiple services (vs. single scalar updates).

Support

• Debugging:
  • Pro: Stack traces show PO class names, not array keys.
  • Con: Deeply nested POs may obscure the source of a misconfiguration.
• Runtime Overrides:
  • Workaround Needed: Env vars must be explicitly mapped to PO properties (e.g., via %env(int)% in constructor).
  • Tooling: Consider a custom ParameterObjectCompilerPass to auto-generate POs from env vars.

Scaling

• Performance:
  • Minimal Overhead: PO instantiation is cheap; impact is negligible unless creating thousands per request.
  • Caching: POs can be singletons for immutable configs (e.g., AppConfig::DEFAULT).
• Horizontal Scaling:
  • No impact; POs are stateless and thread-safe (unlike shared ParameterBag).

Failure Modes

Ramp-Up

• Developer Onboarding:
  • Training: 1-hour session on PO patterns and autowiring.
  • Coding Standards: Enforce PO naming conventions (e.g., *Config, *Settings).
• Documentation:
  • ADR: Justify PO adoption for future devs.
  • Cheat Sheet: PO → Env Var mapping examples.
• Metrics:
  • Track parameter-related bugs pre/post-adoption.
  • Measure developer satisfaction via surveys (e.g., "Easier to debug configs?").

Recommendation: Proceed with pilot adoption in a high-parameter-density module (e.g., payment processing) to validate benefits before full rollout. Pair with PHPStan and autowiring checks to enforce consistency.