Json Builder Laravel Package

Product Decisions This Supports

• API/Backend Standardization: Adopt a consistent JSON serialization approach across Laravel/PHP services, reducing ad-hoc json_encode() calls and improving maintainability.
• Data Transformation Pipeline: Enable granular control over JSON escaping (e.g., embedding raw JS, HTML, or non-JSON-compliant values) for use cases like:
  • Dynamic frontend payloads (e.g., embedding JS snippets in API responses).
  • Legacy system integrations requiring non-standard JSON formats.
  • Debugging tools or admin panels where raw data inspection is critical.
• Build vs. Buy: Replace custom JSON builders or json_encode() hacks with a battle-tested, Symfony-backed library (leveraging PropertyAccess for path-based manipulation).
• Roadmap: Phase out legacy JSON serialization logic in favor of a centralized builder, reducing technical debt.
• Security: Explicitly control escaping to mitigate XSS risks when embedding user-generated content in JSON responses.

When to Consider This Package

• Avoid if:
  • Your use case requires strict JSON compliance (no need for escaping control) → Use Laravel’s built-in json_encode() or Response::json().
  • You’re using PHP 8+ with native JSON extensions → Modern PHP’s json_encode() is optimized and sufficient for most cases.
  • Your team lacks Symfony/PropertyAccess familiarity → Adds minor learning curve for path-based value setting.
  • You need high-performance serialization → This library adds abstraction overhead; consider json_encode() or specialized libraries like Spatie’s Array to JSON.
• Consider if:
  • You need fine-grained escaping control (e.g., embedding JS, HTML, or non-JSON values).
  • Your JSON structure is dynamic or path-based (e.g., nested updates via PropertyAccess syntax).
  • You’re already using Symfony components (PropertyAccess) in your stack.
  • You require PHP 5.6+ compatibility with modern tooling (e.g., Docker, CI/CD).

How to Pitch It (Stakeholders)

For Executives:

"This package standardizes how we generate JSON responses across our Laravel services, reducing bugs and tech debt. It’s like a ‘JSON assembly line’—we can now safely embed custom data (e.g., JS snippets, debug info) without security risks, while keeping the codebase clean. Low risk (MIT license, 100% test coverage), high reward for edge cases like our [specific use case, e.g., dynamic frontend payloads]."

For Engineers:

*"Replace scattered json_encode() calls with a fluent, path-based JSON builder that:

• Controls escaping (e.g., setValue('[key]', '<script>...</script>', false) for raw HTML/JS).
• Leverages Symfony’s PropertyAccess for nested data manipulation (e.g., setValue('[user][profile][0]', 'value')).
• Integrates seamlessly with Laravel (Composer-friendly, PSR-4 autoloading). Example:

$builder
    ->setValues(['user' => ['name' => 'Alice']])
    ->setValue('[user][script]', '<alert>Hello!</alert>', false) // Raw HTML
    ->build();
// Output: {"user":{"name":"Alice","script":"<alert>Hello!</alert>"}}

Why? Fewer bugs, reusable logic, and explicit control over JSON output."*

For Security/Compliance Teams:

"This package explicitly manages JSON escaping, reducing XSS risks when embedding user-generated content. Unlike json_encode(), it lets us opt-out of escaping for trusted contexts (e.g., admin panels, debug tools) while defaulting to safe behavior. MIT license + 100% test coverage = low risk."