Expander Laravel Package

Product Decisions This Supports

• Dynamic Data Resolution: Enables runtime expansion of nested references in API responses, configuration files, or payloads (e.g., transforming {"user": {"posts": "${user.id}"}} into fully hydrated objects). Reduces manual mapping logic in controllers/transformers.
• Configuration-Driven Features: Supports complex, declarative configurations (e.g., feature flags, multi-environment setups) where cross-references are critical. Example: ${env.DB_HOST} in config/database.php.
• Roadmap for Scalable APIs: Aligns with initiatives to standardize data expansion across microservices or monoliths, ensuring consistency in payloads like GraphQL-style nested queries.
• Build vs. Buy: Avoids reinventing reference resolution (e.g., custom recursive array traversal) while offering more flexibility than Laravel’s built-in with() or load() for Eloquent.
• Use Cases:
  • APIs: Expand ?expand=comments,author into single queries (e.g., post.comments → ${post.id}/comments).
  • Templates: Generate dynamic content (e.g., emails with ${user.name} placeholders).
  • Testing: Mock complex nested data without hardcoding (e.g., ${factories.user} → UserFactory::new()).

When to Consider This Package

• Adopt if:
  • Your app uses nested data structures (e.g., JSON APIs with expand parameters, config files with cross-references).
  • You’re fatigued by repetitive transformation logic (e.g., if ($payload['user']) { $payload['user'] = User::find($payload['user']['id']); }).
  • You need environment-aware expansions (e.g., ${env.APP_DEBUG} in logs or configs).
  • Your team prioritizes DRY principles over micro-optimizations for simple cases.
• Avoid if:
  • Data is flat (no references) or static (no runtime resolution needed).
  • You’re using Eloquent’s eager loading exclusively for all nested relationships.
  • Performance is critical for high-frequency operations (e.g., real-time systems where recursion overhead matters).
  • Your stack is non-Laravel/PHP (though the package is language-agnostic, Laravel integrations are implied).

How to Pitch It (Stakeholders)

• Executives:

  "This package cuts 20–40% of the boilerplate in our API layer by automating data expansion—think of it as a ‘templating engine for PHP arrays.’ It’s MIT-licensed, actively maintained (PHP 8.4 support), and future-proofs our configs/APIs for dynamic features like multi-tenancy or A/B testing. For example, instead of manually resolving user.posts in every endpoint, we define it once and reuse it everywhere. This reduces tech debt and accelerates feature delivery without hiring more engineers."

• Engineering (Devs/Architects):

  *"Imagine Laravel’s with() on steroids: recursive, configurable, and extensible. You can:

  • Expand ${user.posts} into a full Post collection with a single line of code.
  • Resolve environment variables (${env.API_KEY}) in configs or payloads.
  • Chain expanders for complex workflows (e.g., user → posts → comments). The package handles edge cases like circular references, null safety, and custom stringification (e.g., arrays → CSV). Zero dependency bloat—just Composer install and go. Perfect for APIs, CLI tools, or even testing data factories."*

• QA/DevOps:

  "This standardizes how we handle dynamic data, reducing bugs from inconsistent transformations. For example, if config/services.php uses ${env.DB_PASSWORD}, we no longer risk hardcoded secrets in PRs. The logger integration also helps debug expansion failures in staging/prod."