Dummy Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require directorytree/dummy --dev
   

   • No Laravel dependency required (since v1.1.0), but orchestra/testbench is recommended for Laravel integration tests.

2. Basic Factory Creation:

   use DirectoryTree\Dummy\Dummy;
   use App\Models\User;
   
   $dummy = new Dummy();
   $user = $dummy->make(User::class, [
       'name' => 'Test User',
       'email' => 'test@example.com'
   ]);
   

   • Works with Eloquent models or plain PHP classes.

3. First Use Case: Replace manual test data creation in unit tests:

   public function test_user_creation()
   {
       $dummy = new Dummy();
       $user = $dummy->make(User::class);
   
       $this->assertDatabaseHas('users', [
           'email' => $user->email
       ]);
   }
   

4. Key Starting Points:

   • Package Source (check tests/ for usage examples)
   • Dummy::make() for single instances
   • Dummy::sequence() for batches

Implementation Patterns

Core Workflows

1. Eloquent Model Factories

// Basic factory
$user = Dummy::make(User::class);

// With attributes
$admin = Dummy::make(User::class, [
    'role' => 'admin',
    'is_active' => true
]);

// With relationships
$post = Dummy::make(Post::class, [
    'user_id' => $user->id
]);

2. Dynamic State Management (v1.3.0+)

// Define states in your model
class User extends Model
{
    use \DirectoryTree\Dummy\HasFactory;

    protected $factoryStates = [
        'admin' => ['role' => 'admin'],
        'inactive' => ['is_active' => false]
    ];
}

// Usage
$admin = Dummy::make(User::class)->state('admin');
$inactiveAdmin = Dummy::make(User::class)
    ->state(['admin', 'inactive']);

3. Batch Generation

// Create 10 users
$users = Dummy::sequence(User::class, 10);

// With custom attributes
$posts = Dummy::sequence(Post::class, 5, [
    'title' => fn($i) => "Post $i",
    'content' => 'Lorem ipsum...'
]);

4. Laravel Integration (with Testbench)

// In a Laravel test
public function test_with_laravel()
{
    $this->artisan('migrate'); // Setup DB

    $user = Dummy::make(User::class);
    $user->save();

    $this->assertDatabaseHas('users', [
        'email' => $user->email
    ]);
}

5. Non-Laravel Usage

// Plain PHP class
class Product {
    public $name;
    public $price;
}

$products = Dummy::sequence(Product::class, 3, [
    'name' => ['Laptop', 'Phone', 'Tablet'],
    'price' => [999, 699, 399]
]);

Integration Tips

1. PestPHP Integration:

   use DirectoryTree\Dummy\Dummy;
   
   it('creates a user', function () {
       $user = Dummy::make(User::class);
       expect($user)->toBeInstanceOf(User::class);
   });
   

2. Factory State Testing:

   public function test_factory_states()
   {
       $admin = Dummy::make(User::class)->state('admin');
       $this->assertEquals('admin', $admin->role);
   }
   

3. Database Seeding:

   // In DatabaseSeeder.php
   public function run()
   {
       Dummy::sequence(User::class, 100)->each->save();
   }
   

4. Custom Attribute Expansion:

   // Expand 'password' to hashed value
   $user = Dummy::make(User::class, [
       'password' => 'secret'
   ])->expand(['password' => fn($val) => bcrypt($val)]);
   

Gotchas and Tips

Common Pitfalls

1. Non-Stringable Objects in filled():

   • Issue: filled(...) throws exceptions for non-stringable objects (fixed in v2.0.1).
   • Fix: Ensure all attributes are stringable or use type casting:

     $data = Dummy::make(User::class, [
         'metadata' => new \stdClass() // Will fail in <v2.0.1
     ]);
     

2. Late Static Binding in HasFactory:

   • Issue: v1.3.1 fixed late static binding problems when using HasFactory.
   • Fix: Update to ^1.3.1 if experiencing closure binding issues.

3. Laravel-Specific Helpers:

   • Issue: Arr helpers (introduced in v1.3.1) won't work in non-Laravel projects.
   • Fix: Use PHP's native array_* functions or install illuminate/support:

     composer require illuminate/support
     

4. Dynamic State Conflicts:

   • Issue: Custom states may override default factory attributes.
   • Fix: Use explicit state arrays:

     $user = Dummy::make(User::class)
         ->state(['role' => 'editor', 'is_active' => true]);
     

Debugging Tips

1. Inspect Generated Data:

   $data = Dummy::make(User::class)->toArray();
   dd($data); // Debug output
   

2. Check Factory States:

   $user = Dummy::make(User::class)->state('admin');
   dd($user->getFactoryStates()); // List available states
   

3. Sequence Debugging:

   $users = Dummy::sequence(User::class, 3, [
       'name' => ['Alice', 'Bob', 'Charlie']
   ]);
   dd($users->all()); // Inspect batch
   

Configuration Quirks

1. Default Attribute Handling:

   • The package uses Arr::get() for attribute access (v1.3.1+). For older Laravel versions, override:

     $dummy = new Dummy();
     $dummy->setAttributeAccessor(function ($data, $key) {
         return data_get($data, $key);
     });
     

2. Generic Types:

   • Since v1.5.0, generic types are supported but may require explicit type hints:

     $dummy = new Dummy();
     $data = $dummy->make(\stdClass::class, ['prop' => 'value']);
     

3. Factory Method Parity:

   • Laravel factory methods (e.g., has(), for()) are partially supported. For full parity, extend the Dummy class:

     class CustomDummy extends Dummy {
         public function has($relation, $callback)
         {
             // Custom implementation
         }
     }
     

Extension Points

1. Custom Attribute Providers:

   $dummy = new Dummy();
   $dummy->addProvider('users', function () {
       return [
           'name' => 'Test User',
           'email' => 'test@example.com'
       ];
   });
   
   $user = $dummy->make(User::class, ['provider' => 'users']);
   

2. Post-Processing Hooks:

   $dummy = new Dummy();
   $dummy->afterMake(function ($model) {
       if ($model instanceof User) {
           $model->password = bcrypt($model->password);
       }
   });
   
   $user = $dummy->make(User::class, ['password' => 'secret']);
   

3. Custom State Resolvers:

   $dummy = new Dummy();
   $dummy->resolveState('admin', function ($model) {
       $model->role = 'admin';
       $model->permissions = ['create', 'read'];
   });
   
   $admin = $dummy->make(User::class)->state('admin');
   

Performance Considerations

1. Batch Generation:

   • For large batches (>1000 items), use chunking:

     Dummy::sequence(User::class, 10000)->chunk(100)->each(function ($chunk) {
         User::insert($chunk->toArray());
     });
     

2. Memory Optimization:

   • Clear sequences after use:

     $users = Dummy::sequence(User::class, 100);
     // Use $users...
     unset($users);
     

3. Avoid Over-Fetching:

   • Only request needed attributes:

     $user = Dummy::make(User::class, [], ['email', 'name']);