Simple Normalizer Laravel Package

Getting Started

Install via Composer:

composer require 21torr/simple-normalizer

Register the service provider in config/app.php:

'providers' => [
    // ...
    SimpleNormalizer\SimpleNormalizerServiceProvider::class,
],

First Use Case: Normalize a complex object to JSON with context:

use SimpleNormalizer\Normalizer;

// Basic usage
$normalizer = app(Normalizer::class);
$json = $normalizer->normalize($object, Normalizer::FORMAT_JSON);

// With new ContextBag helper (1.6.0)
$context = new \SimpleNormalizer\ContextBag();
$context->set('group', 'user');
$json = $normalizer->normalize($object, Normalizer::FORMAT_JSON, $context);

Key starting points:

• Documentation
• Normalizer facade for quick access
• ContextBag class for reusable context management

Implementation Patterns

Core Workflows

1. Standard Normalization:

$normalizer->normalize($entity, Normalizer::FORMAT_JSON);

2. Context-Driven Normalization (new in 1.6.0):

$context = new ContextBag(['group' => 'admin', 'depth' => 5]);
$result = $normalizer->normalize($object, Normalizer::FORMAT_JSON, $context);

3. Custom Normalizers:

$normalizer->addNormalizer(new class implements NormalizerInterface {
    public function normalize($object, $format, array $context = []) {
        // Custom logic
    }
});

Integration Tips

• Doctrine Entities: Use SimpleNormalizer with Doctrine metadata caching (now optimized in 1.6.0):

$normalizer->normalize($entity, Normalizer::FORMAT_JSON, [
    'groups' => ['api'],
    'use_metadata' => true
]);

• Validation: Chain with ValidJsonVerifier (optimized in 1.6.0):

$verifier = new \SimpleNormalizer\ValidJsonVerifier();
$verifier->verify($json, $expectedSchema);

• Performance: Leverage new caching (1.6.0) for repeated normalizations of same object types.

Gotchas and Tips

Performance Optimizations (1.6.0)

• Class Name Caching: Doctrine metadata lookups are now cached in SimpleNormalizer (reduces overhead for repeated calls).
• Path Stack Reuse: ValidJsonVerifier reuses path stack internally (no more allocation per element).
• Empty Object Check: Uses (array) cast instead of get_object_vars() for stdClass detection (faster).

Debugging Aids (1.6.0)

• Stack Traces: All relevant exceptions now include stack traces:

  try {
      $normalizer->normalize($object);
  } catch (\SimpleNormalizer\NormalizationFailedException $e) {
      $e->getTraceAsString(); // Full stack trace
  }
  

• Max Depth Guard: Added default max-depth of 128 to prevent DoS via deep nesting. Override via context:

  $context->set('max_depth', 256);
  

Common Pitfalls

1. Context Mutability: Avoid modifying context arrays directly during recursive normalization (use ContextBag for shared state).
2. Circular References: Explicitly handle circular references in custom normalizers:

   $context['handled'] = [];
   

3. Doctrine Metadata: Ensure Doctrine metadata is available when using use_metadata option (caching helps here).

Extension Points

• Custom Context: Extend ContextBag for project-specific context handling:

  class ProjectContextBag extends ContextBag {
      public function setProjectId(int $id) { /* ... */ }
  }
  

• Normalizer Decorators: Wrap existing normalizers for pre/post-processing:

  $normalizer->addNormalizer(new class implements NormalizerInterface {
      public function __construct(private NormalizerInterface $decorated) {}
      public function normalize($object, $format, array $context) {
          $result = $this->decorated->normalize($object, $format, $context);
          return $this->postProcess($result);
      }
  });
  

• Exception Handling: Catch NormalizationFailedException for granular error handling (now with stack traces).

catch (NormalizationFailedException $e) {
    $path = $e->getPath(); // e.g., ['user', 'address', 'city']
    $value = $e->getValue();
}