Foundry

Foundry allows you to reference objects in Gherkin steps using names (from the registry) or special placeholders.

In Table Cells (Automatic Resolution)

If a property type is a registered factory, you can simply use the object's name. If automatic resolution fails, use the escape hatch:

• <foundry:object(type, name)>
• <foundry:lastObject(type)>: References the row with the highest ID in the database.

In Plain Step Arguments (Placeholders)

Placeholders using the foundry: prefix work in plain text arguments (e.g., in URLs or specific step strings):

• <foundry:id(type, name)>: The ID of a named object in the registry.
• <foundry:lastId(type)>: The ID of the row with the highest ID in the database.

Warning: <foundry:lastId(...)> assumes IDs follow creation order (auto-increment, sequences, or time-ordered UIDs like UUID v7/ULID). For random IDs (UUID v4), use named objects with <foundry:id(factory, name)> instead.

# Using object names in tables
Given there is a category named "tech"
Given there is a post named "my-post" with:
  | title   | category |
  | My Post | tech     |

# Using escape hatch in tables
Given there is a post named "my-post" with:
  | title   | category                         |
  | My Post | <foundry:object(category, tech)> |

# Using lastObject in tables
Then post named "my-post" should have properties:
  | category                       |
  | <foundry:lastObject(category)> |

# Using placeholders in plain arguments (URLs)
When I am on "/contacts/<foundry:lastId(contact)>"
When I am on "/contacts/<foundry:id(contact, john)>"

Foundry (v2.5+) supports experimental "in-memory" behavior. This allows you to use in-memory implementations of your domain repositories instead of Doctrine-backed ones during tests.

Implementation Steps:

1. Create an In-Memory Repository: Implement Zenstruck\Foundry\InMemory\InMemoryRepository and use the InMemoryRepositoryTrait. The repository must implement a _class() method returning the entity class it manages.
2. Configure the Container: Ensure your in-memory repository is used in the container (e.g., via a test-in-memory environment or an InMemoryKernel).
3. Use the #[AsInMemoryTest] Attribute: Apply this attribute to your KernelTestCase. This disables factory persistence and allows you to register an "after instantiate" hook to store objects in your in-memory repositories.

When using this mode, YourFactory::repository() returns the in-memory repository, and no database queries are made.

use App\Domain\Address\DomainAddressRepositoryInterface;
use Zenstruck\Foundry\InMemory\InMemoryRepository;
use Zenstruck\Foundry\InMemory\InMemoryRepositoryTrait;

/**
 * @implements InMemoryRepository<Address>
 */
final class InMemoryAddressRepository implements InMemoryRepository, DomainAddressRepositoryInterface
{
    use InMemoryRepositoryTrait;

    public static function _class(): string
    {
        return Address::class;
    }
}

#[AsInMemoryTest]
final class SomeTest extends KernelTestCase
{
    private InMemoryAddressRepository $addressRepository;

    protected function setUp(): void
    {
        $this->addressRepository = self::getContainer()->get(InMemoryAddressRepository::class);
    }

    #[Test]
    public function object_should_be_accessible_from_in_memory_repository(): void
    {
        $address = AddressFactory::createOne();
        self::assertSame([$address], $this->addressRepository->_all());
        
        // No database query is made here
        self::assertSame(1, AddressFactory::repository()->count(1));
    }

    protected static function getKernelClass(): string
    {
        return InMemoryKernel::class;
    }
}

In Foundry 2.0, Zenstruck\Foundry\ModelFactory is deprecated. You must choose one of the following based on your use case:

• \Zenstruck\Foundry\ObjectFactory: Use for creating plain objects that are not persisted.
• \Zenstruck\Foundry\Persistence\PersistentObjectFactory: Use for ORM entities or ODM documents that you want to persist and return directly. Note: This does not return a Proxy; remove calls to ->object() on objects created this way.
• \Zenstruck\Foundry\Persistence\PersistentProxyObjectFactory: Use for ORM entities or ODM documents when you want to leverage "auto refresh" behavior. This acts most like the old ModelFactory.

Factory Method Changes:

• getDefaults(): array $\rightarrow$ defaults(): array|callable
• getClass(): string $\rightarrow$ public static function class(): string
• initialize() $\rightarrow$ protected function initialize(): static

To create objects that do not interact with the database (useful for unit tests or non-entity objects), you can use two approaches:

1. Inherit from Zenstruck\Foundry\ObjectFactory: This creates plain objects.
2. Use withoutPersisting(): For existing persistent factories, call withoutPersisting() before creating.

To make a factory non-persisting by default, override its initialize() method.

Manual Persistence: If an object is created without persisting, you can use the save($object) helper to persist it later.

use App\Entity\Post;
use App\Factory\PostFactory;
use function Zenstruck\Foundry\Persistence\save;

// Using an existing factory without persisting
$post = PostFactory::new()->withoutPersisting()->create();
$post->setTitle('something else');
save($post); // Persist manually

// Using the convenience helper
$entity = object(Post::class, ['field' => 'value']);

If you don't have an explicit factory class for an entity, you can use persistent_factory() to create an anonymous factory. To interact with the data created by these factories, use the repository() helper.

Anonymous Factory API:

• $factory->create(['field' => 'value'])
• $factory->many(5)->create(['field' => 'value'])
• $factory->instantiateWith(function () {})
• $factory->beforeInstantiate(function () {})
• $factory->afterInstantiate(function () {})
• $factory->afterPersist(function () {})

Repository API:

• $repository->first(['createdAt']): Get the first object (or latest if a column is provided).
• $repository->last(['createdAt']): Get the last object (or oldest if a column is provided).
• $repository->truncate(): Empty the database table.
• $repository->count(): Number of persisted objects.
• $repository->all(): Returns all persisted objects.
• $repository->findBy(['field' => 'value']): Returns matching objects.
• $repository->find($id) or $repository->find(['field' => 'value']): Find by ID or filter.
• $repository->random(['field' => 'value']): Get a random object.
• $repository->randomSet(count, ['field' => 'value']): Get a random set of objects.
• $repository->randomRange(start, end, ['field' => 'value']): Get a random range of objects.

use App\Entity\Post;
use function Zenstruck\Foundry\Persistence\persistent_factory;
use function Zenstruck\Foundry\Persistence\repository;

$factory = persistent_factory(Post::class);
$factory->create(['field' => 'value']);

$repository = repository(Post::class);
$repository->first();
$repository->findBy(['author' => 'kevin']);