Download the PHP package lukeraymonddowning/poser without Composer

Poser

Laravel Class-based Model Factories in literal seconds! Write tests that look as sexy as this...

...with a Factory that looks like this...

Note for Laravel 8 users

Whilst Poser is tagged for Laravel 8, you should start migrating to use Laravel's new built in class based factories. The syntax is nearly identical and you'll pick it up in no time. I want to thank everybody who used, tested, altered and discussed Poser. Its been so much fun to build something to the Laravel community!

Examples

Want to see what Poser looks like compared with the default Laravel tests? Check out our examples!

Install

First, install into your Laravel project using composer.

composer require lukeraymonddowning/poser

Next, publish the Poser config file by calling

php artisan vendor:publish --tag=poser

Lumen Installation

Create the poser.php in your config directory and copy the lukeraymonddowning/poser/src/config/poser.php into it

Add $app->configure('poser'); to the config section in boostrap/app.php

Add $app->register(\Lukeraymonddowning\Poser\PoserServiceProvider::class); to the providers section in boostrap/app.php

Getting Started

To get started quickly, we provide a php artisan make:poser command. You may pass the desired name of your factory as an argument. So the command to create the UserFactory would be php artisan make:poser UserFactory.

If you want to let Poser do all of the work, simply call php artisan make:poser to turn all the models defined in your poser.models_namespace config entry into Poser Factories.

More of a visual person? Watch this video demonstration of Poser

Usage

Poser takes all of the boilerplate out of writing class-based model factories. To get started, install Poser and go to your test suite. Please note: Poser uses the database (obviously), so make sure your test class extends Laravel's TestCase, not PhpUnit's.

The Basics

Let's imagine you have a user model that has many customers...

To set up the factory for this, create a class (we suggest a 'Factories' directory in your 'tests' folder) called UserFactory (you can also just call it User, but we think the Factory suffix helps), and a class called CustomerFactory.

Both of these classes should extend the Poser/Factory abstract class. Poser can take care of this for you via the make:poser command, so you can call php artisan make:poser UserFactory and php artisan make:poser CustomerFactory.

You should also have CustomerFactory and UserFactory as entries in your database/factories directory (standard Laravel stuff)

Now, head to the test you want to write, and type the following:

The test should pass with flying colors. Hurrah! Notice that we didn't have to implement the withCustomers() method: Poser was able to intelligently decide what we were trying to do.

For HasOne or HasMany relationships, you can simply prepend with to the relationship method in the model (eg: the customers() method in the User model becomes withCustomers in the tests), and Poser will do the rest.

Let's add a little more complexity: each customer can own many books...

So far, so good. Let's create another factory class, this time called BookFactory, that again extends Poser's abstract Factory class. That's all there is to it! Modify your original test to give our customers 5 books each...

...and watch the tests pass. Pretty nice, huh?

Magic Bindings

If your model relationship method name (ie: the customers() method on our User model) is the same or a plural version of our Factory class (ie: CustomerFactory), then we can take advantage of Magic Bindings in Poser.

Let's take another look at our User/Customer example.

Poser is smart enough to be able to work out that withCustomers() is a reference to the CustomerFactory, and allows us to rewrite our test like this:

The first argument passed to withCustomers() is the number of customers we want to create, in this case: 30.

Imagine, for a contrived example, that every customer should be called "Joe Bloggs". We can pass a second argument to withCustomers() that defines an associative array of column names and values, just like we do with the create(), make() and withAttributes() methods:

To take this a step further, imagine that we want 10 of our customers to be called "Joe Bloggs", 10 to be called "Jane Bloggs" and 10 to be called "John Doe". Poser allows multiple attribute arrays to be passed to the withAttributes, make and create methods, along with any method using magic bindings, to facilitate this:

For HasOne relationships, like our User's Address, we can do very much the same:

We can also pass an array of attributes, but in this case we pass it as the first argument:

Sometimes, with[RelationshipMethodName] might not be the most readable choice. Poser also supports the has[RelationshipMethodName] syntax, like so:

In most cases, we don't even need to call create, Poser will call it for us when we try to access a method or property on the model or collection we have built (in this case, the $user property).

Let's now put this all together, and demonstrate how simple it is to world build in Poser. Imagine we want 10 Users, each with an Address and 20 customers. Each customer should have 5 books. That should be 10 Users, 10 Addresses, 200 Customers and 1000 Books. Check it out:

Let's break down this code. First, we ask the UserFactory to create 10 users, and pass it the hasAddress() function. Poser is able to find the AddressFactory, so it automatically instantiates it for us and gives each user an Address.

Next, we call withCustomers(). Because we want to specify additional parameters for each Customer, we instantiate CustomerFactory directly, asking for 20 at a time. We then chain withBooks() onto the CustomerFactory, simply passing the integer 5. Poser looks for a BookFactory, which it finds, and automatically calls BookFactory::times(5) under the hood.

Finally, we complete the statement by invoking the UserFactory with (). This is a shorthand syntax for calling create() on the UserFactory. Because in these tests we are accessing the models indirectly (we request the models from the database in the assertions rather than accessing a property or method on the users), we must invoke the create or () method.

For reference, the same test using Laravel's built in factories looks like this:

Belongs To Many Relationships

Poser supports Many-to-Many relationships using the exact same with[RelationshipMethodName]() or has[RelationshipMethodName]() syntax you're now used to. Let's take the commonly used example of a User that can have many Roles, and a Role that can have many Users.

Poser also allows you to save data to your pivot table when handing Many-to-Many relationships using the withPivotAttributes() method:

For instances where you would like to save different pivot data on each related model, withPivotAttributes() accepts multiple attribute sets:

It is important to note that you should not use the make(), create() or invoke() methods on the relationship factory when adding pivot attributes, as Poser will have no way to access them when saving the models.

Polymorphic Relationships

Poser supports all polymorphic relationship types using the same with[RelationshipMethodName]() or has[RelationshipMethodName]() syntax you're now very used to. Imagine that both our User and Customer models can have Comments. Your Poser tests might look something like this:

Many to Many polymorphic relationships work in exactly the same way.

Belongs To Relationships

What if we want to create a BelongsTo relationship? Poser makes this easy too. Instead of prepending with, we can prepend for. Let's take another look at our examples. Say we wanted to request that a customer is given a user. Simply do this:

No need to call create on the UserFactory either; Poser will do that for you!

Static Instantiation

If you only want a single instance of a model, you don't necessarily have to use the ::new() method. When called statically, Poser will build a factory instance and handle your relationship methods for you. So instead of writing UserFactory::new()->withCustomers(5)->create(), we could instead write UserFactory::withCustomers(5)->create().

Note that static resolution only works with dynamic methods, not methods that you define in your factory or methods built into the Poser class. So UserFactory::withoutEvents()->create() would not work.

Factory States

If you have setup any States in your laravel factories, then you can also use them with Poser. So if in your Laravel customer factory class you have the following states setup

Then you can use the state method to tell Poser to also use these factory states

You may alternatively use the as method, which calls the state method under the hood

Like Laravel's Factories, there is also a states method to allow you to use multiple states

As Poser makes use of the built in Laravel factory methods, you can use the afterMaking(), afterCreating(), afterMakingState() and afterCreatingState() callbacks in your Laravel database factories as you always have done, and they will be called as you would expect.

After Creating

Similar to Laravel's model factories, Poser also offers an afterCreating() method that will accept a closure to run after the record(s) have been created.

Example:

• User belongs to a company
• Company has a single Main user (stored on company record)
  • setMainUser on Company is a function to just update the main_user_id column on Company

So after the Company has been created, it will create a new user for that company, and set it as the main user for the company.

This will also work when using times() to create multiple companies, and it will create a new user for each created company

Logic like this is likely to be commonly used, and this is where Poser being classed based helps, as you can store this logic behind a function on the CompanyFactory class, as such:

Allowing you to then just call withMainUser()

The afterCreating() method also works on nested relationships:

Note that nested relationships are also given the parent model, in this case the User that was created, as the second argument of the closure.

Factory API

::new()

Creates a new instance of the factory. If you only want to create one model, use this to instantiate the class.

If you're going to call a dynamic relationship method directly after this call, you can remove this call entirely and instead call the relationship method statically, like so: UserFactory::withCustomers(5)->create().

::times($count)

Creates a new instance of the factory, but informs the factory that you will be creating multiple models. Use this to instantiate the class when you wish to create multiple entries in the database.

::craft(int $count, ...$attributes)

Allows you to create multiple models, persist them to the database, and return the resulting collection, all in one method call. A very useful shortcut when you don't need complex relationship mapping. You may pass in the count of models you wish to create, along with attributes that should be given to those models.

::craft(...$attributes, int $count)

Alternate syntax for craft as described above, which more closely matches factory method baked into Laravel.

::craft(array $attributes = null)

If you only need to craft one model, you can omit the count. It will return a single model instead of a collection.

->create(...$attributes) or (...$attributes)

Similar to the Laravel factory create command, this will create the models, persisting them to the database. You may pass an associative array of column names with desired values, which will be applied to the created models. You can optionally call create by invoking the Factory. This allows for a shorter syntax.

If you're interacting with the models directly in your tests, rather than re-fetching them from the database, you can omit the create call completely. Poser will automatically call the create method for you when you try to access a property or call a method on the model(s)/collection.

If you would like to apply different attributes to each model that will be created, you may pass as many attribute arrays as separate parameters as desired.

->make(...$attributes)

Similar to the Laravel factory make command, this will make the models without persisting them to the database. You may pass an associative array of column names with desired values, which will be applied to the created models.

If you would like to apply different attributes to each model that will be created, you may pass as many attribute arrays as separate parameters as desired.

->withAttributes(...$attributes)

You may pass an associative array of column names with desired values, which will be applied to the created models.

If you would like to apply different attributes to each model that will be created, you may pass as many attribute arrays as separate parameters as desired.

->state(string $state) or ->as(string $state)

You may pass a factory state that you have defined in your laravel model factory, which will be applied to the created models.

->states(...$states)

Similar to ->state(string $state), but allows you to pass in multiple states that will all be applied to the created models.

->withPivotAttributes(...$attributes)

When working with Many-to-Many relationships, you may want to store data on the pivot table. You may use this method to do so, passing in an associative array of column names with desired values. This should be called on the related factory, not the root-level factory.

If you would like to apply different pivot attributes to each model that will be created, you may pass as many attribute arrays as separate parameters as desired.

->afterCreating(Closure $closure)

Allows you to provide a hook that will be called when the given factory has created its model(s). This allows you to perform additional setup to created models. It can be placed on relationships as well as the parent model.

The closure will be provided with the created model as the first parameter. If afterCreating() is called on a relationship, it will also be given the parent model as the second parameter.

->withoutDefaults(...$defaultsToIgnore)

If you would like to ignore certain Poser defaults for a given test, you may chain this method onto your Poser Factory call. If you would like to ignore all defaults, simply call this method with no parameters.

$usersWithoutDefaultCustomers = UserFactory::new()->withoutDefaults('customers')->create();

->withoutEvents()

At times, it is useful to disable events when a model is being created to avoid unwanted side-effects in your tests. You may append this method to a Poser Factory call to ensure that no events will be fired during model creation.

php artisan make:poser API

If no arguments are passed to the command, Poser will attempt to create matching factories for every model in your application. It does this by looking at your poser.models_namespace config entry, and scanning for models in that given namespace. You may call make:poser multiple times without fear of it overriding your existing factories; if it finds that a given factory already exists, it will simply skip over it.

Individual Factories

You may optionally pass a name to the command, which corresponds to the name of the factory you want to create. For instance, php artisan make:poser UserFactory would create a factory called UserFactory in the namespace defined in your poser.factories_namespace config file.

The -m or --model Flag

If your model name is different to the name you wish to give your factory, you may pass a -m or --model flag, along with the name of the model that the factory will correspond to. So php artisan make:poser ClientFactory -m Customer would create a factory called ClientFactory, but point it to the Customer model.

The -f or --factory Flag

You may pass -f or --factory to the command to optionally generate a corresponding Laravel database factory. The database factory will take the form [modelName]Factory.

Things to note

Models location

By default, Poser looks for your models in the App directory, which should be fine for most projects. If you have your models in a different directory, you can let Poser know about it by editing the models_namespace entry in the poser.php config file.

If you need to override the model location for a single instance, you can override the $modelName static variable in your Factory class, passing it the fully qualified class name of the corresponding model.

Factories location

By default, Poser will search the Tests/Factories directory for your Factory classes. If you have your Factories in a different directory (eg: Tests/Models/Factories), you can let Poser know about it by editing the factories_namespace entry in the poser.php config file.

Nested Models

What if you have a model located in a subfolder? For example: app/Models/Customers/Customer.php. You can generate the factory for this by copying the namespace of the model: php artisan make:poser Models\\Customers\\CustomerFactory. Note that the namespace should be relative to your models_namespace entry in the poser.php config file.

The ->create() and ->make() commands

You should call the create command at the end of the outermost Factory statement to cause it to persist to the database. You do not need to call create() or make() on nested Factory statements, as Poser will do this for you.

The only exception to this is BelongsTo relationships, in which case you must call create() on nested Factory statements.

If you like terse syntax, you can replace ->create() with (), as the Factory __invoke function simply calls create() under the hood:

Multiple attributes

Often, it is useful to be able to provide multiple attributes when dealing with multiple models. Poser is smart about this and allows you to do some very powerful world-building with 0 effort. Imagine we want to create 3 users all with different names. No problem:

You can do this with the create, make, withAttributes and magic bindings such as withCustomers. The latter would look like this:

If you provide fewer attribute sets than models, Poser will loop through the attribute sets for you. So in the following example...

...Poser will create 5 users called Joe and 5 users called Jane.

Default Relationships

After using Poser for a while, you may wish to provide default relationships that should be applied every time we create a model. For example, in our examples, a Customer requires a related User model. To facilitate this, Poser understands a default[RelationshipType][RelationshipMethodName] syntax inside Poser Factories. To illustrate:

Now, every time we call...

...a User called Joe Bloggs will be automatically assigned to the customer. However, if we call...

...the default will be ignored and instead a User called "John Doe" will be assigned to the Customer.

For with/has relationship types, the case is much the same:

In this case, when we call UserFactory::new()->create(), it will be given an Address and 10 Customers.

If we would like to ignore your defaults for a given test, simply chain the withoutDefaults method to your Factory. call.

This will create a User with no Address or Customers. If you would only like to ignore certain defaults, you may pass them as properties to the withoutDefaults method.

Now, our created User will have no Customers but will have a default Address.

Inline Tests

Often, you'll find yourself writing short tests that check certain properties on a model can be successfully persisted to the database, or that the expected number of models are related to a parent model.

Poser provides you with a super simple syntax for checking all of this. All it requires is that you use PhpUnit for testing (which is the default testing library in Laravel).

Simply call a PhpUnit assertion as a chained method of the Factory anywhere before the create function, and watch the magic happen.

Let's imagine that we want to check that a User has 5 customers attached. Using inline tests, we could write this test like so:

With just one line, we are able to assert that the count of the customers property on the created User model is 5. Here is another example:

Of course, sometimes you'll need more power. To facilitate this, Poser allows you to pass a closure as the second argument of all assertion methods:

If you're working with multiple models, your method will be passed the Collection, like so:

If you wish to perform an assertion on each model in the Collection, you may type hint the closure parameter with relevant model type. Poser will iterate over the models for you and run the assertion:

Whilst we do not recommend using inline tests for complex use cases, it works perfectly for simple tests, or tests where the main assertion is on the model itself.

Troubleshooting

When using magic binding, I get an ArgumentsNotSatisfiableException

This error is thrown when Poser cannot find a factory that satifies the requested relationship method call. So, imagine you called UserFactory::new()->withCustomers(10)();, but there was no CustomerFactory, Poser would throw this error. The solution is to create the Factory. In this case, we could call php artisan make:poser CustomerFactory from the terminal to automatically create the factory for us.

The other time this error can crop up is if your Parent Model's relationship method name is different to the Child Model name. To illustrate, imaging that we have a UserFactory for User model that has a clients() method. That method returns a has-many relationship for the Customer model, and you have a Poser CustomerFactory.

When we call UserFactory::new()->withClients()(), Poser understands that you're using the clients() method on the User model, but it can't find a corresponding ClientFactory (because, it is in fact called CustomerFactory). The solution to this is to resort to standard bindings. So our updated call would be:

Poser is creating more models than expected when handling relationships

This happens when you declare default closures in your Laravel Factories. Poser has no way to detect that these exist, so they are still created when Poser makes the models. Poser provides a suitable workaround to this in Poser defaults. If this issue affects you, we recommend stripping out the closures in your Laravel Factories and replacing them with defaults in the relevant Poser Factory. Let's look at an example.

This Customer Laravel Factory has a closure for user_id, which causes n+1 User models to be created when calling UserFactory::new()->withCustomers(n)->create(). To resolve this issue, alter the above factory like so:

Now, we can alter the Customer Poser factory, like so:

Now, when calling UserFactory::new()->withCustomers(n)->create(), the default will be ignored, as we have already set it. However, when calling CustomerFactory::new()->create(), the default will be called and we will set a default User up for the Customer.

Changelog

Take a look at the CHANGELOG.md file for details on changes from update to update.

Before and After Examples

Its easier to show somebody that power of poser than it is to explain it, so here are some before and after code snippets. Plain Laravel vs. Poser. Also, note that all of the following examples have 0 code in the generated factories, so there is no extra work taking place "behind the scenes".

Let's start with one of the main reasons to use Poser: tests with complex relationships. In this example, a User can have friends. Those friends are other Users, and they are connected via a lookup table. The User and his friends can earn Achievements in the application. On the User model, we have created a custom friendsWithAllAchievements relationship that filters based on the fact that a User has every achievemnent available. We want to test this relationship returns the expected amount of friends when called.

As you can see, our test written with Poser is much simpler, more readable and manageable. Poser really shines when it comes to tests with a lot of preamble. It can make everybody's life a lot easier, and requires no additional effort!

However, even in 'simple' tests, Poser can make your life very simple. For example, you will often want to create a test to make sure a relationship works as expected, especially in TDD workflows. For the next test, our User may have many Customers, but he could also have no Customers. We want to test both possibilities.

Even in this very simple test, we were able to reduce our lines of code by more than half, whilst improving readability. Every function used in our Poser example oozes meaning and understanding. In the first test, your eyes tend to glaze over the code. You have to force yourself to read and understand it. In our second test, our eyes are instead drawn to the code. We gain insight into its purpose in seconds, as it almost reads like two sentences.

Credits

• Luke Raymond Downing

Follow me on Twitter @LukeDowning19 for updates!

Also, please star the repo. It really helps! ❤️

Security

If you discover any security-related issues, please email [email protected] instead of using the issue tracker.

Testing

License

The MIT License (MIT). Please see License File for more information.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Alan Holmes 💻	AndrewP 📖 ⚠️	veganista 🤔	Brad Roberts 🤔	Rhys Botfield 💻	MB 🤔	Solomon Antoine 📖
Patompong Savaengsuk 💻	mishbah 🤔	Dainius 💻

This project follows the all-contributors specification. Contributions of any kind welcome!