Foundry

https://github.com/zenstruck/foundry
Admin
Foundry is a model factory library for creating expressive, auto-completable, on-demand dev/test...
Tokens:46,243
Snippets:353
Trust Score:7.6
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Start containers and run test suite

Source: https://github.com/zenstruck/foundry/blob/2.x/README.md

Starts the Docker containers, installs dependencies, and runs the main and reset-database test suites. Requires Docker and PHP with mysql, pgsql, and mongodb extensions.

```bash
# start the container
$ docker compose up --detach

# install dependencies
$ composer update

# run main testsuite (with "schema" reset database strategy)
$ ./phpunit

# run "reset-database" testsuite
$ ./phpunit --testsuite reset-database
```

--------------------------------

### Install Foundry with Composer

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Install Foundry as a dev dependency using Composer. Requires Symfony MakerBundle for the make:* commands and Symfony Flex to enable the bundle automatically.

```terminal
$ composer require --dev zenstruck/foundry
```

--------------------------------

### Define an array factory with defaults()

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Shows how to create an associative array factory by extending ArrayFactory and overriding defaults(). The example also shows usage in a test.

```php
use Zenstruck\Foundry\ArrayFactory;

final class SomeArrayFactory extends ArrayFactory
{
    protected function defaults(): array|callable
    {
        return [
            'prop1' => 'default value 1',
            'prop2' => 'default value 2',
        ];
    }
}

// somewhere in a test

// will create ['prop1' => 'foo', 'prop2' => 'default value 2']
$array = SomeArrayFactory::createOne(['prop1' => 'foo']);
```

--------------------------------

### Define a story class (PostStory.php)

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Example story class that creates categories, tags, and posts. The build() method sets up the story state, using factories and random relationships.

```php
// src/Story/PostStory.php
namespace App\Story;

use App\Factory\CategoryFactory;
use App\Factory\PostFactory;
use App\Factory\TagFactory;
use Zenstruck\Foundry\Story;

final class PostStory extends Story
{
    public function build(): void
    {
        // create 10 Category's
        CategoryFactory::createMany(10);

        // create 20 Tag's
        TagFactory::createMany(20);

        // create 50 Post's
        PostFactory::createMany(50, function() {
            return [
                // each Post will have a random Category (created above)
                'category' => CategoryFactory::random(),

                // each Post will between 0 and 6 Tag's (created above)
                'tags' => TagFactory::randomRange(0, 6),
            ];
        });
    }
}
```

--------------------------------

### Distribute categories and dates over posts with distribute()

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Creates two posts and distributes two categories and two dates across them. The first post gets 'category 1' and today's date, the second gets 'category 2' and tomorrow's date. Requires Foundry 2.4 or later.

```php
// let's say we have 2 categories...
$categories = CategoryFactory::createSequence(
    [
        ['name' => 'category 1'],
        ['name' => 'category 2'],
    ]
);

// ...that we want to "distribute" over 2 posts
$posts = PostFactory::new()
    ->sequence(
        [
            ['name' => 'post 1'],
            ['name' => 'post 2'],
        ]
    )

    // "post 1" will have "category 1" and "post 2" will have "category 2"
    ->distribute('category', $categories)

    // you can even chain "distribute()" methods:
    // first post is published today, second post is published tomorrow
    ->distribute('publishedAt', [new \DateTimeImmutable('today'), new \DateTimeImmutable('tomorrow')])

    ->create();
```

--------------------------------

### Combining placeholders in a single step argument

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Gherkin example showing how to combine multiple foundry placeholders in one step argument, using the foundry:id and foundry:lastId syntax.

```gherkin
When I am on "/categories/<foundry:id(category, tech)>/posts/<foundry:lastId(post)>"
```

--------------------------------

### Install Behat extension

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Install the Foundry Behat extension via Composer. This package is required in addition to the main Foundry package.

```terminal
$ composer require --dev zenstruck/foundry-behat
```

--------------------------------

### Define hooks as services with attributes

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Shows how to define hooks as services using the #[AsFoundryHook] attribute, allowing dependency injection and global hook creation. The example includes beforeInstantiate, afterInstantiate, and afterPersist methods with event objects.

```php
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Zenstruck\Foundry\Object\Event\AfterInstantiate;
use Zenstruck\Foundry\Object\Event\BeforeInstantiate;
use Zenstruck\Foundry\Persistence\Event\AfterPersist;

final class FoundryHook
{
    #[AsFoundryHook(Post::class)]
    public function beforeInstantiate(BeforeInstantiate $event): void
    {
        // do something before the post is instantiated:
        // $event->parameters is what will be used to instantiate the object, manipulate as required
        // $event->objectClass is the class of the object being instantiated
        // $event->factory is the factory instance which creates the object
    }

    #[AsFoundryHook(Post::class)]
    public function afterInstantiate(AfterInstantiate $event): void
    {
        // $event->object is the instantiated Post object
        // $event->parameters contains the attributes used to instantiate the object and any extras
        // $event->factory is the factory instance which creates the object
    }

    #[AsFoundryHook(Post::class)]
    public function afterPersist(AfterPersist $event): void
    {
        // this event is only called if the object was persisted
        // $event->object is the persisted Post object
        // $event->parameters contains the attributes used to instantiate the object and any extras
        // $event->factory is the factory instance which creates the object
    }
}
```

--------------------------------

### Repository Decorator usage example

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Shows how to obtain a repository proxy and use its helpful methods. The repository is an instance of RepositoryProxy that wraps the real repository, and all returned objects are proxied. Methods include count, first, last, truncate, random, and more.

```php
use App\Entity\Post;
use App\Factory\PostFactory;
use function Zenstruck\Foundry\Persistence\repository;

// instance of RepositoryProxy that wraps PostRepository
$repository = PostFactory::repository();

// alternative to above for getting a repository for which you haven't created factories for
$repository = repository(Post::class);

// helpful methods - all returned object(s) are proxied
$repository->inner(); // the real "wrapped" repository
$repository->count(); // number of rows in the database table
count($repository); // equivalent to above (RepositoryDecorator implements \Countable)
$repository->first(); // get the first object (assumes an auto-incremented "id" column)
$repository->first('createdAt'); // assuming "createdAt" is a datetime column, this will return latest object
$repository->last(); // get the last object (assumes an auto-incremented "id" column)
$repository->last('createdAt'); // assuming "createdAt" is a datetime column, this will return oldest object
$repository->truncate(); // delete all rows in the database table
$repository->random(); // get a random object
$repository->random(['author' => 'kevin']); // get a random object filtered by the passed criteria
$repository->randomSet(5); // get 5 random objects
$repository->randomSet(5, ['author' => 'kevin']); // get 5 random objects filtered by the passed criteria
$repository->randomRange(0, 5); // get 0-5 random objects
$repository->randomRange(0, 5, ['author' => 'kevin']); // get 0-5 random objects filtered by the passed criteria

// instance of ObjectRepository - all returned object(s) are proxied
$repository->find(1); // Post|null
$repository->find(['title' => 'My Title']); // Post|null
$repository->findOneBy(['title' => 'My Title']); // Post|null
$repository->findAll(); // Post[]
iterator_to_array($repository); // equivalent to above (RepositoryDecorator implements \IteratorAggregate)
$repository->findBy(['title' => 'My Title']); // Post[]

// can call methods on the underlying repository (RepositoryDecorator is a "@mixin" of its wrapped repository)
$repository->findOneByTitle('My Title'); // Post|null
```

--------------------------------

### Load granular Foundry contexts

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Loads one or several granular contexts instead of the full FoundryContext to get only a subset of steps. The contexts are FoundryCreationContext, FoundryAssertionContext, and FoundryPlaceholderContext.

```yaml
default:
    suites:
        main:
            contexts:
                # the "Given" steps creating objects
                - Zenstruck\Foundry\Test\Behat\FoundryCreationContext
                # the "Then" steps asserting on objects and on the database
                - Zenstruck\Foundry\Test\Behat\FoundryAssertionContext
                # the transformations resolving <foundry:...> id placeholders
                - Zenstruck\Foundry\Test\Behat\FoundryPlaceholderContext
```

--------------------------------

### Create Posts with Tags Using Factories

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Shows five ways to create posts with tags using Foundry factories, including pre-creating tags, using random sets/ranges, and creating posts with unique tags. The examples assume a many-to-many relationship between Post and Tag.

```php
use App\Factory\PostFactory;
use App\Factory\TagFactory;

// Example 1: pre-create Tags and attach to Post
$tags = TagFactory::createMany(3);

PostFactory::createOne(['tags' => $tags]);

// Example 2: pre-create Tags and choose a random set
TagFactory::createMany(10);

PostFactory::new()
    ->many(5) // create 5 posts
    ->create(function() { // note the callback - this ensures that each of the 5 posts has a different random set
        return ['tags' => TagFactory::randomSet(2)]; // each post uses 2 random tags from those already in the database
    })
;

// Example 3: pre-create Tags and choose a random range
TagFactory::createMany(10);

PostFactory::new()
    ->many(5) // create 5 posts
    ->create(function() { // note the callback - this ensures that each of the 5 posts has a different random range
        return ['tags' => TagFactory::randomRange(0, 5)]; // each post uses between 0 and 5 random tags from those already in the database
    })
;

// Example 4: create 3 Posts each with 3 unique Tags
PostFactory::createMany(3, ['tags' => TagFactory::new()->many(3)]);

// Example 5: create 3 Posts each with between 0 and 3 unique Tags
PostFactory::createMany(3, ['tags' => TagFactory::new()->many(0, 3)]);
```

--------------------------------

### Access story state in other fixtures

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Shows how to access a story's state when creating other fixtures, using the get() method or the magic method (functionally equivalent).

```php
PostFactory::createOne(['category' => CategoryStory::get('php')]);

// or use the magic method (functionally equivalent to above)
PostFactory::createOne(['category' => CategoryStory::php()]);
```

--------------------------------

### Memoize Factory in Defaults

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Shows how to call memoize() directly on a factory to create a memoized value, which reads better and avoids a common mistake. The example creates a single owner and multiple reviewers, then uses them in the defaults array.

```php
protected function defaults(): array
{
    $owner = UserFactory::new()->memoize();
    // or, for several objects:
    $reviewers = UserFactory::new()->many(2)->memoize();

    return [
        'project' => ProjectFactory::new(['users' => [$owner]]),
        'owner'   => $owner,
    ];
}
```

--------------------------------

### Test with factories following AAA pattern

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Example test method that uses a factory to create a post, performs a request, and asserts the response and database state. Requires kernel shutdown before creating client if factories are used.

```php
public function test_can_post_a_comment(): void
{
    // 1. "Arrange"
    $post = PostFactory::new() // New Post factory
        ->published()          // Make the post in a "published" state
        ->create([             // Instantiate Post and persist
            'slug' => 'post-a' // This test only requires the slug field - all other fields are random data
        ])
    ;

    // 1a. "Pre-Assertions"
    $this->assertCount(0, $post->getComments());

    // 2. "Act"
    static::ensureKernelShutdown(); // Note kernel must be shutdown if you use factories before create client
    $client = static::createClient();
    $client->request('GET', '/posts/post-a'); // Note the slug from the arrange step
    $client->submitForm('Add', [
        'comment[name]' => 'John',
        'comment[body]' => 'My comment',
    ]);

    // 3. "Assert"
    self::assertResponseRedirects('/posts/post-a');

    CommentFactory::assert()->exists([ // Doctrine repository assertions
        'name' => 'John',
        'body' => 'My comment',
    ]);

    CommentFactory::assert()->count(2, ['post' => $post]); // assert given $post has 2 comments
}
```

--------------------------------

### Define a story as a service (PostStory.php)

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Example of a story class that uses dependency injection. The constructor receives MyService, which can be used in build(). In a standard Symfony Flex app, it's autowired; otherwise, register it as a service and tag with foundry.story.

```php
// src/Story/PostStory.php
namespace App\Story;

use App\Factory\PostFactory;
use App\Service\MyService;
use Zenstruck\Foundry\Story;

final class PostStory extends Story
{
    public function __construct(
        private MyService $myService,
    ) {
    }

    public function build(): void
    {
        // $this->myService can be used here to help build this story
    }
}
```

--------------------------------

### One-to-Many relationships: creating posts with comments

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Examples of creating Posts with one-to-many Comment relationships, including fixed counts, ranges, and separate posts per comment.

```php
use App\Factory\CommentFactory;
use App\Factory\PostFactory;

// Example 1: Create a Post with 6 Comments
PostFactory::createOne(['comments' => CommentFactory::new()->many(6)]);

// Example 2: Create 6 Posts each with 4 Comments (24 Comments total)
PostFactory::createMany(6, ['comments' => CommentFactory::new()->many(4)]);

// Example 3: Create 6 Posts each with between 0 and 10 Comments
PostFactory::createMany(6, ['comments' => CommentFactory::new()->range(0, 10)]);
```

--------------------------------

### Use Foundry's faker() helper

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Imports the faker() function and calls it to generate random data. The example shows generating a random email address.

```php
use function Zenstruck\Foundry\faker;

faker()->email(); // random email
```

--------------------------------

### Reset database before first test

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Override resetBeforeFirstTest to perform actions once per test suite, such as installing a PostgreSQL extension. Call the decorated service's method to preserve default behavior.

```php
public function resetBeforeFirstTest(KernelInterface $kernel): void
{
    // do something once per test suite (for instance: install a PostgreSQL extension)

    $this->decorated->resetBeforeFirstTest($kernel);
}
```

--------------------------------

### Use @noResetDB tag to skip reset

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Gherkin example showing how to use the @noResetDB tag on a scenario to keep data from a previous scenario when database_reset_mode is 'scenario'.

```gherkin
@noResetDB
Scenario: Keep data from previous scenario
  Then 1 contact should exist
```

--------------------------------

### Define Factory Defaults with LazyValue and Memoize

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Shows how to use LazyValue::new() and LazyValue::memoize() in a factory's defaults() method to defer value calculation and memoize results. The example creates a shared owner user and a random category, ensuring the same user is used for both project and owner.

```php
use Zenstruck\Foundry\LazyValue;

class TaskFactory extends PersistentObjectFactory
{
    // ...

    protected function defaults(): array
    {
        $owner = LazyValue::memoize(fn() => UserFactory::createOne());

        return [
            // Call CategoryFactory::random() everytime this factory is instantiated
            'category' => LazyValue::new(fn() => CategoryFactory::random()),
            // The same User instance will be both added to the Project and set as the Task owner
            'project' => ProjectFactory::new(['users' => [$owner]]),
            'owner'   => $owner,
        ];
    }
}
```

--------------------------------

### Define default values with Faker

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Example of defaults() method returning an array of default values using Faker integration and custom values. Applied to constructor arguments and properties.

```php
protected function defaults(): array
{
    return [
        // use the built-in Faker integration to generate good random values...
        'title' => self::faker()->unique()->sentence(),
        'body' => self::faker()->sentence(),

        // ...or generate the values yourself if you prefer
        'createdAt' => new \DateTimeImmutable('today'),
    ];
}
```

--------------------------------

### Create non-persisted objects with withoutPersisting()

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Shows how to create objects without persisting them, useful for unit tests. Includes examples for single, many, anonymous factories, and convenience function.

```php
use App\Entity\Post;
use App\Factory\PostFactory;
use function Zenstruck\Foundry\object;
use function Zenstruck\Foundry\Persistence\persistent_factory;
use function Zenstruck\Foundry\Persistence\save;

$post = PostFactory::new()->withoutPersisting()->create(); // returns Post
$post->setTitle('something else'); // do something with object
save($post); // persist the Post

$posts = PostFactory::new()->withoutPersisting()->many(5)->create(); // returns Post[]

// anonymous factories:
$factory = persistent_factory(Post::class);

$entity = $factory->withoutPersisting()->create(['field' => 'value']); // returns Post

$entities = $factory->withoutPersisting()->many(5)->create(['field' => 'value']); // returns Post[]|Proxy[]

// convenience functions
$entity = object(Post::class, ['field' => 'value']);
```

--------------------------------

### Override initialize() method

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Override the factory's initialize() method to add default state and logic. This example sets published by default, custom instantiation, and a default afterPersist event.

```php
final class PostFactory extends PersistentObjectFactory
{
    // ...

    protected function initialize(): static
    {
        return $this
            ->published() // published by default
            ->instantiateWith(function (array $attributes) {
                return new Post(); // custom instantiation for this factory
            })
            ->afterPersist(function () {}) // default event for this factory
        ;
    }
}
```

--------------------------------

### Create a contact with Foundry step

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Gherkin example of a built-in step that creates a single object. The short name 'contact' is resolved from the factory class name (ContactFactory → contact).

```gherkin
# Create a single object
# "contact" is a short name resolved from the factory class name (ContactFactory → contact)
Given there is a contact
```

--------------------------------

### Data Provider with Factory Creation

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Example of using factories in a PHPUnit data provider with Foundry's PHPUnit Extension. Requires PHPUnit 11.4+ and PHP 8.4+ for lazy objects.

```php
use App\Factory\PostFactory;
use PHPUnit\Framework\Attributes\DataProvider;

#[DataProvider('createMultipleObjectsInDataProvider')]
public function test_post_via_data_provider(Post $post): void
{
    // at this point, `$post` exists, and is already stored in database
}

public static function postDataProvider(): iterable
{
    yield [PostFactory::createOne()];
    yield [PostWithServiceFactory::createOne()];
    yield [PostFactory::createOne(['body' => faker()->sentence()])];
}
```

--------------------------------

### Full default bundle configuration

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

The complete default configuration for the Zenstruck Foundry bundle, including faker, instantiator, ORM reset, and Mongo reset settings. Comments show defaults and examples.

```yaml
zenstruck_foundry:
    # Enable auto-refresh with lazy objects (PHP >= 8.4 only).
    enable_auto_refresh_with_lazy_objects: false

    # Configure faker to be used by your factories.
    faker:

        # Change the default faker locale.
        locale:               null # Example: fr_FR

        # Automatically manage faker seed to ensure consistent data between test runs.
        manage_seed:          true

        # Customize the faker service.
        service:              null # Example: my_faker

    # Configure the default instantiator used by your factories.
    instantiator:

        # Use the constructor to instantiate objects.
        use_constructor:      ~

        # Whether or not to allow extra attributes.
        allow_extra_attributes: false

        # Whether or not to skip setters and force set object properties (public/private/protected) directly.
        always_force_properties: false

        # Customize the instantiator service.
        service:              null # Example: my_instantiator
    orm:
        reset:

            # DBAL connections to reset with the reset database mechanism
            connections:

                # Default:
                - default

            # Entity Managers to reset with the reset database mechanism
            entity_managers:

                # Default:
                - default

            # Reset mode to use with the reset database mechanism
            mode:                 schema # One of "schema"; "migrate"
            migrations:

                # Migration configurations
                configurations:       []

    mongo:
        reset:

            # Document Managers to reset with the reset database mechanism
            document_managers:

                # Default:
                - default
```

--------------------------------

### Test permutation environment configuration

Source: https://github.com/zenstruck/foundry/blob/2.x/CLAUDE.md

Environment variables to override in .env.local for fast test setup. Never edit .env or pass variables inline; defaults use sqlite, disable Mongo, and enable native lazy objects on PHP 8.4.

```bash
# .env.local
DATABASE_URL="sqlite:///%kernel.project_dir%/var/data.db" # sqlite: no docker needed
USE_DAMA_DOCTRINE_TEST_BUNDLE="1"                         # wraps tests in transactions, much faster
MONGO_URL=""                                              # disable Mongo
PHPUNIT_VERSION="13"
USE_FOUNDRY_PHPUNIT_EXTENSION="1"
USE_PHP_84_LAZY_OBJECTS="1"                               # native lazy objects instead of generated proxies
```

--------------------------------

### Main development commands

Source: https://github.com/zenstruck/foundry/blob/2.x/CLAUDE.md

Commands for setting up the environment, running tests, and static analysis. Always use the ./phpunit wrapper, never run php-cs-fixer manually, and exclude slow maker tests unless working on them.

```bash
docker compose up --detach   # DBs required by the test suite (mysql:3307, pgsql:5433, mongo:27018)
composer update              # install deps

# provision static analysis tools (bin/tools) — not run automatically on install
# (phpbench is required too: phpstan.neon bootstraps bin/tools/phpbench/vendor/autoload.php)
composer bin phpstan install && composer bin phpbench install

./phpunit --exclude-group=maker      # main testsuite (wrapper script, NOT vendor/bin/phpunit directly);
                                     # always exclude slow "maker" tests unless working on the maker commands
./phpunit --testsuite reset-database # only when touching the reset-database strategies
./phpunit --filter SomeTest          # single test/class

# static analysis
bin/tools/phpstan/vendor/phpstan/phpstan/phpstan analyse

# docs linter
docker run --rm -e DOCS_DIR='/docs' -v ${PWD}/docs:/docs oskarstark/doctor-rst --short
```

--------------------------------

### Use the factory

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Import the factory class to use it in your code.

```php
use App\Factory\PostFactory;
```

--------------------------------

### Create a story with make:story command

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Run this command to generate a new story class. It creates PostStory.php in src/Story by default, or in tests/Story with the --test flag.

```terminal
$ php bin/console make:story Post
```

--------------------------------

### Use the service factory normally

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Shows how to use the service factory to create users with a custom password or the default one. The password is encoded when the hasher is available.

```php
UserFactory::createOne(['password' => 'mypass'])->getPassword(); // "mypass" encoded
UserFactory::createOne()->getPassword(); // "1234" encoded (because "1234" is set as the default password)
```

--------------------------------

### Override MySQL port with docker-compose.override.yml

Source: https://github.com/zenstruck/foundry/blob/2.x/README.md

Example docker-compose.override.yml to map MySQL port 3308 to 3306, used with a corresponding .env.local to connect to that port.

```yaml
# docker-compose.override.yml
version: '3.9'

services:
    mysql:
        ports:
            - "3308:3306"
```

--------------------------------

### Use factory states in tests

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Shows how to use the defined states in tests by chaining methods off new() and then calling create(). Demonstrates combining multiple states.

```php
// never use the constructor (i.e. "new PostFactory()"), but use the
// "new()" method. After defining the states, call "create()" to create
// and persist the model.
$post = PostFactory::new()->unpublished()->create();
$post = PostFactory::new()->withViewCount(3)->create();

// combine multiple states
$post = PostFactory::new()
    ->unpublished()
    ->withViewCount(10)
    ->create()
;
```

--------------------------------

### Recommended defaults() patterns for relationships

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Shows recommended and not recommended ways to define defaults() for relationships, using factory instances and lazy values to avoid unintended entity creation.

```php
protected function defaults(): array
{
    return [
        // RECOMMENDED
        // The Post will only be created when the factory is instantiated
        'post' => PostFactory::new(),
        'post' => PostFactory::new()->published(),
        // The callback will be called when the factory is instantiated, creating the Post
        'post' => LazyValue::new(fn () => PostFactory::createOne()),
        'post' => lazy(fn () => PostFactory::new()->published()->create()),

        // NOT RECOMMENDED
        // Will potentially result in extra unintended Posts (if you override the value during instantiation)
        'post' => PostFactory::createOne(),
        'post' => PostFactory::new()->published()->create(),
    ];
}
```

--------------------------------

### Using FactoryCollection sequence as data provider

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Shows how to use ObjectFactory::new()->sequence() to generate data providers with multiple test cases.

```php
use App\Factory\PostFactory;

/**
 * @dataProvider postDataProvider
 */
public function test_post_via_data_provider(PostFactory $factory): void
{
    $factory->create();

    // ...
}

public static function postDataProvider(): iterable
{
    yield from PostFactory::new()->sequence(
        [
            ['title' => 'foo'],
            ['title' => 'bar'],
        ]
    )->asDataProvider();
}
```

--------------------------------

### Use @resetDB tag to force reset

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Gherkin example showing how to use the @resetDB tag to force a database reset when using manual or feature reset modes.

```gherkin
@resetDB
Scenario: Start with fresh database
  Then 0 contacts should exist
```

--------------------------------

### Generated PostFactory class

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Example of a generated factory class extending PersistentObjectFactory. Includes constructor, class() method, defaults() with Faker values, and initialize() method for customization.

```php
// src/Factory/PostFactory.php
namespace App\Factory;

use App\Entity\Post;
use App\Repository\PostRepository;
use Zenstruck\Foundry\Persistence\PersistentObjectFactory;
use Zenstruck\Foundry\Persistence\ProxyRepositoryDecorator;

/**
 * @extends PersistentObjectFactory<Post>
 */
final class PostFactory extends PersistentObjectFactory
{
    /**
     * @see https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html#factories-as-services
     *
     * @todo inject services if required
     */
    public function __construct()
    {
    }

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

    /**
     * @see https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html#factories
     *
     * @todo add your default values here
     */
    protected function defaults(): array|callable
    {
        return [
            'createdAt' => \DateTimeImmutable::createFromMutable(self::faker()->dateTime()),
            'title' => self::faker()->text(255),
        ];
    }

    /**
     * @see https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html#initialization
     */
    protected function initialize(): static
    {
        return $this
            // ->afterInstantiate(function(Post $post): void {})
        ;
    }
}
```

--------------------------------

### Create sequences of objects

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Shows how to use createSequence() to create multiple objects with different attributes, either via an array of attribute sets or a generator callback. Also shows using sequence() with states.

```php
use App\Factory\PostFactory;

// create/persist 2 posts based on a sequence of attributes
PostFactory::createSequence(
    [
        ['name' => 'title 1'],
        ['name' => 'title 2'],
    ]
);

// create 10 posts using a sequence callback with an incremental index
PostFactory::createSequence(
    function() {
        foreach (range(1, 10) as $i) {
            yield ['name' => "title $i"];
        }
    }
);

// sequences could also be used with a factory with states
$posts = PostFactory::new()
    ->unpublished()
    ->sequence(
        [
            ['name' => 'title 1'],
            ['name' => 'title 2'],
        ]
    )->create();
```

--------------------------------

### Define factory states with with() and faker()

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Shows how to define custom states in a factory class by returning $this->with() with attribute arrays or callables. Use this to create reusable, readable test fixtures.

```php
final class PostFactory extends PersistentObjectFactory
{
    // ...

    public function published(): self
    {
        // call setPublishedAt() and pass a random DateTime
        return $this->with(['published_at' => self::faker()->dateTime()]);
    }

    public function unpublished(): self
    {
        return $this->with(['published_at' => null]);
    }

    public function withViewCount(?int $count = null): self
    {
        return $this->with(function () use ($count) {
            return ['view_count' => $count ?? self::faker()->numberBetween(0, 10000)];
        });
    }
}
```

--------------------------------

### Many-to-One relationships: creating related entities

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Examples of creating Comments with Posts in many-to-one relationships, including pre-created posts, random posts, and creating multiple comments with different or same posts.

```php
use App\Factory\CommentFactory;
use App\Factory\PostFactory;

// Example 1: pre-create Post and attach to Comment
$post = PostFactory::createOne();

CommentFactory::createOne(['post' => $post]);

// Example 2: pre-create Posts and choose a random one
PostFactory::createMany(5); // create 5 Posts

CommentFactory::createOne(['post' => PostFactory::random()]);

// or create many, each with a different random Post
CommentFactory::createMany(
    5, // create 5 comments
    function() { // note the callback - this ensures that each of the 5 comments has a different Post
        return ['post' => PostFactory::random()]; // each comment set to a random Post from those already in the database
    }
);

// Example 3: create a separate Post for each Comment
CommentFactory::createMany(5, [
    // this attribute is an instance of PostFactory that is created separately for each Comment created
    'post' => PostFactory::new(),
]);

// Example 4: create multiple Comments with the same Post
CommentFactory::createMany(5, [
    'post' => PostFactory::createOne(), // note the "createOne()" here
]);
```

--------------------------------

### Bundle configuration with YAML anchors

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Shows how to use YAML anchors with when@dev/when@test to share configuration between dev and test environments. The when@test: *dev line copies the dev config.

```yaml
# config/packages/zenstruck_foundry.yaml
when@dev: &dev
    zenstruck_foundry:
        # ... put all your config here

when@test: *dev # "copies" the config from above
```

--------------------------------

### Faster local test configuration

Source: https://github.com/zenstruck/foundry/blob/2.x/README.md

Recommended .env.local settings to speed up the test suite by enabling dama/doctrine-test-bundle, disabling Mongo, using PHPUnit 12, and enabling all Foundry features.

```dotenv
# dama/doctrine-test-bundle makes Foundry testsuite really faster
USE_DAMA_DOCTRINE_TEST_BUNDLE="1"

# using both ODM and ORM makes the "reset db" mechanism slower
MONGO_URL=""

# Use the last version of PHPUnit
PHPUNIT_VERSION="12"

# Enable all features of Foundry
USE_FOUNDRY_PHPUNIT_EXTENSION="1"
```

--------------------------------

### Override default configuration with .env.local

Source: https://github.com/zenstruck/foundry/blob/2.x/README.md

Shows how to override environment variables in a .env.local file to change the database, disable Mongo, enable dama/doctrine-test-bundle, set PHPUnit version, and configure migration reset mode. Then runs the test suite with vendor/bin/phpunit.

```bash
# .env.local

# change the database to postgreSQL...
DATABASE_URL="postgresql://zenstruck:zenstruck@127.0.0.1:5433/zenstruck_foundry?serverVersion=15"
# ...or to SQLite
DATABASE_URL="sqlite:///%kernel.project_dir%/var/data.db"

MONGO_URL="" # disables Mongo
USE_DAMA_DOCTRINE_TEST_BUNDLE="1" # enables dama/doctrine-test-bundle
PHPUNIT_VERSION="11" # possible values: 9, 10, 11, 11.4

# test reset database with migrations,
# only relevant for "reset-database" testsuite
DATABASE_RESET_MODE="migrate"
MIGRATION_CONFIGURATION_FILE="tests/Fixture/MigrationTests/configs/migration-configuration.php"

# run test suite with postgreSQL
$ vendor/bin/phpunit
```

--------------------------------

### Apply state methods to a collection with applyStateMethod()

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Defines a PostFactory with 'published' and 'title' state methods, then applies them to a collection of three posts. The 'title' method receives the index (0-based) and returns a title like 'title 0'. Requires Foundry 2.4+.

```php
final class PostFactory extends PersistentObjectFactory
{
    // ...

    public function published(): self
    {
        return $this->with(['published_at' => self::faker()->dateTime()]);
    }

    public function title(string $title): self
    {
        return $this->with(['title' => $title]);
    }
}

$post = PostFactory::new()
    ->many(3)
    ->applyStateMethod('published')
    ->applyStateMethod('title', static fn(int $i) => ["title $i"])
    ->create()
;
```

--------------------------------

### Object proxy usage

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Objects created by PersistentProxyObjectFactory are wrapped in a Proxy object, providing Active Record-like behavior. Use _real() to get the wrapped object, call methods directly, and use _save(), _refresh(), _delete(), and _repository() for database operations.

```php
use App\Factory\PostFactory;

$post = PostFactory::createOne(['title' => 'My Title']); // instance of Zenstruck\Foundry\Proxy

// get the wrapped object
$realPost = $post->_real(); // instance of Post

// call any Post method
$post->getTitle(); // "My Title"

// set property and save to the database
$post->setTitle('New Title');
$post->_save();

// refresh from the database
$post->_refresh();

// delete from the database
$post->_delete();

$post->_repository(); // repository proxy wrapping PostRepository (see Repository Proxy section below)
```

--------------------------------

### Run make:factory command

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Terminal command to generate a factory for an entity. Prompts for the entity class and creates src/Factory/PostFactory.php.

```terminal
$ php bin/console make:factory

    > Entity class to create a factory for:
    > Post

    created: src/Factory/PostFactory.php

    Next: Open your new factory and set default values/states.
```

--------------------------------

### Customize instantiator with Instantiator

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Shows various ways to customize the instantiator using Instantiator::withConstructor(), withoutConstructor(), allowExtra(), alwaysForce(), namedConstructor(), and a callable. The callable receives attributes matching its parameter names, remaining attributes are used for hydration.

```php
use App\Entity\Post;
use App\Factory\PostFactory;
use Zenstruck\Foundry\Object\Instantiator;

// set the instantiator for the current factory
PostFactory::new()
    // instantiate the object without calling the constructor
    ->instantiateWith(Instantiator::withoutConstructor())

    // "foo" and "bar" attributes are ignored when instantiating
    ->instantiateWith(Instantiator::withConstructor()->allowExtra('foo', 'bar'))

    // all extra attributes are ignored when instantiating
    ->instantiateWith(Instantiator::withConstructor()->allowExtra())

    // force set "title" and "body" when instantiating
    ->instantiateWith(Instantiator::withConstructor()->alwaysForce('title', 'body'))

    // never use setters, always "force set" properties (even private/protected, does not use setter)
    ->instantiateWith(Instantiator::withConstructor()->alwaysForce())

    // can combine the different "modes"
    ->instantiateWith(Instantiator::withoutConstructor()->allowExtra()->alwaysForce())

    // use a "namedConstructor"
    ->instantiateWith(Instantiator::namedConstructor("methodName"))

    // use a callable: it will be passed the attributes matching its parameters names,
    // remaining attributes will be used in the hydration phase
    ->instantiateWith(Instantiator::use(function(string $title): object {
        return new Post($title); // ... your own instantiation logic
    }))
;
```

--------------------------------

### Run documentation linter

Source: https://github.com/zenstruck/foundry/blob/2.x/README.md

Runs the documentation linter (doctor-rst) via Docker to verify document syntax adheres to standards.

```shell
docker run --rm -it -e DOCS_DIR='/docs' -v ${PWD}/docs:/docs  oskarstark/doctor-rst:latest
```

--------------------------------

### Register a custom Faker provider

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Shows how to register a custom Faker provider by tagging a service with 'foundry.faker_provider'. All public methods on that service become available on Foundry's Faker instance.

```php
use function Zenstruck\Foundry\faker;

faker()->customMethodOnMyService();
```

--------------------------------

### Quoting rules for multi-word names in placeholders

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Gherkin examples showing that multi-word names inside quoted step arguments must not be quoted, while PyStrings and table cells can contain quoted names. A quote inside the placeholder would close the step pattern's own quoted group prematurely.

```gherkin
# inline arguments: no quotes around multi-word names
When I am on "/events/<foundry:id(event date, opening)>"

# PyStrings and table cells: quoted names are fine
Then the response should equal:
  """
  <foundry:id("event date", "opening")>
  """
```

--------------------------------

### Global instantiator configuration (YAML)

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Configure the instantiator globally for all factories in YAML. Options include use_constructor, allow_extra_attributes, always_force_properties, or a custom service. This can be overridden by factory instance instantiators.

```yaml
# config/packages/zenstruck_foundry.yaml
when@dev: # see Bundle Configuration section about sharing this in the test environment
    zenstruck_foundry:
        instantiator:
            use_constructor: false # always instantiate objects without calling the constructor
            allow_extra_attributes: true # always ignore extra attributes
            always_force_properties: true # always "force set" properties
            # or
            service: my_instantiator # your own invokable service for complete control
```

--------------------------------

### Get random Posts with random, randomOrCreate, randomSet, randomRange, randomRangeOrCreate

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Retrieves random persisted Posts, optionally filtered by attributes. randomOrCreate persists a new random object if none exists. randomSet returns a set, randomRange returns a range, and randomRangeOrCreate creates a new random range if none exists.

```php
// get a random object that has been persisted
$post = PostFactory::random(); // returns Post
$post = PostFactory::random(['author' => 'kevin']); // filter by the passed attributes

// or automatically persist a new random object if none exists
$post = PostFactory::randomOrCreate();
$post = PostFactory::randomOrCreate(['author' => 'kevin']); // filter by or create with the passed attributes

// get a random set of objects that have been persisted
$posts = PostFactory::randomSet(4); // array containing 4 "Post" objects
$posts = PostFactory::randomSet(4, ['author' => 'kevin']); // filter by the passed attributes

// random range of persisted objects
$posts = PostFactory::randomRange(0, 5); // array containing 0-5 "Post" objects
$posts = PostFactory::randomRange(0, 5, ['author' => 'kevin']); // filter by the passed attributes

// or automatically persist a new random range of objects if none exists
$posts = PostFactory::randomRangeOrCreate(0, 5); // array containing 0-5 "Post" objects
$posts = PostFactory::randomRangeOrCreate(0, 5, ['author' => 'kevin']); // filter by or create with the passed attributes
```

--------------------------------

### Configure Foundry manually in tests/bootstrap.php for non-kernel tests

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Use UnitTestConfig::configure() to set instantiator and faker options when the bundle is not available. Required for non-kernel tests.

```php
// tests/bootstrap.php
// ...

Zenstruck\Foundry\Test\UnitTestConfig::configure(
    instantiator: Zenstruck\Foundry\Object\Instantiator::withoutConstructor()
        ->allowExtra()
        ->alwaysForce(),
    faker: Faker\Factory::create('fr_FR')
);
```

--------------------------------

### Load fixtures by name and group

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Commands to load fixtures by story name or group name. Multiple names can be passed, mixing story names and group names. The database is reset only once, and stories belonging to multiple groups are loaded only once.

```terminal
$ php bin/console foundry:load-fixtures category post
$ php bin/console foundry:load-fixtures all other-group category
```

--------------------------------

### Run paratest with WrapperRunner

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Command to run paratest with the WrapperRunner option, required for DAMADoctrineTestBundle compatibility with paratest < 7.0.

```terminal
vendor/bin/paratest --runner WrapperRunner
```

--------------------------------

### Enable Psalm extension

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Enable the Psalm extension for Foundry using the Psalm plugin manager. This command must be run in the terminal.

```terminal
$ vendor/bin/psalm enable zenstruck/foundry
```

--------------------------------

### Add factory hooks with callbacks and priority

Source: https://github.com/zenstruck/foundry/blob/2.x/docs/index.rst

Shows how to add beforeInstantiate, afterInstantiate, and afterPersist hooks to a factory. Hooks run in order added or by priority (higher first). The beforeInstantiate callback must return the modified parameters. afterPersist only runs if the object was persisted. Priority was added in Foundry 2.8.

```php
use App\Factory\PostFactory;
use Zenstruck\Foundry\Proxy;

PostFactory::new()
    ->beforeInstantiate(function(array $parameters, string $class, static $factory): array {
        // $parameters is what will be used to instantiate the object, manipulate as required
        // $class is the class of the object being instantiated
        // $factory is the factory instance which creates the object
        $parameters['title'] = 'Different title';

        return $parameters; // must return the final $parameters
    })
    ->afterInstantiate(function(Post $object, array $parameters, static $factory): void {
        // $object is the instantiated object
        // $parameters contains the attributes used to instantiate the object and any extras
        // $factory is the factory instance which creates the object
    })
    ->afterPersist(function(Post $object, array $parameters, static $factory) {
        // this event is only called if the object was persisted
        // $object is the persisted Post object
        // $parameters contains the attributes used to instantiate the object and any extras
        // $factory is the factory instance which creates the object
    })

    // multiple events are allowed
    // priority can be provided: all the following would be executed before the previous ones
    ->beforeInstantiate(function($parameters) { return $parameters; }, priority: 10)
    ->afterInstantiate(function() {}, priority: 10)
    ->afterPersist(function() {}, priority: 10)
;
```
Tokens:
Raw