Symfony Yaml Serializer Encoder Decoder Laravel Package

Getting Started

Minimal Setup

1. Install the package in a Laravel project with PHP 5.6+:

   composer require fitbug/symfony-yaml-serializer-encoder-decoder
   

2. Register Symfony Serializer (if not already present) via a Laravel service provider:

   // app/Providers/AppServiceProvider.php
   use Symfony\Component\Serializer\Serializer;
   use Fitbug\SymfonyYamlSerializerEncoderDecoder\YamlEncoder;
   use Symfony\Component\Yaml\Yaml;
   
   public function register()
   {
       $this->app->singleton('yaml.serializer', function () {
           $encoders = [new YamlEncoder(new Yaml(), new Yaml())];
           $normalizers = \Symfony\Component\Serializer\Normalizer\NormalizerFactory::create();
           return new Serializer($normalizers, $encoders);
       });
   }
   

3. First use case: Serialize/deserialize YAML in a controller or command:

   use Illuminate\Support\Facades\Facade;
   
   class ExampleController extends Controller
   {
       public function serializeYaml()
       {
           $serializer = app('yaml.serializer');
           $data = ['name' => 'John', 'roles' => ['admin']];
   
           // Encode to YAML
           $yaml = $serializer->encode($data, 'yaml');
           dd($yaml);
   
           // Decode from YAML
           $decoded = $serializer->decode($yaml, 'yaml');
           dd($decoded);
       }
   }
   

Where to Look First

• Package source: YamlEncoder (core class).
• Symfony Serializer docs: Encoding/Decoding for format-specific usage.
• Laravel integration: Focus on the Serializer service binding and facade patterns.

Implementation Patterns

Core Workflows

1. Basic Serialization

// Encode PHP object/array to YAML
$yaml = app('yaml.serializer')->encode($arrayOrObject, 'yaml');

// Decode YAML to PHP object
$object = app('yaml.serializer')->decode($yaml, 'yaml', \stdClass::class);

2. Integration with Laravel Models

Use normalizers to convert Eloquent models to/from YAML:

use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;

$normalizers = [
    new ObjectNormalizer(),
    // Add custom normalizers for model-specific logic
];

$serializer = new Serializer($normalizers, [new YamlEncoder(new Yaml(), new Yaml())]);

// Serialize a User model
$user = User::first();
$yaml = $serializer->encode($user, 'yaml');

3. Configuration Management

Load YAML configs dynamically (e.g., feature flags, API specs):

// Load YAML from file
$yamlContent = file_get_contents(storage_path('config/api_spec.yaml'));
$spec = app('yaml.serializer')->decode($yamlContent, 'yaml', \stdClass::class);

// Update config and re-serialize
$spec->version = '2.0';
file_put_contents(storage_path('config/api_spec.yaml'), app('yaml.serializer')->encode($spec, 'yaml'));

4. API Payloads

Normalize API responses to YAML for logging/auditing:

use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;

$normalizers = [
    new ObjectNormalizer(),
    new DateTimeNormalizer(),
];

$serializer = new Serializer($normalizers, [new YamlEncoder(new Yaml(), new Yaml())]);

// Log API response as YAML
$responseYaml = $serializer->encode($apiResponse, 'yaml');
Log::info('API Response', ['yaml' => $responseYaml]);

Laravel-Specific Patterns

Facade Wrapper

Create a reusable facade for cleaner syntax:

// app/Facades/YamlSerializer.php
namespace App\Facades;

use Illuminate\Support\Facades\Facade;

class YamlSerializer extends Facade
{
    protected static function getFacadeAccessor() { return 'yaml.serializer'; }
}

Usage:

use App\Facades\YamlSerializer;

$yaml = YamlSerializer::encode($data, 'yaml');

Artisan Commands

Process YAML files via CLI:

// app/Console/Commands/ProcessYamlConfig.php
use App\Facades\YamlSerializer;

class ProcessYamlConfig extends Command
{
    public function handle()
    {
        $yaml = file_get_contents($this->argument('file'));
        $data = YamlSerializer::decode($yaml, 'yaml');
        // Process $data...
    }
}

Middleware for YAML Payloads

Validate/transform YAML payloads in incoming requests:

// app/Http/Middleware/ValidateYamlPayload.php
public function handle($request, Closure $next)
{
    if ($request->isYamlPayload()) {
        $data = YamlSerializer::decode($request->getContent(), 'yaml');
        $request->merge($data);
    }
    return $next($request);
}

Integration Tips

1. Combine with Symfony Normalizers:

   • Use ObjectNormalizer for Eloquent models.
   • Add DateTimeNormalizer for datetime fields.
   • Example:

     $normalizers = [
         new ObjectNormalizer(null, null, null, new \DateTimeZone('UTC')),
         new DateTimeNormalizer(),
     ];
     

2. Handle Circular References: Symfony’s ObjectNormalizer supports circular references via enableMaxDepth:

   new ObjectNormalizer(null, null, null, null, null, null, ['enableMaxDepth' => true])
   

3. Custom Normalizers: Extend functionality for Laravel-specific types (e.g., Carbon, Collection):

   use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
   
   class CarbonNormalizer implements NormalizerInterface
   {
       public function normalize($object, $format = null, array $context = [])
       {
           return $object->toDateTimeString();
       }
       // ... other methods
   }
   

4. Error Handling: Wrap serialization in try-catch blocks:

   try {
       $yaml = YamlSerializer::encode($data, 'yaml');
   } catch (\Symfony\Component\Serializer\Exception\ExceptionInterface $e) {
       Log::error('YAML serialization failed', ['error' => $e->getMessage()]);
       throw new \RuntimeException('Invalid YAML data', 0, $e);
   }
   

5. Performance: Reuse the Serializer instance (Laravel’s service container caches it) instead of creating new instances per request.

Gotchas and Tips

Pitfalls

1. PHP Version Mismatch:

   • The package targets PHP 5.6, but modern Laravel (8+) uses PHP 8.0+. Workaround:
     • Fork the package and update type hints (e.g., add return_type declarations).
     • Use symfony/yaml directly with Symfony Serializer v6+.

2. YAML Parsing Quirks:

   • Trailing commas: Symfony’s YAML parser may fail on trailing commas in arrays (e.g., items: [1, 2,]). Fix: Pre-process YAML or use symfony/yaml directly.
   • Anchors/aliases: Complex YAML features (e.g., &anchor) may not work as expected. Tip: Validate YAML with symfony/yaml first.

3. Namespace Collisions:

   • Symfony’s Serializer and Laravel’s Serializer (if any) may conflict. Solution:
     • Use fully qualified namespaces (e.g., \Symfony\Component\Serializer\Serializer).
     • Avoid naming service providers SerializerServiceProvider.

4. Stale Dependencies:

   • The package depends on old Symfony components (e.g., symfony/yaml:3.x). Risk: Security updates or BC breaks. Mitigation:
     • Pin versions strictly in composer.json.
     • Monitor for Symfony YAML deprecations.

5. Laravel Cache Conflicts:

   • If using symfony/yaml for caching (e.g., Cache::put()), ensure the YAML encoder/decoder aligns with Laravel’s cache drivers.

6. Normalizer Conflicts:

   • Mixing Laravel’s Arrayable/Jsonable with Symfony’s normalizers may cause unexpected behavior. Tip: Use ObjectNormalizer with ignoredAttributes to exclude Laravel-specific methods.

Debugging Tips

1. Validate YAML Input: Use symfony/yaml to pre-validate YAML before serialization:

   use Symfony\Component\Yaml\Yaml as SymfonyYaml;
   
   $yaml = file_get_contents('config.yaml');
   SymfonyYaml::parse($yaml); // Throws exception on invalid YAML