README

The goal of this package is to enable the rapid creation of objects for the purpose of testing.

It's basically a "factory_girl", simplified for use with PHP.

Installing

PHP 5.4+ and Composer are required.

In your composer.json, simply add "league/factory-muffin": "^3.3" to your "require-dev" section:

{
    "require-dev": {
        "league/factory-muffin": "^3.3"
    }
}

Faker support is provided by Factory Muffin Faker. If you want to enable faker support, then you need to add "league/factory-muffin-faker": "^2.3" too:

{
    "require-dev": {
        "league/factory-muffin": "^3.3",
        "league/factory-muffin-faker": "^2.3"
    }
}

Upgrading

It maybe be useful for existing users to check out the upgrade guide.

Usage

Introduction

This is the usage guide for Factory Muffin 3.0. Within this guide, you will see "the xyz function can be called". You should assume that these functions should be called on an instance of League\FactoryMuffin\FactoryMuffin; you should keep track of this instance yourself, and you can of course have multiple instances of this class for maximum flexibility. For simplicities sake, many of our examples include a $fm variable. This variable will actually be made available when files are required using the loadFactories function.

Model Definitions

You can define model factories using the define function. You may call it like this: $fm->define('Fully\Qualifed\ModelName')->addDefinitions('foo', 'bar'), where foo is the name of the attribute you want set on your model, and bar describes how you wish to generate the attribute. You may also define multiple attributes at once like this: $fm->define('Fully\Qualifed\ModelName')->setDefinitions('foo', 'bar'). Note that both functions append to the internal attributes definition array rather than replacing it. Please see the generators section for more information on how this works.

You can also define multiple different model definitions for your models. You can do this by prefixing the model class name with your "group" followed by a colon. This results in you defining your model like this: $fm->define('myGroup:Fully\Qualifed\ModelName')->addDefinitions('bar', 'baz'). You don't have to entirely define your model here because we will first look for a definition without the group prefix, then apply your group definition on top of that definition, overriding attribute definitions where required. Note that if you want to use group prefixes, you must also create a definition without the group prefix as well.

We have provided a nifty way for you to do this in your tests. PHPUnit provides a setupBeforeClass function. Within that function you can call $fm->loadFactories(__DIR__ . '/factories');, and it will include all files in the factories folder. Within those PHP files, you can put your definitions (all your code that calls the define function).

The loadFactories function will recurse through all sub-folders of the path you specify when searching for factory files, except for hidden folders (i.e. starting with a .) which will be ignored. It will also throw a League\FactoryMuffin\Exceptions\DirectoryNotFoundException exception if the factories directory you specify is not found.

Creation/Instantiation Callbacks

You may optionally specify a callback to be executed on model creation/instantiation using the setCallback function, like this: $fm->define('MyModel')->setCallback(function ($object, $saved) {}). We will pass your model instance as the first parameter to the callback and a boolean as the second parameter. The boolean will be true if the model is being persisted to the database (the create function was used), and false if it's not being persisted (the instance function was used). We're using the isPendingOrSaved function under the hood here. Note that if you specify a callback and use the create function, we will try to save your model to the database both before and after we execute the callback.

Generators

Callable

The callable generator can be used if you want a more custom solution. Whatever you return from your closure, or valid callable, will be set as the attribute. The closure/callable will be called with the same parameters as creation/instantiation callbacks described above: an instance of your model as the first parameter (to give you even more flexibility to modify it as you wish) and a boolean indicating if the model is being persisted to the database. In the following examples, we will go through using a closure, or callable, and then how to use faker to generate attributes.

Example 1

As you can see from this example, the ability to use a closure to generate attributes can be so useful and flexible. Here we use it to generate a slug based on the initially randomly generated 5 word long title.

$fm->define('MyModel')->setDefinitions([
    'title' => Faker::sentence(5),
    'slug' => function ($object, $saved) {
        $slug = preg_replace("/[^a-zA-Z0-9\/_|+ -]/", '', $object->title);
        $slug = strtolower(trim($slug, '-'));
        $slug = preg_replace("/[\/_|+ -]+/", '-', $slug);

        return $slug;
    },
]);

Example 2

This will set the foo attribute to whatever calling MyModel::exampleMethod($object, $saved) returns.

$fm->define('MyModel')->setDefinitions([
    'foo' => 'MyModel::exampleMethod',
]);

Example 3

There is a simple example of setting a few different attributes using our faker wrapper.

use League\FactoryMuffin\Faker\Facade as Faker;

$fm->define('MyModel')->setDefinitions([
    'foo'    => Faker::word(),          // Set the foo attribute to a random word
    'name'   => Faker::firstNameMale(), // Set the name attribute to a random male first name
    'email'  => Faker::email(),         // Set the email attribute to a random email address
    'body'   => Faker::text(),          // Set the body attribute to a random string of text
    'slogan' => Faker::sentence(),      // Set the slogan attribute to a random sentence
]);

Example 4

This will set the age attribute to a random number between 20 and 40.

use League\FactoryMuffin\Faker\Facade as Faker;

$fm->define('MyModel')->setDefinitions([
    'age' => Faker::numberBetween(20, 40),
]);

Example 5

This will set the name attribute to a random female first name. Because we've called the unique method first, the attribute should be unique between all your generated models. Be careful with this if you're generating lots models because we might run out of unique items. Also, note that calling Faker::setLocale('whatever') will reset the internal unique list.

use League\FactoryMuffin\Faker\Facade as Faker;

$fm->define('MyModel')->addDefinition('name', Faker::unique()->firstNameFemale());

Example 6

This will set the profile_pic attribute to a random image url of dimensions 400 by 400. Because we've called the optional method first, not all the generated models will have an image url set; sometimes we will return null.

use League\FactoryMuffin\Faker\Facade as Faker;

$fm->define('MyModel')->addDefinition('profile_pic', Faker::optional()->imageUrl(400, 400));

More

Check out the faker library itself to see all the available methods. There are far too many to cover in the documentation here, and far too many for them to cover in their documentation too. Note that you can fiddle with the underlying faker instance through the public methods on our faker class if you want.

Factory

The factory generator can be useful for setting up relationships between models. The factory generator will return the model id of the model you ask it to generate.

Example 1

When we create a Foo object, we will find that the Bar object will been generated and saved too, and it's id will be assigned to the bar_id attribute of the Foo model.

$fm->define('Foo')->addDefinition('bar_id', 'factory|Bar');

$fm->define('Bar')->addDefinition('baz', Faker::date('Y-m-d'));

Creating And Seeding

The create function will create and save your model, and will also save anything you generate with the Factory generator too. If you want to create multiple instances, check out the seed seed function, which accepts an additional argument at the start which is the number of models to generate in the process. The seed function will effectively be calling the create function over and over.

For example, let's create a user model and associate multiple location and email models to each one. Each email will also have multiple token models.

$user = $fm->create('User');
$profiles = $fm->seed(5, 'Location', ['user_id' => $user->id]);
$emails = $fm->seed(100, 'Email', ['user_id' => $user->id]);

foreach ($emails as $email) {
    $tokens = $fm->seed(50, 'Token', ['email_id' => $email->id]);
}

You may encounter the following exceptions:

• League\FactoryMuffin\Exceptions\ModelNotFoundException will be thrown if the model class defined is not found.
• League\FactoryMuffin\Exceptions\DefinitionNotFoundException will be thrown if you try to create a model and you haven't defined a model definition for it earlier.
• League\FactoryMuffin\Exceptions\SaveFailedException will be thrown if the save function on your model returns false.
• League\FactoryMuffin\Exceptions\SaveMethodNotFoundException will be thrown if the save function on your model does not exist.
• Any other exception thrown by your model while trying to create or save it.

There are 5 other helper functions available:

• You may call pending to return an array of all the objects waiting to be saved.
• You may call isPending with an instance of a model to check if will be saved.
• You may call saved to return an array of all the saved objects.
• You may call isSaved with an instance of a model to check if it's saved.
• You may call isPendingOrSaved with an instance of a model to check if it will be saved, or is already saved.

Also, a reminder that the instance function is still available if you don't want database persistence.

Deleting

You can delete all your saved models with the deleteSaved function. Please note that your saved models will be deleted in the reverse order they were saved to ensure relationships behave correctly.

If one or more models cannot be deleted, a League\FactoryMuffin\Exceptions\DeletingFailedException will be raised after we have attempted to delete all the saved models. You may access each underlying exception, in the order they were thrown during the whole process, with the getExceptions function which will return an array of exceptions. You may encounter the following exceptions:

• League\FactoryMuffin\Exceptions\DeleteFailedException will be thrown if the delete function on your model returns false.
• League\FactoryMuffin\Exceptions\DeleteMethodNotFoundException will be thrown if the delete function on your model does not exist.
• Any other exception thrown by your model while trying to delete it.

It's recommended that you call the deleteSaved function from PHPUnit's tearDownAfterClass function, however, if you are writing tests using Laravel's TestCase, you should call the deleteSaved function from the tearDown method before calling parent::tearDown. This method flushes the application instance's bindings and Factory Muffin would not unable to execute its deletes. Further more, this unbinds the assigned exception handler and you will not be able to troubleshoot your tests due to binding resolution exceptions obfuscating the true exceptions.

Real Examples

To start with, we need to create some definitions:

# tests/factories/all.php

use League\FactoryMuffin\Faker\Facade as Faker;

$fm->define('Message')->setDefinitions([
    'user_id'      => 'factory|User',
    'subject'      => Faker::sentence(),
    'message'      => Faker::text(),
    'phone_number' => Faker::randomNumber(8),
    'created'      => Faker::date('Ymd h:s'),
    'slug'         => 'Message::makeSlug',
])->setCallback(function ($object, $saved) {
    // we're taking advantage of the callback functionality here
    $object->message .= '!';
});

$fm->define('User')->setDefinitions([
    'username' => Faker::firstNameMale(),
    'email'    => Faker::email(),
    'avatar'   => Faker::imageUrl(400, 600),
    'greeting' => 'RandomGreeting::get',
    'four'     => function() {
        return 2 + 2;
    },
]);

You can then use these factories in your tests:

# tests/TestUserModel.php

use League\FactoryMuffin\Faker\Facade as Faker;

class TestUserModel extends PHPUnit_Framework_TestCase
{
    protected static $fm;

    public static function setupBeforeClass()
    {
        // create a new factory muffin instance
        static::$fm = new FactoryMuffin();

        // you can customize the save/delete methods
        // new FactoryMuffin(new ModelStore('save', 'delete'));

        // load your model definitions
        static::$fm->loadFactories(__DIR__.'/factories');

        // you can optionally set the faker locale
        Faker::setLocale('en_EN');
    }

    public function testSampleFactory()
    {
        $message = static::$fm->create('Message');
        $this->assertInstanceOf('Message', $message);
        $this->assertInstanceOf('User', $message->user);
    }

    public static function tearDownAfterClass()
    {
        static::$fm->deleteSaved();
    }
}

Further Information

If you want more information, the following resources are available to you:

• Generated api docs are available here.
• Philip Brown's article is available here.
• Our test suite may also be useful to you.

Integrations

• CakePHP 3
• Yii 2

Contributing

Please check out our contribution guidelines for details.

Credits

Factory Muffin is based on Zizaco Zizuini's original work on "Factory Muff", and is currently maintained by Graham Campbell. Scott Robertson was also a co-maintainer before the 3.0 release. Thank you to all our wonderful contributors too.

Security

If you discover a security vulnerability within this package, please send an email to Graham Campbell at graham@alt-three.com. All security vulnerabilities will be promptly addressed. You may view our full security policy here.

License

Factory Muffin is licensed under The MIT License (MIT).

For Enterprise

Available as part of the Tidelift Subscription

The maintainers of league/factory-muffin and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.