Jsonmapper Laravel Package

Getting Started

Install via Composer: composer require netresearch/jsonmapper. Begin by creating simple PHP classes (POPOs) that mirror your JSON structure—JsonMapper auto-populates them using reflection. For a basic use case like deserializing a user response:

use JsonMapper;

class User {
    public string $name;
    public int $age;
}

$mapper = new JsonMapper();
$json = '{"name":"Alice","age":30}';
$user = $mapper->map(json_decode($json), new User());
// Access: $user->name === 'Alice'

Check README.md for core examples and docs/ (if available) for advanced patterns like custom factories.

Implementation Patterns

• API Client DTOs: Map external API responses (e.g., Stripe, GitHub) to typed domain models without manual parsing.
• Configuration Loading: Deserialize config/*.json into typed config objects—improves validation and IDE support.
• Request/Response DTOs: In controllers or services, hydrate request bodies or API responses into structured objects, decoupling logic from raw data.
• Property Naming Strategy: Handle mismatched casing (e.g., snake_case JSON → camelCase PHP) via:

  $mapper->setPropertyNameStrategy(JsonMapper::PROPERTY_NAME_STRATEGY_CAMEL_CASE);
  

• Extensibility Hooks:
  • Use EVENT_BEFORE_MAP/EVENT_AFTER_MAP for validation or logging.
  • Extend JsonMapper to customize mapObject() for domain-specific types (e.g., enums, UUIDs).
  • Leverage JsonMapperFactory for DI-friendly setup (e.g., injecting custom handlers in Laravel).

Gotchas and Tips

• Property Visibility: Only public properties or protected properties with @var annotations are mapped. Private properties require a custom setter strategy.
• Missing Fields: Unmapped JSON keys are silently ignored; enforce presence via typed properties (e.g., public string $email; triggers error if missing) or defaults (e.g., public ?string $token = null;).
• Circular References: JsonMapper lacks cycle detection—avoid recursive structures or pre-flatten JSON to prevent memory exhaustion.
• Performance: Reuse JsonMapper instances (stateless), and avoid heavy annotation use; while reflection caching helps, tight loops need benchmarking.
• Type Safety Limits: No built-in validation— pair with symfony/validator or custom @Assert-style annotations if needed.
• PHP Version: Requires ≥7.4; no official support for PHP 8.0+ features beyond basic union types.