My learnings after using this plugin for 2 years

[LordSimal]

I just checked my git log and I added this plugin to my main app on 20th of November 2021. Now it's the end of 2023, and I just did a major overhaul of all my factories and how they are used in my testcases.

And I can definitely say that this plugin has changed my test structure to something I really enjoy adjusting and extending.

So what did I learn?

Make sure to add all available associations via withXYZ() methods

e.g. 1 StaffMember has many Projects would mean you have to add the following method to your StaffMemberFactory

public function withProjects($parameter = null, int $n = 1): self
{
    return $this->with('Projects', ProjectFactory::make($parameter, $n));
}

but also name your withXYZ() methods singular or plural depending on the association

e.g. 1 Ticket belongsTo 1 Project would mean you have to add the following method to your TicketFactory

public function withProject($parameter = null, int $n = 1): self
{
    return $this->with('Projects', ProjectFactory::make($parameter, $n));
}

notice the difference of withProjects and withProject. There is no difference in how the method works, but the naming already tells the user (aka YOU) if this is just a single associated entity or if it can be multiple.

This allowed me to easily write Model/Table tests for all my table classes because I was easily able to create entities with their associated entities in all kinds of variations.

Also you don't know when sometimes in the future you need that specific association on that entity so your future self (and or colleagues) don't have to setup that association in the factory 😉

DON'T chain ->withXYZ() methods inside your factory

At the beginning I thought I was clever and did a lot of variations of these

public function withDomains($parameter = null, int $n = 1): self
{
    return $this->with('FtpDomains', FtpDomainFactory::make($parameter, $n)->withFtpLoginData());
}

where you can see I not only added the association but also an additional association INSIDE the inner factory.

This surely resulted in "shorter" method calls in TestCases like so

RepositoryBranchFactory:make()->withDomains();

but resulted in uncontrollable data being present inside the FtpLoginData entity

Sure you could add a paremeter to the ->withDomains() method but it all just gets out of hand very quickly if you have to re-define each sub-association.

DON'T add ->withXYZ() methods to your setDefaultTemplate() method

Basically the same as the previous one but this time for the default entity data which is defined in the

protected function setDefaultTemplate(): void
{
    $this->setDefaultData(function (Generator $faker) {
        return [

        ];
    })->withFtpLoginData();
}

The withFtpLoginData() just caused more trouble than it was actually worth it. Yes you could get rid of that association with a ->without('FtpLoginData') call but still, why add it by default in the first place to just remove it later when you don't need it? It should only be added to the places where it's actually needed.

DON'T nest/chain ->with() calls inside your testcases

Inside my tests I had factory calls like this:

$entity = ProjectFactory::make([
    'project_end' => null,
    'is_duedate_notification_sent' => 0,
    'duedate' => Carbon::now()->subDays(5),
])
    ->with(
        'StaffMembersProjects',
        StaffMembersProjectFactory::make()
            ->without('Projects')
            ->with('ProjectRoles', ['id' => 1])
    )
    ->persist();

which is already pretty messy imho.

What is the better alternative?

Sure, you may now say I have a vendeta on the whole ->with() system but NO!

The following examples showcase how I like to deal with factory calls with multiple (sometimes deeper) associations, which sometimes have custom data as well.

1 association with custom data

$staffMembersProject = StaffMembersProjectFactory::make()
    ->withStaffMember()
    ->withProjectRole(['id' => 1])
    ->getEntity();
$entity = ProjectFactory::make([
    'project_end' => null,
    'is_duedate_notification_sent' => 0,
    'duedate' => Carbon::now()->subDays(5),
])
  ->withStaffMembersProjects($staffMembersProject)
  ->persist();

2 associations with 1 shared entity

$customer = EasybillCustomerFactory::make()->persist();
$charge = EasybillChargeFactory::make()->withEasybillCustomer($customer)->persist();
$entry = ProjectFactory::make()
    ->withEasybillCustomer($customer)
    ->withEasybillCharges($charge)
    ->persist();

2 associations with multiple generated entities

$staffMembersProjects = StaffMembersProjectFactory::make(3)
    ->withStaffMember()
    ->withProjectRole()
    ->getEntities();
$entry = ProjectFactory::make()
    ->withEasybillCustomer()
    ->withStaffMembersProjects($staffMembersProjects)
    ->persist();

3 levels of associations with 1 shared entity

$customer = EasybillCustomerFactory::make()->persist();
$easybillDocument = EasybillDocumentFactory::make()
    ->withEasybillCustomer($customer)
    ->withEasybillDocumentType()
    ->persist();
$projectEasyBillDocument = ProjectsEasybillDocumentFactory::make()
    ->withProjectDocumentType()
    ->withEasybillDocument($easybillDocument)
    ->getEntity();
$entry = ProjectFactory::make()
    ->withEasybillCustomer($customer)
    ->withProjectsEasybillDocuments($projectEasyBillDocument)
    ->persist();

Not only do you get rid of the "generic" ->with() call, but also you are certain, that your sub-entity is created exactly how you like it without having to try to wrap your head around all the nested/chained ->with() calls.

Avoid ->without() if possible

Following the rules above I was already able to remove all the ->without() calls I had in my tests since every sub-entity needed to be created previously by its own factory and then passed down to its parent entity via the ->withXYZ() method.

Resume

With these changes you will always have full control over all your entities' data in a very organised and telling way. Surely there are other ways to achieve the same thing in a different syntax but at least for me these rules have resulted in a fixture setup which is imho more readable and extendable.