Class Builder Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require andrew-gos/class-builder
   

2. Basic Usage:

   use AndrewGos\ClassBuilder\ClassBuilder;
   
   $builder = new ClassBuilder();
   $object = $builder->build(YourClass::class, ['param1' => 'value1']);
   

First Use Case: Instantiating Simple Classes

class User {
    public function __construct(
        private string $name,
        private int $age
    ) {}
}

$user = $builder->build(User::class, [
    'name' => 'John Doe',
    'age' => 30
]);

Where to Look First

• README.md: For core features and examples.
• Attribute/: For customization options like @Field, @ArrayType, etc.
• Checker/: For conditional object building logic.

Implementation Patterns

Common Workflows

1. Building Objects from Arrays

// Standard constructor mapping
$order = $builder->build(Order::class, [
    'customer_id' => 1,
    'items' => [['product_id' => 101, 'quantity' => 2]]
]);

2. Handling Abstract Classes/Interfaces

#[AvailableInheritors([AdminUser::class, GuestUser::class])]
interface User {}

$builder->build(User::class, ['role' => 'admin']); // Returns AdminUser

3. Typed Arrays

class Cart {
    public function __construct(
        #[ArrayType('Product')] private array $products
    ) {}
}

$cart = $builder->build(Cart::class, [
    'products' => [
        ['id' => 1, 'name' => 'Laptop'],
        ['id' => 2, 'name' => 'Phone']
    ]
]);

4. Scalar-to-Object Conversion

#[CanBeBuiltFromScalar]
class Id {
    public function __construct(private int $value) {}
}

$id = $builder->build(Id::class, 42); // Direct scalar input

5. Custom Field Mapping

class Profile {
    public function __construct(
        #[Field('full_name')] private string $name
    ) {}
}

$profile = $builder->build(Profile::class, [
    'full_name' => 'Alice Smith'
]);

Integration Tips

• Dependency Injection: Register ClassBuilder as a singleton in Laravel's service container:

  $app->singleton(ClassBuilder::class, fn() => new ClassBuilder());
  

• Form Requests: Use in FormRequest classes to validate and build objects:

  public function build(array $data) {
      return resolve(ClassBuilder::class)->build(YourModel::class, $data);
  }
  

• API Responses: Transform array data into objects for consistent responses:

  return response()->json($builder->build(UserResource::class, $userData));
  

Gotchas and Tips

Pitfalls

1. Type Mismatches:

   • If input data doesn’t match constructor types, the builder throws InvalidArgumentException.
   • Fix: Use BuildIf with custom CheckerInterface implementations to validate data before building.

2. Circular Dependencies:

   • Building nested objects with circular references (e.g., User has Address, Address has User) will fail.
   • Fix: Use lazy loading or break cycles with null placeholders.

3. Attribute Overrides:

   • Attributes like @Field or @ArrayType must be applied to constructor parameters, not properties.
   • Fix: Reapply attributes if migrating from property injection to constructor injection.

4. Performance with Large Arrays:

   • Building arrays of complex objects (e.g., #[ArrayType(User::class)]) can be slow for large datasets.
   • Fix: Use batch processing or optimize with ArrayType constraints.

Debugging Tips

• Enable Verbose Mode:

  $builder = new ClassBuilder(verbose: true); // Logs building steps
  

• Check Constructor Parameters: Use ReflectionClass to verify parameter names/types if builds fail silently:

  $reflection = new ReflectionClass(YourClass::class);
  print_r($reflection->getConstructor()->getParameters());
  

• Test with Simple Cases: Start with scalar parameters before testing complex types (arrays, unions, etc.).

Extension Points

1. Custom Checkers: Implement CheckerInterface for dynamic validation:

   class MinAgeChecker implements CheckerInterface {
       public function check(array $data): bool {
           return $data['age'] >= 18;
       }
   }
   

   Apply with @BuildIf(new MinAgeChecker()).

2. Post-Build Hooks: Extend ClassBuilder to add callbacks after object creation:

   $builder->afterBuild(fn($object) => $this->logObject($object));
   

3. Custom Type Builders: Override ClassBuilder::buildType() to handle unsupported types (e.g., custom collections).

Laravel-Specific Quirks

• Service Container Conflicts: If ClassBuilder is registered as a singleton, ensure it’s not overridden by multiple bindings.
• Configuration: Store default builder settings in config/class-builder.php:

  'default_checkers' => [
      'min_age' => \App\Checkers\MinAgeChecker::class,
  ],
  

  Load via:

  $builder = new ClassBuilder(config('class-builder'));
  

• Artisan Commands: Useful for bulk object generation:

  $builder->buildBatch(User::class, $usersData);