Type Converter Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require apie/type-converter
   

   Add to composer.json if using Laravel’s autoloader:

   "autoload": {
       "psr-4": {
           "App\\": "app/",
           "Apie\\TypeConverter\\": "vendor/apie/type-converter/src/"
       }
   }
   

   Run composer dump-autoload.

2. First Use Case: Convert a simple array to a Laravel Carbon instance:

   use Apie\TypeConverter\DefaultConvertersFactory;
   use Carbon\Carbon;
   
   $converter = DefaultConvertersFactory::create();
   $result = $converter->convert(['year' => 2023, 'month' => 1], Carbon::class);
   // Returns: Carbon instance for January 2023
   

3. Key Classes:

   • DefaultConvertersFactory: Bootstraps default converters.
   • ConverterInterface: Core interface for type conversion.
   • Converter: Default implementation (extend for custom logic).

Implementation Patterns

Core Workflow

1. Instantiate Converter:

   $converter = DefaultConvertersFactory::create();
   

   Or customize with a Converter instance:

   $converter = new Converter();
   $converter->addConverter(new CustomConverter());
   

2. Basic Conversion:

   // Convert array to Eloquent model
   $user = $converter->convert([
       'name' => 'John Doe',
       'email' => 'john@example.com'
   ], User::class);
   

3. Nested Conversions:

   // Convert array with nested objects
   $data = [
       'user' => ['name' => 'Alice'],
       'posts' => [['title' => 'Hello']]
   ];
   $result = $converter->convert($data, [
       'user' => User::class,
       'posts' => [Post::class] // Array of Post models
   ]);
   

4. Laravel Integration:

   • Form Requests:

     public function rules() {
         return [
             'user' => ['required', Rule::exists('users')->converter($this->converter)]
         ];
     }
     

   • API Resources:

     public function toArray($request) {
         return $this->converter->convert($this->resource, UserResource::class);
     }
     

5. Service Container Binding (Laravel):

   $this->app->singleton(ConverterInterface::class, function ($app) {
       $converter = DefaultConvertersFactory::create();
       $converter->addConverter(new CustomDateConverter());
       return $converter;
   });
   

Gotchas and Tips

Pitfalls

1. Circular References:

   • Converting nested objects with circular references (e.g., User ↔ Post) will throw RecursionException.
   • Fix: Use Converter::setMaxDepth() or implement CircularReferenceHandlerInterface.

2. Type Mismatches:

   • Converting incompatible types (e.g., string → Carbon) silently fails unless a converter is registered.
   • Debug: Enable Converter::setStrictMode(true) to throw exceptions on failures.

3. Default Converters:

   • The package ships with basic converters (e.g., array → Carbon, array → DateTime), but no Eloquent model support by default.
   • Workaround: Register custom converters for models:

     $converter->addConverter(new ModelConverter(User::class));
     

4. Performance:

   • Avoid converting large arrays recursively without depth limits.
   • Tip: Cache converter instances in Laravel’s service container.

Debugging Tips

• Log Conversions:

  $converter->setLogger(new Monolog\Logger('converter'));
  

• Inspect Converters:

  $converter->getConverters(); // List all registered converters
  

Extension Points

1. Custom Converters:

   class CustomConverter implements ConverterInterface {
       public function canConvert($source, $target): bool {
           return is_array($source) && $target === CustomModel::class;
       }
       public function convert($source, $target) {
           return new CustomModel($source['data']);
       }
   }
   $converter->addConverter(new CustomConverter());
   

2. Override Default Behavior:

   • Extend Converter and override convert() or getConverter() methods.

3. Laravel Service Provider:

   public function register() {
       $this->app->extend(ConverterInterface::class, function () {
           $converter = DefaultConvertersFactory::create();
           $converter->addConverter(new EloquentConverter());
           return $converter;
       });
   }
   

Laravel-Specific Quirks

• Model Binding:
  • Use Illuminate\Routing\Router::bind() with a custom resolver:

    $router->bind('user', function ($value, $route) {
        return app(ConverterInterface::class)->convert($value, User::class);
    });
    

• Validation:
  • Combine with Laravel’s Rule::exists() for type-safe database lookups:

    Rule::exists('users')->converter($this->converter)