DataFactory.php

<?php
namespace Codeception\Module;

use Codeception\Lib\Interfaces\DataMapper;
use Codeception\Lib\Interfaces\DependsOnModule;
use Codeception\Lib\Interfaces\ORM;
use Codeception\Exception\ModuleException;
use Codeception\Lib\Interfaces\RequiresPackage;
use Codeception\TestInterface;
use League\FactoryMuffin\FactoryMuffin;
use League\FactoryMuffin\Stores\RepositoryStore;

/**
 * DataFactory allows you to easily generate and create test data using [**FactoryMuffin**](https://github.com/thephpleague/factory-muffin).
 * DataFactory uses an ORM of your application to define, save and cleanup data. Thus, should be used with ORM or Framework modules.
 *
 * This module requires packages installed:
 *
 * ```json
 * {
 *  "league/factory-muffin": "^3.0",
 * }
 * ```
 *
 * Generation rules can be defined in a factories file. You will need to create `factories.php` (it is recommended to store it in `_support` dir)
 * Follow [FactoryMuffin documentation](https://github.com/thephpleague/factory-muffin) to set valid rules.
 * Random data provided by [Faker](https://github.com/fzaninotto/Faker) library.
 *
 * ```php
 * <?php
 * use League\FactoryMuffin\Faker\Facade as Faker;
 *
 * $fm->define(User::class)->setDefinitions([
 *  'name'   => Faker::name(),
 *
 *     // generate email
 *    'email'  => Faker::email(),
 *    'body'   => Faker::text(),
 *
 *    // generate a profile and return its Id
 *    'profile_id' => 'factory|Profile'
 * ]);
 * ```
 *
 * Configure this module to load factory definitions from a directory.
 * You should also specify a module with an ORM as a dependency.
 *
 * ```yaml
 * modules:
 *     enabled:
 *         - Yii2:
 *             configFile: path/to/config.php
 *         - DataFactory:
 *             factories: tests/_support/factories
 *             depends: Yii2
 * ```
 *
 * (you can also use Laravel5 and Phalcon).
 *
 * In this example factories are loaded from `tests/_support/factories` directory. Please note that this directory is relative from the codeception.yml file (so for Yii2 it would be codeception/_support/factories).
 * You should create this directory manually and create PHP files in it with factories definitions following [official documentation](https://github.com/thephpleague/factory-muffin#usage).
 *
 * In cases you want to use data from database inside your factory definitions you can define them in Helper.
 * For instance, if you use Doctrine, this allows you to access `EntityManager` inside a definition.
 *
 * To proceed you should create Factories helper via `generate:helper` command and enable it:
 *
 * ```
 * modules:
 *     enabled:
 *         - DataFactory:
 *             depends: Doctrine2
 *         - \Helper\Factories
 *
 * ```
 *
 * In this case you can define factories from a Helper class with `_define` method.
 *
 * ```php
 * <?php
 * public function _beforeSuite()
 * {
 *      $factory = $this->getModule('DataFactory');
 *      // let us get EntityManager from Doctrine
 *      $em = $this->getModule('Doctrine2')->_getEntityManager();
 *
 *      $factory->_define(User::class, [
 *
 *          // generate random user name
 *          // use League\FactoryMuffin\Faker\Facade as Faker;
 *          'name' => Faker::name(),
 *
 *          // get real company from database
 *          'company' => $em->getRepository(Company::class)->find(),
 *
 *          // let's generate a profile for each created user
 *          // receive an entity and set it via `setProfile` method
 *          // UserProfile factory should be defined as well
 *          'profile' => 'entity|'.UserProfile::class
 *      ]);
 * }
 * ```
 *
 * Factory Definitions are described in official [Factory Muffin Documentation](https://github.com/thephpleague/factory-muffin)
 *
 * ### Related Models Generators
 *
 * If your module relies on other model you can generate them both.
 * To create a related module you can use either `factory` or `entity` prefix, depending on ORM you use.
 *
 * In case your ORM expects an Id of a related record (Eloquent) to be set use `factory` prefix:
 *
 * ```php
 * 'user_id' => 'factory|User'
 * ```
 *
 * In case your ORM expects a related record itself (Doctrine) then you should use `entity` prefix:
 *
 * ```php
 * 'user' => 'entity|User'
 * ```
 */
class DataFactory extends \Codeception\Module implements DependsOnModule, RequiresPackage
{
    protected $dependencyMessage = <<<EOF
ORM module (like Doctrine2) or Framework module with ActiveRecord support is required:
--
modules:
    enabled:
        - DataFactory:
            depends: Doctrine2
--
EOF;

    /**
     * ORM module on which we we depend on.
     *
     * @var ORM
     */
    public $ormModule;

    /**
     * @var FactoryMuffin
     */
    public $factoryMuffin;

    protected $config = ['factories' => null];

    public function _requires()
    {
        return [
            'League\FactoryMuffin\FactoryMuffin' => '"league/factory-muffin": "^3.0"',
        ];
    }

    public function _beforeSuite($settings = [])
    {
        $store = $this->getStore();
        $this->factoryMuffin = new FactoryMuffin($store);

        if ($this->config['factories']) {
            foreach ((array) $this->config['factories'] as $factoryPath) {
                $realpath = realpath(codecept_root_dir().$factoryPath);
                if ($realpath === false) {
                    throw new ModuleException($this, 'The path to one of your factories is not correct. Please specify the directory relative to the codeception.yml file (ie. _support/factories).');
                }
                $this->factoryMuffin->loadFactories($realpath);
            }
        }
    }
    
    /**
     * @return StoreInterface|null
     */
    protected function getStore()
    {
        return $this->ormModule instanceof DataMapper
            ? new RepositoryStore($this->ormModule->_getEntityManager()) // for Doctrine
            : null;
    }

    public function _inject(ORM $orm)
    {
        $this->ormModule = $orm;
    }

    public function _after(TestInterface $test)
    {
        $skipCleanup = array_key_exists('cleanup', $this->config) && $this->config['cleanup'] === false;
        if ($skipCleanup || $this->ormModule->_getConfig('cleanup')) {
            return;
        }
        $this->factoryMuffin->deleteSaved();
    }

    public function _depends()
    {
        return ['Codeception\Lib\Interfaces\ORM' => $this->dependencyMessage];
    }

    /**
     * Creates a model definition. This can be used from a helper:.
     *
     * ```php
     * $this->getModule('{{MODULE_NAME}}')->_define('User', [
     *     'name' => $faker->name,
     *     'email' => $faker->email
     * ]);
     *
     * ```
     *
     * @param string $model
     * @param array $fields
     *
     * @return \League\FactoryMuffin\Definition
     *
     * @throws \League\FactoryMuffin\Exceptions\DefinitionAlreadyDefinedException
     */
    public function _define($model, $fields)
    {
        return $this->factoryMuffin->define($model)->setDefinitions($fields);
    }

    /**
     * Generates and saves a record,.
     *
     * ```php
     * $I->have('User'); // creates user
     * $I->have('User', ['is_active' => true]); // creates active user
     * ```
     *
     * Returns an instance of created user.
     *
     * @param string $name
     * @param array $extraAttrs
     *
     * @return object
     */
    public function have($name, array $extraAttrs = [])
    {
        return $this->factoryMuffin->create($name, $extraAttrs);
    }

    /**
     * Generates a record instance.
     *
     * This does not save it in the database. Use `have` for that.
     *
     * ```php
     * $user = $I->make('User'); // return User instance
     * $activeUser = $I->make('User', ['is_active' => true]); // return active user instance
     * ```
     *
     * Returns an instance of created user without creating a record in database.
     *
     * @param string $name
     * @param array $extraAttrs
     *
     * @return object
     */
    public function make($name, array $extraAttrs = [])
    {
        return $this->factoryMuffin->instance($name, $extraAttrs);
    }

    /**
     * Generates and saves a record multiple times.
     *
     * ```php
     * $I->haveMultiple('User', 10); // create 10 users
     * $I->haveMultiple('User', 10, ['is_active' => true]); // create 10 active users
     * ```
     *
     * @param string $name
     * @param int $times
     * @param array $extraAttrs
     *
     * @return \object[]
     */
    public function haveMultiple($name, $times, array $extraAttrs = [])
    {
        return $this->factoryMuffin->seed($times, $name, $extraAttrs);
    }
}