Download the PHP package directorytree/dummy without Composer

Generate PHP class instances populated with fake dummy data using Faker

Index

• Requirements
• Installation
• Upgrading
• Introduction
• Setup
  • HasDummyFactory Trait
  • Class Factory
• Usage
  • Factory States
  • Eloquent Attributes
  • Factory Callbacks
  • Factory Sequences
  • Factory Collections
  • Factory Macros
  • IDE Type Inference

Requirements

• PHP >= 8.0

Installation

You can install the package via composer:

Upgrading

From v1 to v2

Dummy v2 renames the trait API so it is explicitly Dummy-owned and does not reserve the common factory() method name on your classes.

1. Replace DirectoryTree\Dummy\HasFactory with DirectoryTree\Dummy\HasDummyFactory.
2. Replace use HasFactory; with use HasDummyFactory;.
3. Replace YourClass::factory() calls with YourClass::dummy().
4. Rename toFactoryInstance to toDummyInstance.
5. Rename getFactoryDefinition to getDummyDefinition.
6. Change the toDummyInstance argument from array to DirectoryTree\Dummy\DummyData.

Before:

After:

If your constructor or factory method needs a plain array, call all():

You can also replace manual array access with helper methods where useful:

State callbacks, attribute closures, raw(), and custom Factory::generate(array $attributes) methods continue to receive plain arrays.

Introduction

Consider you have a class representing a restaurant reservation:

To make dummy instances of this class during testing, you have to manually populate it with dummy data.

This can quickly get out of hand as your class grows, and you may find yourself writing the same dummy data generation code over and over again.

Dummy provides you with a simple way to generate dummy instances of your classes using a simple API:

Setup

Dummy provides you two different ways to generate classes with dummy data.

HasDummyFactory Trait

The HasDummyFactory trait is applied directly to the class you would like to generate dummy instances of.

To use the HasDummyFactory trait, you must implement the toDummyInstance and getDummyDefinition methods:

The $attributes argument passed into toDummyInstance is a DirectoryTree\Dummy\DummyData instance. It supports array access and common data helpers, such as get, has, filled, notFilled, boolean, integer, enum, enums, only, except, collect, and all.

Once implemented, you may call the Reservation::dummy() method to create a new dummy factory:

Dynamic State Methods

The HasDummyFactory trait supports defining dynamic state methods. You can define state methods in your class using the format get{StateName}State and call them dynamically on the factory:

You can then use these state methods dynamically:

Class Factory

If you need more control over the dummy data generation process, you may use the Factory class.

The Factory class is used to generate dummy instances of a class using a separate factory class definition.

To use the Factory class, you must extend it with your own and override the definition and generate methods:

Usage

Once you've defined a factory, you can generate dummy instances of your class using the make method:

To add or override attributes in your definition, you may pass an array of attributes to the make method:

To generate multiple instances of the class, you may use the count method:

This will return an Illuminate\Support\Collection instance containing the generated classes.

If you have a counted factory but need one instance, use makeOne:

To make several instances with a different state record for each one, use makeMany:

You may also defer generation by creating a lazy callback:

Factory States

State manipulation methods allow you to define discrete modifications that can be applied to your dummy factories in any combination.

For example, your App\Factories\Reservation factory might contain a tomorrow state method that modifies one of its default attribute values:

You may prepend a state when you need it evaluated before the factory's existing states:

Eloquent Attributes

When Laravel's Eloquent is installed, Dummy will expand Eloquent model instances and factories into model keys:

This also works for values returned from attribute closures, so dependent attributes can use previously expanded keys:

Factory Callbacks

Factory callbacks are registered using the afterMaking method and allow you to perform additional tasks after making or creating a class. You should register these callbacks by defining a configure method on your factory class. This method will be automatically called when the factory is instantiated:

You may remove configured afterMaking callbacks for a single factory chain with withoutAfterMaking:

Factory Sequences

Sometimes you may wish to alternate the value of a given attribute for each generated class.

You may accomplish this by defining a state transformation as a sequence:

Factory Collections

By default, when making more than one dummy class, an instance of Illuminate\Support\Collection will be returned.

If you need to customize the collection of classes generated by a factory, you may override the collect method:

Factory Macros

Factories are macroable, allowing you to register reusable factory helpers:

IDE Type Inference

Dummy includes generic PHPDoc annotations so static analysis tools and IDEs can infer factory return types.

When using the HasDummyFactory trait, add an @use annotation to your class:

When using a dedicated factory class, add an @extends annotation:

These annotations allow tools to infer that Reservation::dummy()->makeOne() and ReservationFactory::new()->makeOne() return a Reservation instance.