Parameter Objects Bundle Laravel Package

Product Decisions This Supports

• Improved Developer Experience (DX):

  • Reduces boilerplate in Symfony applications by replacing scalar/array parameters with strongly-typed objects, easing autowiring and IDE support.
  • Aligns with modern PHP/Symfony best practices (e.g., DDD, SOLID principles) by promoting explicit, self-documenting parameter definitions.

• Roadmap Acceleration:

  • Enables faster iteration on configuration-heavy features (e.g., API clients, service integrations) by decoupling parameter definitions from service logic.
  • Supports future-proofing for Symfony 7+ and PHP 8.3+ features (e.g., enums, read-only properties).

• Build vs. Buy:

  • Buy: Avoid reinventing wheel for parameter validation/transformation logic (e.g., custom DTOs, Symfony’s ParameterBag).
  • Build: Only if needing deeply customized serialization/validation beyond the bundle’s scope (e.g., dynamic parameter generation).

• Use Cases:

  • Configuration-Driven Services: E.g., payment gateways, third-party API clients where parameters are complex or frequently updated.
  • Microservices: Standardize parameter contracts across services without shared libraries.
  • Legacy Refactoring: Gradually replace config.yml/parameters.yml with typed objects in monolithic apps.

When to Consider This Package

• Adopt if:

  • Your Symfony app uses scalar/array parameters in services/controllers that require validation/transformation (e.g., API payloads, database queries).
  • You’re migrating from YAML/XML configs to PHP objects for better IDE support (autocompletion, type hints).
  • Your team prioritizes explicit over implicit parameter handling (e.g., avoiding array_merge hell).
  • You need autowiring compatibility with Symfony’s DI container without manual ArgumentResolver classes.

• Look Elsewhere if:

  • You’re not using Symfony (this is a Symfony-specific bundle).
  • Parameters are trivially simple (e.g., string $userId with no validation).
  • You require dynamic parameter generation at runtime (e.g., based on user input without predefined classes).
  • Your team lacks PHP 8.0+ (named arguments, constructor property promotion) or Symfony 5.3+.
  • You need advanced serialization (e.g., JSON:API, GraphQL) beyond what the bundle offers (consider symfony/serializer or api-platform/core).

How to Pitch It (Stakeholders)

For Executives:

"This bundle lets us replace messy YAML configs and loose arrays with self-documenting, type-safe objects for service parameters—cutting bugs in configuration-heavy workflows (e.g., payment processing, API integrations) by 30–50%. It’s a low-risk upgrade that aligns with modern PHP/Symfony standards, reducing tech debt while speeding up feature delivery. Think of it as ‘Git for parameters’—version control for your app’s configuration."

ROI:

• Dev Velocity: Faster onboarding (IDE autocompletion) and fewer runtime errors.
• Maintainability: Parameters are now testable units (e.g., mock PaymentGatewayConfig in unit tests).
• Scalability: Future-proofs the codebase for microservices or complex integrations.

Risk:

• Minimal (drop-in replacement for existing parameters; backward-compatible).

For Engineering:

*"This bundle solves two pain points:

1. Autowiring Hell: No more manually resolving arrays or scalar values in services. Define a CreateUserRequest object once, and Symfony’s DI container handles the rest.
2. Validation/Transformation: Attach logic (e.g., sanitization, default values) to parameters once, in their class definition, rather than duplicating it across services.

Example:

// Before: Messy and error-prone
public function __construct(
    array $apiConfig,
    string $timeout,
    ?int $retryLimit = null
) {
    $this->config = array_merge([
        'timeout' => 30,
        'retry_limit' => 3,
    ], $apiConfig);
}

// After: Clean, type-safe, and self-validating
public function __construct(
    private ApiConfig $config,  // Autowired automatically!
) {}

Why Now?

• If you’re tired of ParameterBag or manual parameter parsing, this is a 10x improvement.
• Works seamlessly with Symfony’s existing tools (e.g., Validator, Serializer).
• Zero runtime overhead—just a compile-time/autowiring optimization.

Trade-offs:

• Requires PHP 8.0+ (named args, constructor promotion).
• Not a silver bullet for dynamic parameters (e.g., user-generated queries)."*

Next Steps:

1. Pilot: Replace 1–2 high-complexity services (e.g., a payment service) to measure DX gains.
2. Tooling: Add a make:parameter-object Artisan command to scaffold new objects.
3. Docs: Update team on migration path from YAML/arrays to objects.