DEV Community: Francisco Barrento

From Laravel Factories to Framework-Agnostic: Building the Data Factory Package

Francisco Barrento — Tue, 11 Nov 2025 18:06:01 +0000

Part 2 of the Laravel Factory Patterns series

Part 1: Stop Writing Arrays in Your Tests

Part 2: Building the Data Factory Package (you are here)

Originally published on barrento.dev

After my last article on using Laravel factories with Data Objects, I kept thinking: why should only Laravel developers get this elegant API?

If you're building framework-agnostic PHP packages, you face a problem. You need realistic test data, but you can't depend on Laravel's factory system. So you end up writing repetitive array construction code in every test, violating DRY and making maintenance a nightmare.

I built Data Factory to solve this.

The Framework-Agnostic Challenge

When you're building a PHP SDK or package that works with any framework (or no framework), test data becomes painful:

// Every test looks like this
it('processes a deployment', function () {
    $deployment = [
        'id' => '123e4567-e89b-12d3-a456-426614174000',
        'status' => 'deployment.succeeded',
        'branch_name' => 'main',
        'commit_hash' => 'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0',
        'commit_message' => 'Deploy feature X to production',
        'failure_reason' => null,
        'php_major_version' => '8.4',
        'uses_octane' => true,
        'started_at' => '2024-01-15 10:00:00',
        'finished_at' => '2024-01-15 10:05:00',
    ];

    // Your actual test...
});

Multiply this by dozens of tests, and you've got a maintenance problem. When the API structure changes, you're updating arrays scattered across your entire test suite.

Laravel developers don't have this problem. They use factories:

$deployment = Deployment::factory()->succeeded()->make();

But that's tied to Eloquent. If you're building a package, you can't bring in the entire Laravel framework as a dev dependency just for test factories.

The Solution: Extract the Pattern

Data Factory brings Laravel's elegant factory API to any PHP project. No framework required. No Eloquent dependency.

Here's what that same test looks like with Data Factory:

it('processes a deployment', function () {
    $deployment = Deployment::factory()->succeeded()->make();

    // Your actual test logic - clean and focused!
});

One line. Clear intent. Type safe. And when the structure changes, you update one factory definition, not 50 tests.

Building Your First Factory

Installation is simple:

composer require fbarrento/data-factory --dev

Then create a factory for your Data Object:

use FBarrento\DataFactory\Factory;

class DeploymentFactory extends Factory
{
    protected string $dataObject = Deployment::class;

    protected function definition(): array
    {
        return [
            'id' => $this->fake->uuid(),
            'status' => 'pending',
            'branch_name' => 'main',
            'commit_hash' => $this->fake->sha1(),
            'commit_message' => $this->fake->sentence(),
            'php_major_version' => '8.4',
            'uses_octane' => false,
        ];
    }
}

The definition() method returns default attributes. Notice $this->fake - that's FakerPHP integrated out of the box for realistic test data.

The $dataObject property tells the factory which class to instantiate. The factory automatically uses argument unpacking to construct your object.

Wire it up to your Data Object:

use FBarrento\DataFactory\Concerns\HasDataFactory;

readonly class Deployment
{
    use HasDataFactory;

    public function __construct(
        public string $id,
        public string $status,
        public string $branch_name,
        public string $commit_hash,
        public string $commit_message,
        public string $php_major_version,
        public bool $uses_octane,
    ) {}

    public static function newFactory(): DeploymentFactory
    {
        return new DeploymentFactory();
    }
}

The HasDataFactory trait provides the factory() method, and newFactory() tells it which factory class to instantiate.

Now you can use it anywhere:

// Single object
$deployment = Deployment::factory()->make();

// Collection of objects
$deployments = Deployment::factory()->count(50)->make();

// Override specific attributes
$deployment = Deployment::factory()->make([
    'status' => 'failed',
    'branch_name' => 'feature/new-api',
]);

States: Named Variations

States let you define common variations without repeating yourself:

class DeploymentFactory extends Factory
{
    // ... definition() ...

    public function succeeded(): static
    {
        return $this->state([
            'status' => 'deployment.succeeded',
            'finished_at' => now(),
        ]);
    }

    public function failed(): static
    {
        return $this->state([
            'status' => 'deployment.failed',
            'failure_reason' => $this->fake->sentence(),
        ]);
    }

    public function withOctane(): static
    {
        return $this->state(['uses_octane' => true]);
    }
}

Then use them in your tests:

it('handles successful deployments', function () {
    $deployment = Deployment::factory()->succeeded()->make();
    expect($deployment->status)->toBe('deployment.succeeded');
});

it('handles failed Octane deployments', function () {
    $deployment = Deployment::factory()
        ->failed()
        ->withOctane()
        ->make();

    expect($deployment->status)->toBe('deployment.failed');
    expect($deployment->uses_octane)->toBeTrue();
});

Compare this to manually building arrays with different statuses in every test. States make your intent clear and your tests maintainable.

Sequences: Cycling Through Values

Sometimes you need different values for each item in a collection. Sequences handle this elegantly:

$deployments = Deployment::factory()
    ->count(3)
    ->sequence(
        ['branch_name' => 'main'],
        ['branch_name' => 'staging'],
        ['branch_name' => 'feature/new-api'],
    )
    ->make();

// First deployment has branch_name = 'main'
// Second has 'staging'
// Third has 'feature/new-api'

This is the exact same API Laravel uses for Eloquent factories. If you know Laravel, you already know Data Factory.

Nested Factories: Complex Object Graphs

Here's where it gets powerful. Real-world data isn't flat - it's nested. A deployment might have a user, a repository, commit details, and more.

Without factories, building nested test data is painful:

$deployment = [
    'id' => '...',
    'repository' => [
        'name' => '...',
        'owner' => [
            'name' => '...',
            'email' => '...',
        ],
    ],
    'commit' => [
        'hash' => '...',
        'author' => [
            'name' => '...',
            'email' => '...',
        ],
    ],
];

With Data Factory, you compose factories:

class DeploymentFactory extends Factory
{
    protected function definition(): array
    {
        return [
            'id' => $this->fake->uuid(),
            'repository' => Repository::factory(),
            'commit' => Commit::factory(),
        ];
    }
}

// In your test
$deployment = Deployment::factory()->make();
// Automatically creates nested Repository and Commit objects

You can override nested factories too:

$deployment = Deployment::factory()
    ->make([
        'repository' => Repository::factory()->private()->make(),
        'commit' => Commit::factory()->make(['hash' => 'abc123']),
    ]);

This composition pattern keeps your test setup clean while handling arbitrarily complex object graphs.

Array Factories: When You Don't Need Objects

Sometimes you need arrays, not objects. Maybe you're testing JSON serialization, API responses, or working with dynamic data where objects would be overkill.

Data Factory supports this through dedicated array factories:

use FBarrento\DataFactory\ArrayFactory;

class DeploymentArrayFactory extends ArrayFactory
{
    protected function definition(): array
    {
        return [
            'id' => $this->fake->uuid(),
            'status' => 'pending',
            'branch_name' => 'main',
            'commit_hash' => $this->fake->sha1(),
        ];
    }

    public function succeeded(): static
    {
        return $this->state(['status' => 'deployment.succeeded']);
    }
}

// Single array
$deploymentArray = DeploymentArrayFactory::new()->make();
// Returns: ['id' => '...', 'status' => '...', ...]

// Collection of arrays
$deploymentsArray = DeploymentArrayFactory::new()->count(5)->make();
// Returns: [['id' => '...'], ['id' => '...'], ...]

// With states
$succeeded = DeploymentArrayFactory::new()->succeeded()->make();

Perfect for testing API endpoints, JSON serialization, or when you're working with unstructured data that doesn't warrant a Data Object.

Why Framework-Agnostic Matters

When I built the Laravel Ortto SDK, I needed factories for testing. But I'm also building other SDKs and packages that aren't Laravel-specific.

Data Factory works with:

✅ Laravel projects (alongside Eloquent factories)
✅ Symfony projects
✅ Framework-agnostic PHP packages
✅ Plain PHP projects with PEST or PHPUnit

The API is familiar to Laravel developers, but you don't need Laravel. You get the elegant factory pattern everywhere.

Real-World Usage

In the Laravel Cloud SDK I'm building, I use Data Factory extensively:

class ServerFactory extends Factory
{
    protected function definition(): array
    {
        return [
            'id' => $this->fake->uuid(),
            'name' => $this->fake->word(),
            'region' => $this->fake->randomElement(['us-east-1', 'eu-west-1']),
            'size' => 'small',
            'status' => 'active',
            'ipAddress' => $this->fake->ipv4(),
        ];
    }

    public function provisioning(): static
    {
        return $this->state(['status' => 'provisioning']);
    }

    public function large(): static
    {
        return $this->state(['size' => 'large']);
    }
}

// In tests
it('lists active servers', function () {
    $servers = Server::factory()->count(10)->make();
    // Test logic...
});

it('handles server provisioning', function () {
    $server = Server::factory()->provisioning()->large()->make();
    expect($server->status)->toBe('provisioning');
    expect($server->size)->toBe('large');
});

Clean. Readable. Maintainable. And when the Cloud API changes their server structure, I update one factory, not dozens of tests.

What's Next

Data Factory is on Packagist and actively maintained. The package has:

✅ 100% test coverage
✅ 100% type coverage (PHPStan level 9)
✅ Comprehensive documentation
✅ PHP 8.2+ with modern patterns

I'm considering these features for future releases:

raw() method for returning attribute arrays without instantiating objects
afterMaking() callbacks for post-processing
Export to JSON fixtures
Streaming/chunking for massive datasets

In the next article, we'll dive into advanced patterns: managing relationships between factories, custom faker providers, and testing strategies with complex object graphs.

Check out Data Factory on GitHub and give it a try. If you're building PHP packages or SDKs, it'll change how you write tests.

Stop writing arrays. Start using factories. Everywhere.

What's Next?

In Part 3, I'll show you how to use this package to generate 1 million database seeders efficiently. We'll explore:

Memory optimization techniques
Chunking strategies for large datasets
Performance benchmarking
Real-world seeding scenarios

Follow me to catch it when it drops!

Let's Discuss

Have you built packages from patterns you kept repeating? What testing or seeding challenges have you faced?

Let me know in the comments!

If you found this helpful:

❤️ React to show support
🦄 Unicorn if you want Part 3
🔖 Bookmark for reference
💬 Share your experience below
⭐ Star the repo on GitHub

Check out the Laravel Ortto SDK to see the pattern that inspired this package.

Stop Writing Arrays in Your Tests: Laravel Factories for Data Objects

Francisco Barrento — Sun, 09 Nov 2025 15:37:25 +0000

How I used Laravel's factory pattern with Data Objects to DRY up test data in the Ortto SDK

This article was originally published on my blog. First in a series on Laravel Data Factories.

Building the Laravel Ortto SDK taught me something: test setup shouldn't be harder than the actual testing. When you are integrating with an API that expects complex, nested payloads, raw arrays turn your tests into unreadable nightmares fast.

Here's what I mean. The Ortto API's person merge endpoint expects payloads like this:

$payload = [
    'people' => [
        [
            'fields' => [
                'str::ei' => 'user_12345',
                'str::email' => 'francisco.barrento@gmail.com',
                'str::first' => 'Francisco',
                'str::last' => 'Barrento',
                'geo::city' => ['name' => 'Lisbon'],
                'geo::country' => ['name' => 'Portugal'],
                'str::postal' => '1000-001',
                'bol::p' => true,
                'bol::sp' => false,
            ]
        ],
        [
            'fields' => [
                'str::ei' => 'user_67890',
                'str::email' => 'another@example.com',
                'str::first' => 'Jane',
                'str::last' => 'Smith',
                'geo::city' => ['name' => 'Porto'],
                'geo::country' => ['name' => 'Portugal'],
                'str::postal' => '4000-001',
                'bol::p' => true,
                'bol::sp' => true,
            ]
        ],
        // ... imagine 52 more of these
    ]
];

Now multiply that by every test case that needs person data. Different scenarios, edge cases, validation tests. You're writing the same structure dozens of times, changing a field here and there. When the API structure changes (and it will), you're updating arrays scattered across 30 test files.

There's a better way.

The Pattern That Changed Everything

What if instead of building arrays manually, you could write:

$people = PersonData::factory()->count(54)->make();

$payload = [
    'people' => $people->toArray()
];

That's it. Fifty-four realistic person objects with random, valid data. One line. And when the structure changes, you update one factory definition, not 30 tests.

This is what Laravel's factory pattern does for Eloquent models, but we can hijack it for Data Objects.

Setting Up Factories for Data Objects

First, we need a Data Object. Mine implements Laravel's Arrayable interface because our HTTP client (Saloon) transforms arrays into JSON payloads for the API:

class PersonData implements Arrayable
{
    public function __construct(
        public string|int $id,
        public string $email,
        public ?string $firstName = null,
        public ?string $lastName = null,
        public ?string $name = null,
        public ?string $city = null,
        public ?string $country = null,
        public ?string $postalCode = null,
        public ?CarbonImmutable $birthdate = null,
        public bool $emailPermission = false,
        public bool $smsPermission = false,
    ) {}

    public static function factory(): PersonFactory
    {
        return PersonFactory::new();
    }

    public function toArray(): array
    {
        return [
            'fields' => [
                'str::ei' => (string) $this->id,
                'str::email' => $this->email,
                'str::first' => $this->firstName,
                'str::last' => $this->lastName,
                'str::name' => $this->name,
                'geo::city' => [
                    'name' => $this->city,
                ],
                'geo::country' => [
                    'name' => $this->country,
                ],
                'str::postal' => $this->postalCode,
                'dtz::b' => [
                    'year' => $this->birthdate?->year,
                    'month' => $this->birthdate?->month,
                    'day' => $this->birthdate?->day,
                    'timezone' => $this->birthdate?->getTimezone()->getName(),
                ],
                'bol::p' => $this->emailPermission,
                'bol::sp' => $this->smsPermission,
            ]
        ];
    }

    public function newCollection(array $items = []): Collection
    {
        return new Collection($items);
    }
}

Now for the factory. Laravel's Illuminate\Database\Eloquent\Factories\Factory class is built for Eloquent models, but it's generic enough to work with any class. We just need to extend it and tell it what to create:

final class PersonFactory extends Factory
{
    protected $model = PersonData::class;

    private array $extraAttributes = [];

    public function definition(): array
    {
        return [
            'id' => Str::uuid()->toString(),
            'email' => fake()->unique()->email(),
            'firstName' => fake()->firstName(),
            'lastName' => fake()->lastName(),
            'name' => fake()->name(),
            'city' => fake()->city(),
            'country' => fake()->country(),
            'postalCode' => fake()->postcode(),
            'birthdate' => CarbonImmutable::now(),
            'emailPermission' => fake()->boolean(),
            'smsPermission' => fake()->boolean(),
        ];
    }

    public function make($attributes = [], ?Model $parent = null): PersonData|Collection
    {
        $this->extraAttributes = $attributes;

        if ($this->count === null) {
            return $this->makeInstance($parent);
        }
        $instances = [];

        for ($i = 0; $i < $this->count; $i++) {
            $instances[] = $this->makeInstance($parent);
        }

        return collect($instances);
    }

    protected function makeInstance(?Model $parent = null): PersonData
    {
        $attributes = array_merge(
            $this->getRawAttributes($parent),
            $this->extraAttributes
        );

        return new PersonData(...$attributes);
    }

    public function newModel(array $attributes = []): PersonData
    {
        $attributes = array_merge($this->definition(), $attributes);

        return new PersonData(...$attributes);
    }
}

The definition() method returns the default attributes. Faker gives us realistic, random data every time.

But here's the crucial part: Laravel's factory expects Eloquent models, not Data Objects. We need to override make() to handle instantiation:

public function make($attributes = [], ?Model $parent = null): PersonData|Collection
{
    $this->extraAttributes = $attributes;

    if ($this->count === null) {
        return $this->makeInstance($parent);
    }
    $instances = [];

    for ($i = 0; $i < $this->count; $i++) {
        $instances[] = $this->makeInstance($parent);
    }
    return collect($instances);
}

Instead of returning Eloquent models, this returns either a single PersonData or a Collection of them. The makeInstance() method handles the actual object creation:

protected function makeInstance(?Model $parent = null): PersonData
{
    $attributes = array_merge(
        $this->getRawAttributes($parent),
        $this->extraAttributes
    );

    return new PersonData(...$attributes);
}

The newModel() method is simpler but still important:

public function newModel(array $attributes = []): PersonData
{
    $attributes = array_merge($this->definition(), $attributes);
    return new PersonData(...$attributes);
}

Laravel's factory calls this internally when it needs to create a fresh instance. It merges your custom attributes with the defaults from definition(), then uses argument unpacking to instantiate the Data Object. Without this, the factory wouldn't know how to construct your non-Eloquent object.

Now we wire up the factory to the Data Object:

class PersonData implements Arrayable
{
    // ... constructor and toArray() ...

    public static function factory(): PersonFactory
    {
        return PersonFactory::new();
    }

    public function newCollection(array $items = []): Collection
    {
        return collect($items);
    }
}

That's the setup. Now the magic happens in your tests.

Testing Gets Stupid Simple

Here's a real test from the Ortto SDK. I need to verify that merging multiple people works correctly:

it('can merge multiple people at once', function () {
    Ortto::fake();

    $people = PersonData::factory()->count(10)->make();

    $response = $this->ortto->send(
        new MergePopleRequest(
            people: $people->toArray(),
            mergeBy: ['str::email'],
            mergeStrategy: MergeStrategy::OverwriteExisting->value,
            finsStartegy: FindStrategy::All->value,
        )
    );

    expect($response->status())
        ->toBe(200)
        ->and($response->json())
        ->toHaveKey('people')
        ->and($response->json('people'))
        ->toBeArray()
        ->and($response->json('people'))
        ->toHaveCount(54);
});

Ten realistic people, with valid emails, names, cities, postal codes, and external IDs. All different. All random. One line.

Need edge cases? Override specific attributes:

$person = PersonData::factory()->make([
    'email' => 'invalid-email',
    'postalCode' => '',
]);

Need a specific scenario? Make a factory state:

public function withMissingCity(): static
{
    return $this->state(fn (array $attributes) => [
        'city' => null,
    ]);
}

// In your test
$person = PersonData::factory()->withMissingCity()->make();

Need sequences? Got it:

$people = PersonData::factory()
    ->count(3)
    ->sequence(
        ['city' => 'Lisbon'],
        ['city' => 'Porto'],
        ['city' => 'Faro'],
    )
    ->make();

The DRY Payoff

This pattern pays dividends immediately, but the real win shows up over time:

One source of truth. When the API changes (Ortto adds a required phone field, for example), you update the factory definition. Every test that uses PersonData::factory() instantly gets the new structure.

Readable tests. Compare these two:

// Before: What are we even testing here?
$payload = [
    'people' => [
        ['fields' => ['str::email' => 'test@example.com', 'str::first' => 'Test', ...]],
        ['fields' => ['str::email' => 'test2@example.com', 'str::first' => 'Test2', ...]],
    ]
];

// After: Ah, we're testing bulk merges
$people = PersonData::factory()->count(50)->make();

Reusable across tests. Every test that needs person data uses the same factory. Integration tests, unit tests, feature tests. They all share the same realistic data generation.

Type safety bonus. Because we're working with Data Objects instead of arrays, our IDE catches mistakes before the tests run. Try to set $person->emial and your IDE screams at you. Try to set $array['emial'] and you won't know until the test fails.

The toArray() Bridge

The toArray() method is where we translate between our nice, typed PHP objects and whatever format the API expects. For Ortto, that means their type-prefixed notation (str::, geo::, dtz::, bol::), nested structures for geographic data, and complex datetime handling:

public function toArray(): array
{
    return [
        'fields' => [
            'str::ei' => (string) $this->id,
            'str::email' => $this->email,
            'str::first' => $this->firstName,
            'str::last' => $this->lastName,
            'geo::city' => [
                'name' => $this->city,
            ],
            'geo::country' => [
                'name' => $this->country,
            ],
            'str::postal' => $this->postalCode,
            'dtz::b' => [
                'year' => $this->birthdate?->year,
                'month' => $this->birthdate?->month,
                'day' => $this->birthdate?->day,
                'timezone' => $this->birthdate?->getTimezone()->getName(),
            ],
            'bol::p' => $this->emailPermission,
            'bol::sp' => $this->smsPermission,
        ]
    ];
}

Look at that birthdate transformation. The API wants year, month, day, and timezone as separate fields. Without the Data Object, you'd be manually destructuring CarbonImmutable objects in every test. With it? One transformation, defined once, used everywhere.

Your API probably expects something different. Maybe flat arrays, maybe different nesting, maybe camelCase instead of snake_case. Doesn't matter. You control the transformation in one place, and every factory-generated object transforms consistently.

When working with collections, Laravel's map method makes the transformation trivial:

$people = PersonData::factory()->count(54)->make();
$arrayOfArrays = $people->toArray();

That's calling toArray() on each PersonData object in the collection, then converting the collection itself to a plain PHP array. One line handles the entire transformation.

What's Next

This pattern removes so much friction from testing that I kept finding ways to extend it. In the next article, we'll extract a DataFactory trait to clean up the repetitive factory setup even further. Then we'll tackle something trickier: managing relationships between Data Objects using factories.

The Laravel Ortto SDK uses this pattern throughout its test suite. Check out the complete implementations:

PersonData - The Data Object with Arrayable interface
PersonFactory - The factory with attribute mapping
MergePeopleTest - Real tests using the factory pattern

Stop writing arrays. Start using factories.

What do you think? Have you used factories with Data Objects before? Let me know in the comments!

Check out the Laravel Ortto SDK to see the full implementation.