Zenstruck Foundry

https://symfony.com/bundles/ZenstruckFoundryBundle/current/
Admin
Zenstruck Foundry is a Symfony bundle that turns fixture creation into a joy with an expressive,...
Tokens:23,149
Snippets:222
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Example feature file step

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Usage of the custom step definition defined in the context class.

```gherkin
Given create a contact called "john"
```

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

### Install Behat Extension

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Install the independent Behat extension package via Composer.

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

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

### Managing One-to-Many Relationships

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Examples for creating parent entities with collections of child entities using the many and range methods.

```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)]);
```

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

### Install Foundry via Composer

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Use this command to add the ZenstruckFoundryBundle as a development dependency to your Symfony project.

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

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

### Using the Repository Decorator

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Demonstrates how to wrap repositories to access helper methods for database operations and object retrieval.

```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
```

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

### Full default configuration for ZenstruckFoundryBundle

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Reference for all available configuration options for the bundle.

```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

    # Array of stories that should be used as global state.
    global_state:         []

    make_factory:

        # Default namespace where factories will be created by maker.
        default_namespace:    Factory

        # Add "beginner" hints in the created factory.
        add_hints:    true
    make_story:

        # Default namespace where stories will be created by maker.
        default_namespace:    Story
```

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

### Access Story State

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Retrieve stored objects using the get method or magic methods.

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

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

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

### Interacting with Object Proxies

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Demonstrates basic operations on a proxy object, including accessing the real object, calling methods, and database persistence.

```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)
```

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

### Doctrine Proxy Pitfall Error

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Example of the error message encountered when passing a proxy object to the Doctrine EntityManager.

```text
> Doctrine\ORM\ORMInvalidArgumentException: A new entity was found through the relationship
'App\Entity\Post#category' that was not configured to cascade persist operations for entity: AppEntityCategoryProxy@3082.
To solve this issue: Either explicitly call EntityManager#persist() on this unknown entity or configure cascade persist
this association in the mapping for example @ManyToOne(..,cascade={"persist"}). If you cannot find out which entity
causes the problem implement 'App\Entity\Category#__toString()' to get a clue.
```

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

### Configuring Global State

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Configures initial database state for tests within the bundle configuration file.

```yaml
# config/packages/zenstruck_foundry.yaml
when@test: # see Bundle Configuration section about sharing this in the test environment
    zenstruck_foundry:
        global_state:
            - App\Story\StoryThatIsAService
            - App\Story\GlobalStory
            - invokable.service # just a service with ::invoke()
            - ...
```

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

### Customizing Factory Instantiation

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Demonstrates various ways to configure the instantiator for a factory, including bypassing constructors, allowing extra attributes, and using custom callables.

```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
    }))
;
```

```php
->instantiateWith(function(array $attributes, string $class): object {
    return new Post(); // ... your own logic
})
```

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

### Accessing Non-Public Properties

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Use these helper methods to get or set private and protected properties on the wrapped object.

```php
// set private/protected properties
$post->_set('createdAt', new \DateTime());

// get private/protected properties
$post->_get('createdAt');
```

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

### Apply Factory States in Tests

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Use the new() method to initialize a factory and chain state methods before calling create().

```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()
;
```

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

### Handling Unsaved Changes Exception

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

When auto-refresh is enabled, multiple state changes can trigger an exception. This example shows the problematic scenario.

```php
use App\Factory\PostFactory;

$post = PostFactory::new(['title' => 'Original Title', 'body' => 'Original Body'])
    ->create()
    ->_enableAutoRefresh()
;

$post->setTitle('New Title');
$post->setBody('New Body'); // exception thrown because of "unsaved changes" to $post from above
```

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

### Applying State Methods to Collections

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Demonstrates using applyStateMethod() to trigger factory methods on each item within a collection.

```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()
;
```

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

### Using the force() Helper

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Forces property setting on-demand, bypassing setters while still allowing constructor arguments.

```php
use App\Factory\PostFactory;

use function Zenstruck\Foundry\force;

// in this case, the "body" attribute will be set directly, without using the setter
PostFactory::createOne(['body' => force('some body')]) ;

// in this case, the "title" attribute will still be used in the constructor (otherwise an error would be thrown)
PostFactory::createOne(['title' => force('some title')]) ;
// ...unless we disable the constructor:
PostFactory::new()
    ->instantiateWith(Instantiator::withoutConstructor())
    ->create(['title' => force('some title')]) ;
```

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

### Configuring Foundry for Unit Tests

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Manual configuration of Foundry in the bootstrap file, as bundle configuration is not automatically picked up in 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')
);
```

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

### Configure ZenstruckFoundryBundle for dev and test environments

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Use YAML anchors to share configuration between development and test environments.

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

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

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

### Generate data providers with FactoryCollection

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Use sequence() and asDataProvider() to generate multiple test cases from a collection of factory states.

```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();
}
```

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

### Implement an In-memory Repository

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Create a repository class implementing InMemoryRepository and using InMemoryRepositoryTrait to manage domain objects in memory.

```php
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<Address> */
    use InMemoryRepositoryTrait;

    // The class returned by this method is the class managed by this repository
    public static function _class(): string
    {
        return Address::class;
    }

    // + all methods implementing "DomainAddressRepository"
}
```

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

### Creating Object Sequences

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Shows how to generate multiple objects using static arrays or generator callbacks.

```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();
```

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

### Enable Psalm Plugin

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Command to enable the Zenstruck Foundry Psalm extension.

```bash
$ vendor/bin/psalm-plugin enable zenstruck/foundry
```

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

### Implementing AAA Testing Pattern

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Demonstrates creating fixtures with factories and performing assertions within a test case.

```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 object 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
}
```

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

### Configure Migration-based Reset

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Configure the bundle to use migrations for database resets instead of schema commands.

```yaml
# config/packages/zenstruck_foundry.yaml
when@dev: # see Bundle Configuration section about sharing this in the test environment
    zenstruck_foundry:
        orm:
            reset:
                mode: migrate # enables resetting with migrations

                # optional: allows you to pass additional configuration to the doctrine:migrations:migrate command
                migrations:
                    configurations:
                        - '%kernel.root_dir%/migrations/configuration.php'
                        - 'migrations/configuration.yaml'
```

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

### Create a Story

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Use the Symfony console command to generate a new story class.

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

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

### Global Instantiator Configuration

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Configures the instantiator globally for all factories via the bundle configuration file.

```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
```

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

### Configure flush once behavior

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Enable the flush_once configuration to optimize performance by limiting flush calls per create operation.

```yaml
zenstruck_foundry:
    persistence:
        flush_once: true
```

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

### Run Paratest with WrapperRunner

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Use the WrapperRunner option when combining Paratest with DAMADoctrineTestBundle to ensure the database is reset once per process.

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

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

### Managing Many-to-One Relationships

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Demonstrates various ways to associate related entities in Many-to-One relationships, including using callbacks for unique associations.

```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
]);
```

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

### Using Factories in a Unit Test

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Demonstrates creating a factory instance in a standard PHPUnit test. Factories created here are not persisted to the database.

```php
use App\Factory\PostFactory;
use PHPUnit\Framework\TestCase;
use Zenstruck\Foundry\Test\Factories;

class MyUnitTest extends TestCase
{
    public function some_test(): void
    {
        $post = PostFactory::createOne();

        // $post is not persisted to the database
    }
}
```

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

### Marking a Story as a Fixture

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Use the #[AsFixture] attribute to register a story for the foundry:load-fixtures command.

```php
use Zenstruck\Foundry\Attribute\AsFixture;

#[AsFixture(name: 'category')]
final class CategoryStory extends Story
{
    // ...
}
```

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

### Configure Granular Foundry Contexts

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Load specific context traits individually if you do not require the full suite of built-in steps.

```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
```

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

### Configure Built-in FoundryContext

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Add the full FoundryContext to your behat.yaml to enable all built-in step definitions.

```yaml
default:
    suites:
        main:
            contexts:
                - Zenstruck\Foundry\Test\Behat\FoundryContext
```

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

### Using PHPUnit Assertions

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Shows how to use Foundry's built-in assertions to verify the state of persisted entities in tests.

```php
use App\Factory\PostFactory;
use function Zenstruck\Foundry\Persistence\assert_not_persisted;
use function Zenstruck\Foundry\Persistence\assert_persisted;

$post = PostFactory::createOne();
assert_persisted($post);
assert_not_persisted($post);

PostFactory::assert()->empty();
PostFactory::assert()->count(3);
PostFactory::assert()->countGreaterThan(3);
PostFactory::assert()->countGreaterThanOrEqual(3);
PostFactory::assert()->countLessThan(3);
PostFactory::assert()->countLessThanOrEqual(3);
PostFactory::assert()->exists(['title' => 'My Title']);
PostFactory::assert()->notExists(['title' => 'My Title']);
```

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

### Configure Auto-Refresh

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Enable the auto-refresh feature globally via the bundle configuration file.

```yaml
# config/packages/zenstruck_foundry.yaml
when@dev: # see Bundle Configuration section about sharing this in the test environment
    zenstruck_foundry:
        enable_auto_refresh_with_lazy_objects: true
```

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

### Grouping Stories for Fixture Loading

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Assign stories to groups to load multiple fixtures simultaneously using the foundry:load-fixtures command.

```php
use Zenstruck\Foundry\Attribute\AsFixture;

#[AsFixture(name: 'category', groups: ['all'])]
final class CategoryStory extends Story {}

#[AsFixture(name: 'post', groups: ['all'])]
final class PostStory extends Story {}
```

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

### Configure Behat Extension

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Enable the Foundry and Symfony extensions in your behat.yaml file.

```yaml
default:
    extensions:
        Zenstruck\Foundry\Test\Behat\FoundryExtension: ~

        # SymfonyExtension is required for the Foundry Behat extension to work, so make sure to enable it as well
        FriendsOfBehat\SymfonyExtension: ~
```

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

### Configure Default Factory Namespace

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Set a global namespace for generated factories in the bundle configuration.

```yaml
# config/packages/zenstruck_foundry.yaml
zenstruck_foundry:
    make_factory:
        default_namespace: 'App\MyFactories'
```

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

### Define Story Build Logic

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Implement the build method to define the database state created by the story.

```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),
            ];
        });
    }
}
```

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

### Generate a Factory

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Use the maker command to create a persistent object factory for a specific entity.

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

> Entity class to create a factory for:
> Post

created: src/Factory/PostFactory.php
```

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

### Define Factory Defaults

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Implement the defaults method to provide initial data for object creation using Faker.

```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'),
    ];
}
```

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

### Define factory lifecycle hooks

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Use beforeInstantiate, afterInstantiate, and afterPersist to modify parameters or perform actions during object creation. Hooks can be chained and assigned priorities.

```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)
;
```

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

### Factory Immutability

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Demonstrates that factory methods return new instances rather than modifying the existing one.

```php
use App\Factory\PostFactory;

$factory = PostFactory::new();
$factory1 = $factory->with([]); // returns a new PostFactory object
$factory2 = $factory->instantiateWith(function () {}); // returns a new PostFactory object
$factory3 = $factory->beforeInstantiate(function () {}); // returns a new PostFactory object
$factory4 = $factory->afterInstantiate(function () {}); // returns a new PostFactory object
$factory5 = $factory->afterPersist(function () {}); // returns a new PostFactory object
```

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

### Define Factories as Services

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Inject dependencies into factories by defining them as services, ensuring the injected service is nullable for unit testing compatibility.

```php
// src/Factory/UserFactory.php
use Symfony\Component\PasswordHasher\Hasher\UserPasswordHasherInterface;

final class UserFactory extends PersistentObjectFactory
{
    // the injected service should be nullable in order to be used in unit test, without container
    public function __construct(
        private ?UserPasswordHasherInterface $passwordHasher = null
    ) {
        parent::__construct();
    }

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

    protected function defaults(): array
    {
        return [
            'email' => self::faker()->unique()->safeEmail(),
            'password' => '1234',
        ];
    }

    protected function initialize(): static
    {
        return $this
            ->afterInstantiate(function(User $user) {
                if ($this->passwordHasher !== null) {
                    $user->setPassword($this->passwordHasher->hashPassword($user, $user->getPassword()));
                }
            })
        ;
    }
}
```

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

### Loading Fixtures in a Scenario

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Apply the @withFixture tag to a scenario to load the specified story before execution.

```gherkin
@withFixture(my-contacts)
Scenario: View contacts
  Then 3 contacts should exist

@withFixture(my-contacts)
Scenario: Assert john exists
  # Objects added with "addState()" are automatically available in the objects registry and can be
  # referenced in your scenarios.
  Then contact named "john" should have properties:
    | name     |
    | John     |
```

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

### Improve Autocompletion with Magic Methods

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Use PHPDoc annotations to define magic methods for better IDE support and static analysis.

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

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

/**
 * @method static Category<Category> php()
 */
final class CategoryStory extends Story
{
    public function build(): void
    {
        $this->addState('php', CategoryFactory::createOne(['name' => 'php']));
    }
}
```

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

### Use foundry object syntax for manual resolution

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Use the <foundry:object(type, name)> syntax when automatic type resolution fails.

```gherkin
Given there is a category named "tech"
Given there is a post named "my-post" with:
  | title   | category                         |
  | My Post | <foundry:object(category, tech)> |
```

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

### Perform database assertions

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Use various assertion steps to verify object counts, properties, and existence in the database.

```gherkin
# count objects of a type
Then 2 contacts should exist

# assert a specific object has properties
Then contact named "john" should have properties:
  | name     |
  | John Doe |

# You can also use various natural language forms:
Then the contact named "john" should exist and have properties:
  | name     |
  | John Doe |

# assert if objects are persisted or not: the database is checked whenever the
# object is persisted and identifiable (objects from non-persistent factories
# fall back to a registry-only check).
# "should exist" requires the name to have been registered by a "Given" step (or a fixture),
# then asserts the row is still present in the database.
Then contact named "john" should exist

# "should not exist" passes if the name was never registered, or if the row was
# deleted from the database (e.g. by the endpoint under test).
Then contact named "jane" should not exist

# assert against the database with a set of properties, whoever created the
# row (a Foundry "Given" step or the application under test):
Then a contact should exist with:
  | name     |
  | John Doe |
Then no contact should exist with:
  | name |
  | Jane |

# assert by id, either a literal one or an id placeholder (see below).
# Like names, ids must be quoted when they contain a space:
Then the contact with id 42 should exist
Then the contact with id "<foundry:id(contact, john)>" should have properties:
  | name     |
  | John Doe |
Then the contact with id 42 should not exist
```

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

### Override Factory Initialization

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Customize default state and instantiation logic by overriding the initialize() method in a factory.

```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
        ;
    }
}
```

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

### Combining Fixtures with Database Reset

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Fixtures are automatically reloaded when @withFixture is combined with @resetDB.

```gherkin
@withFixture(my-contacts)
Feature: Contacts management
  Scenario: List all contacts
    Then 3 contacts should exist

  @resetDB
  Scenario: Start fresh but still have fixtures
    # Database was reset, but fixtures were reloaded
    Then 3 contacts should exist
```

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

### Customize Reset Connections and Managers

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Define specific ORM connections and object managers to be reset in the bundle configuration.

```yaml
# config/packages/zenstruck_foundry.yaml
when@dev: # see Bundle Configuration section about sharing this in the test environment
    zenstruck_foundry:
        orm:
            reset:
                connections:
                    - orm_connection_1
                    - orm_connection_2
                entity_managers:
                    - orm_object_manager_1
                    - orm_object_manager_2
                mode: schema # default value, enables resetting the schema with doctrine:schema commands
        mongo:
            reset:
                document_managers:
                    - odm_object_manager_1
                    - odm_object_manager_2
```

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

### Register a custom Faker provider

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Tag a service with foundry.faker_provider to make its public methods available via the faker() function.

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

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

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

### Configuring Foundry PHPUnit Extension

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Register the Foundry extension in your phpunit.xml file to enable it globally.

```xml
<phpunit>
    <extensions>
        <bootstrap class="Zenstruck\Foundry\PHPUnit\FoundryExtension"/>
    </extensions>
</phpunit>
```

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

### Create Objects in Behat

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Use Gherkin steps to create single or multiple objects, optionally naming them for later reference in the object registry.

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

# Create a named object: this name will be useful for later reference
Given there is a contact named "john"

# Create an object with properties
Given there is a contact named "john" with:
  | name     | email          |
  | John Doe | john@email.com |

# Create multiple objects
# Notice that you can use the plural form of the factory name
Given there are contacts with:
  | _ref | name     |
  | A    | John Doe |
  | B    | Jane Doe |
```

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

### Configure Doctrine for Paratest

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Update your Doctrine configuration to use the TEST_TOKEN environment variable, ensuring each parallel process uses a unique database.

```yaml
# config/packages/doctrine.yaml
when@test:
    doctrine:
        dbal:
            dbname_suffix: '_test%env(default::TEST_TOKEN)%'
```

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

### Loading Fixtures at the Feature Level

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Apply the @withFixture tag to a feature to load fixtures for every scenario within that feature.

```gherkin
@withFixture(my-contacts)
Feature: Contacts management
  Scenario: List contacts
    Then 3 contacts should exist

  Scenario: Find john
    Then contact named "john" should exist
```

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

### Define Foundry Hooks as Services

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Use the #[AsFoundryHook] attribute to register methods as event listeners for specific classes or globally.

```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
    }

    #[AsFoundryHook]
    public function afterInstantiateGlobal(AfterInstantiate $event): void
    {
        // Omitting class defines a "global" hook which will be called for all objects
    }
}
```

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

### Register hook with specific priority

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Use a priority lower than PersistentObjectFactory::PRIORITY_SCHEDULE_FOR_INSERT to observe state computed by Doctrine lifecycle listeners.

```php
use Zenstruck\Foundry\Persistence\PersistentObjectFactory;

PostFactory::new()
    ->afterInstantiate(function(Post $post): void {
        // the "pre persist" events of the whole object graph have been triggered:
        // any state they computed is visible here
    }, priority: PersistentObjectFactory::PRIORITY_SCHEDULE_FOR_INSERT - 1)
;
```

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

### Configure In-memory Testing

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Use the #[AsInMemoryTest] attribute on test classes to disable persistence and enable in-memory repository hooks.

```php
use Zenstruck\Foundry\InMemory\AsInMemoryTest;

#[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());

        // The following assertion is also true, `YourFactory::repository()` returns a special "in-memory" repository
        // no request to the database will be made.
        self::assertSame(1, AddressFactory::repository()->count(1));

        // You can even use `YourFactory::repository()->assert()`
        AddressFactory::repository()->assert()->count(1);
    }

    protected static function getKernelClass(): string
    {
        // This is one of the ways to use the "in-memory" repositories in a "kernel test":
        // the "InMemoryKernel" would use "in-memory" repositories instead of the main ones.
        return InMemoryKernel::class;
    }
}
```

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

### Create a custom Behat context

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Define a custom context class that uses Foundry traits and overrides specific methods to change step wording or implementation.

```php
// tests/Behat/CustomFoundryContext.php
namespace App\Tests\Behat;

use Behat\Step\Given;
use Zenstruck\Foundry\Test\Behat\AssertionSteps;
use Zenstruck\Foundry\Test\Behat\CreationSteps;
use Zenstruck\Foundry\Test\Behat\FoundryContextInterface;
use Zenstruck\Foundry\Test\Behat\PlaceholderTransforms;

final class CustomFoundryContext implements FoundryContextInterface
{
    use AssertionSteps;
    use CreationSteps {
        createObject as private builtinCreateObject;
    }
    use PlaceholderTransforms;

    #[Given('create a :factoryShortName called :objectName')]
    public function createObject(string $factoryShortName, ?string $objectName = null): void
    {
        $this->builtinCreateObject($factoryShortName, $objectName);
    }
}
```

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

### Pre-Encode Passwords in Factories

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Use pre-encoded password hashes in your factories to avoid the overhead of hashing passwords during every test execution.

```php
class UserFactory extends PersistentObjectFactory
{
    public const DEFAULT_PASSWORD = '1234'; // the password used to create the pre-encoded version below

    protected function defaults(): array
    {
        return [
            // ...
            'password' => '$argon2id$v=19$m=65536,t=4,p=1$pLFF3D2gnvDmxMuuqH4BrA$3vKfv0cw+6EaNspq9btVAYc+jCOqrmWRstInB2fRPeQ',
        ];
    }
}
```

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

### Load a Story

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Invoke the load method to apply the defined story state. Subsequent calls do nothing if the story is already loaded.

```php
PostStory::load(); // loads the state defined in PostStory::build()

PostStory::load(); // does nothing - already loaded
```

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

### Marking a Story as a Fixture

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Use the #[AsFixture] attribute on a Story class to register it for use in Behat scenarios.

```php
use Zenstruck\Foundry\Attribute\AsFixture;
use Zenstruck\Foundry\Story;

#[AsFixture(name: 'my-contacts')]
final class ContactsStory extends Story
{
    public function build(): void
    {
        $this->addState('john', ContactFactory::createOne(['name' => 'John']));
        $this->addState('jane', ContactFactory::createOne(['name' => 'Jane']));
        $this->addState('bob', ContactFactory::createOne(['name' => 'Bob']));
    }
}
```

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

### Pass factory instances in data providers

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

When not using the PHPUnit extension, pass factory instances to the test method and call create() inside the test.

```php
use App\Factory\PostFactory;

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

    // ...
}

public static function postDataProvider(): iterable
{
    yield [PostFactory::new()];
    yield [PostFactory::new()->published()];
}
```

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

### Configure Test Factory Services

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Register factories located in the tests directory as services in the dev environment.

```yaml
# config/packages/zenstruck_foundry.yaml
when@dev:
    services:
        App\Tests\Factory\:
            resource: '%kernel.project_dir%/tests/Factory/'
            autowire: true
            autoconfigure: true
```

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

### Defining Relationship Defaults

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Recommended patterns for defining relationships within the factory defaults method 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(),
    ];
}
```

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

### Overriding Factory Attributes

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Demonstrates using new(), with(), and many() to customize object creation and handle related entities.

```php
use App\\\Entity\\\Category;
use App\\\Entity\\\Post;
use App\\\Factory\\\CategoryFactory;
use App\\\Factory\\\PostFactory;
use function Zenstruck\\\Foundry\\\faker;

// The first argument to "new()" allows you to overwrite the default
// values that are defined in the `PostFactory::defaults()`
$posts = PostFactory::new(['title' => 'Post A'])
    ->with([
        'body' => 'Post Body...',

        // CategoryFactory will be used to create a new Category for each Post
        'category' => CategoryFactory::new(['name' => 'php']),
    ])
    ->with([
        // Proxies are automatically converted to their wrapped object
        // will override previous category
        'category' => CategoryFactory::createOne(['name' => 'Symfony']),
    ])
    ->with(function() { return ['createdAt' => faker()->dateTime()]; }) // see faker section below

    // create "2" Post's
    ->many(2)->create(['title' => 'Different Title'])
;

$posts[0]->getTitle(); // "Different Title"
$posts[0]->getBody(); // "Post Body..."
$posts[0]->getCategory(); // Category with name "Symfony"
$posts[0]->getPublishedAt(); // \DateTime('last week')
$posts[0]->getCreatedAt(); // random \DateTime

$posts[1]->getTitle(); // "Different Title"
$posts[1]->getBody(); // "Post Body..."
$posts[1]->getCategory(); // Category with name "Symfony" (same object than above)
$posts[1]->getPublishedAt(); // \DateTime('last week')
$posts[1]->getCreatedAt(); // random \DateTime (different than above)
```

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

### Disable Factory Hints

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Disable the generation of beginner hints in factory classes.

```yaml
# config/packages/zenstruck_foundry.yaml
zenstruck_foundry:
    make_factory:
        add_hints: false
```

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

### Fetching Objects from Pools

Source: https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html

Retrieve objects from defined pools using static methods on the Story class.

```php
ProvinceStory::getRandom('be'); // random Province from "be" pool
ProvinceStory::getRandomSet('be', 3); // 3 random Province from "be" pool
ProvinceStory::getRandomRange('be', 1, 4); // between 1 and 4 random Province from "be" pool
ProvinceStory::getPool('be'); // all Province from "be" pool
```
Tokens:
Raw