Alice allows you to create a ton of fixtures/fake data for use while developing or testing your project. It gives you a few essential tools to make it very easy to generate complex data with constraints in a readable and easy to edit way, so that everyone on your team can tweak the fixtures if needed.
This is installable via Composer as nelmio/alice.
To use it in Symfony2 you may want to use the hautelook/alice-bundle or h4cc/alice-fixtures-bundle package instead.
The easiest way to use this is to call the static Nelmio\Fixture\Fixture::load
method. It will bootstrap everything for you and return you a set of persisted
objects in the container you give it.
Examples:
// load a yaml file into a Doctrine\Common\Persistence\ObjectManager object
$objects = \Nelmio\Alice\Fixtures::load(__DIR__.'/fixtures.yml', $objectManager);
// load a php file into a Doctrine\Common\Persistence\ObjectManager object
$objects = \Nelmio\Alice\Fixtures::load(__DIR__.'/fixtures.php', $objectManager);Note: You can also pass an array of filenames if you have multiple files with references spanning more than one.
Fixtures::load accepts a third $options argument that is an array
with the following keys:
- locale: the default locale
- providers: an array of additional Faker providers
- seed: a seed to make sure Faker generates data consistently across runs, set to null to disable (defaults to 1)
- logger: a callable or Psr\Log\LoggerInterface object that will receive progress information during the loading of the fixtures
- persist_once: only persist objects once if multiple files are passed, by default objects are persisted after each file
If you want a bit more control you can instantiate the various object yourself and make it work just as easily:
// load objects from a yaml file
$loader = new \Nelmio\Alice\Loader\Yaml();
$objects = $loader->load(__DIR__.'/fixtures.yml');
// optionally persist them into the doctrine object manager
// you can also do that yourself or persist them in another way
// if you do not use doctrine
$persister = new \Nelmio\Alice\ORM\Doctrine($objectManager);
$persister->persist($objects);Note: To load plain PHP files, you can use the
\Nelmio\Alice\Loader\Baseclass instead. These PHP files must return an array containing the same structure as the yaml files have.
The most basic functionality of this library is to turn flat yaml files into objects. You can define many objects of different classes in one file as such:
Nelmio\Entity\User:
user0:
username: bob
fullname: Bob
birthDate: 1980-10-10
email: bob@example.org
favoriteNumber: 42
user1:
username: alice
fullname: Alice
birthDate: 1978-07-12
email: alice@example.org
favoriteNumber: 27
Nelmio\Entity\Group:
group1:
name: AdminsThis works fine, but it is not very powerful and is completely static. You still have to do most of the work. Let's see how to make this more interesting.
The first step is to let Alice create many copies of an object for you to remove duplication from the yaml file.
You can do that by defining a range in the fixture name:
Nelmio\Entity\User:
user{1..10}:
username: bob
fullname: Bob
birthDate: 1980-10-10
email: bob@example.org
favoriteNumber: 42Now it will generate ten users, with names user1 to user10. Pretty good but we only have 10 bobs with the same name, username and email, which is not so fancy yet.
You can also specify a list of values instead of a range:
Nelmio\Entity\User:
user{alice, bob}:
username: <current()>
fullname: <current()>
birthDate: 1980-10-10
email: <current()>@example.org
favoriteNumber: 42To go further we can just randomize data.
Alice integrates with the Faker library.
Using <foo()> you can call Faker data providers to generate random data. Check
the list of Faker providers.
Let's turn our static bob user into a randomized entry:
Nelmio\Entity\User:
user{1..10}:
username: <username()>
fullname: <firstName()> <lastName()>
birthDate: <date()>
email: <email()>
favoriteNumber: <numberBetween(1, 200)>As you see in the last line, you can also pass arguments to those just as if you were calling a function.
Faker can create localized data for adresses, phone numbers and so on. You can
set the default locale to use by passing a locale value in the $options
array of Fixtures::load.
Additionally, you can mix locales by adding a locale prefix to the faker key,
i.e. <fr_FR:phoneNumber()> or <de_DE:firstName()>.
Sometimes though you need to call a method to initialize some more data, you
can do this just like with properties but instead using the method name and
giving it an array of arguments. For example let's assume the user class has
a setLocation method that requires a latitude and a longitude:
Nelmio\Entity\User:
user1:
username: <username()>
setLocation: [40.689269, -74.044737]When a constructor has mandatory arguments you must define it as explained above, for example if the User required a username in the constructor you could do the following:
Nelmio\Entity\User:
user1:
__construct: [<username()>]If you want to call a static factory method instead of a constructor, you can specify a hash as the constructor:
Nelmio\Entity\User:
user1:
__construct: { create: [<username()>] }If you specify false in place of constructor arguments, Alice will
instantiate the object without executing the constructor:
Nelmio\Entity\User:
user1:
__construct: falseSome fields do not have to be filled-in, like the favoriteNumber in this
example might be personal data you don't want to share, to reflect this in
our fixtures and be sure the site works and looks alright even when users
don't enter a favorite number, we can make Alice fill it in sometimes using
the 50%? value : empty value notation. It's a bit like the ternary operator,
and you can omit the empty value if null is ok as such: %50? value.
Let's update the user definition with this new information:
Nelmio\Entity\User:
user{1..10}:
username: <username()>
fullname: <firstName()> <lastName()>
birthDate: <date()>
email: <email()>
favoriteNumber: 50%? <numberBetween(1, 200)>Now only half the user will have a number filled-in.
Let's get back to the Group. Ideally a group should have members, and Alice
allows you to reference one object from another one. You can do that with the
@name notation, where name is a fixture name from any class.
Let's add a fixed owner to the group:
Nelmio\Entity\User:
# ...
Nelmio\Entity\Group:
group1:
name: Admins
owner: @user1Alice also allows you to directly reference objects' properties using the @name->property notation.
Nelmio\Entity\User:
# ...
Nelmio\Entity\Group:
group1:
name: Admins
owner: @user1->usernameTo be able to use this feature, your entities have to match some requirements :
- You can reference public properties
- You can reference properties reachable through a getter (i.e :
@name->propertywill call$name->getProperty()ifpropertyis not public) - You can reference entities' ID but you will then have to split fixtures in multiple files (this is because objects are persisted at the end of each file processing) :
# fixture_user.yml
Nelmio\Entity\User:
# ...# fixture_group.yml
Nelmio\Entity\Group:
group1:
name: Admins
owner: @user1->idIf you want to create ten users and ten groups and have each user own one
group, you can use <current()> which is replaced with the current id of
each iteration when using fixture ranges:
Nelmio\Entity\User:
# ...
Nelmio\Entity\Group:
group{1..10}:
owner: @user<current()>If you would like a random user instead of a fixed one, you can define a reference with a wildcard:
Nelmio\Entity\User:
# ...
Nelmio\Entity\Group:
group1:
name: Admins
owner: @user*It will then pick any object whose name matches user* where * can be any
string.
There is one limitation, you can only refer to objects that are defined above in the file. If you want to use an existing object that is already present in your database you can also provide the id of the object. For this to work however the setter method for that property must have a type hint.
Nelmio\Entity\Group:
group1:
owner: 1 # this will try to fetch the User (as typehinted in Group::setOwner) with id 1It is also possible to create a relation to a random object by id:
Nelmio\Entity\Group:
group1:
owner: <numberBetween(1, 200)>If we want to also add group members, there are two ways to do this. One is to define an array of references to have a fixed set of members:
Nelmio\Entity\User:
# ...
Nelmio\Entity\Group:
group1:
name: Admins
owner: @user1
members: [@user2, @user3]The other, which is more interesting, is to define a reference with a wildcard, and also tell Alice how many object you want:
Nelmio\Entity\User:
# ...
Nelmio\Entity\Group:
group1:
name: Admins
owner: @user1
members: 5x @user*In this case it will pick 5 fixture objects which have a name matching user*.
You can also randomize the amount by combining it with faker data:
# ...
members: <numberBetween(1, 10)>x @user*Note: You do not need to define multi-references inside an array, since they are automatically translated to an array of objects.
Quite often some database fields have a unique constraint set on them, in which case having the fixtures randomly failing to generate because of bad luck is quite annoying. This is especially important if you generate large amounts of objects, as otherwise you will most likely never encounter this issue.
By declaring the key as unique using the (unique) flag at the end, Alice
will make sure every element of this class that is created has a unique value
for that property. For example:
Nelmio\Entity\User:
user{1..10}:
username (unique): <username()>For some advanced use cases you sometimes need to reference one property
from another, for example to generate the update date while making sure
it is after the creation date. If you simply use two random dates it might
be that they are reversed, but Alice let's you refer to other properties
using the traditional PHP $variable notation.
Let's add created/modified dates to our group:
Nelmio\Entity\User:
# ...
Nelmio\Entity\Group:
group1:
name: Admins
owner: @user1
members: <numberBetween(1, 10)>x @user*
created: <dateTimeBetween('-200 days', 'now')>
updated: <dateTimeBetween($created, 'now')>As you can see, we make sure that the update date is between the creation date and the current time, which ensure the data will look real enough.
Sometimes you require value objects that are not persisted by an ORM, but
are just stored on other objects. You can use the (local) flag on the class
or the instance name to mark them as non-persistable. They will be available
as references to use in other objects, but will not be returned by the
LoaderInterface::load call.
For example this avoids getting an error because Geopoint is not an Entity if you use the Doctrine persister.
Nelmio\Data\Geopoint (local):
geo1:
__construct: [<latitude()>, <longitude()>]
Nelmio\Entity\Location:
loc{1..100}:
name: <city()>
geopoint: @geo1Sometimes you need more than what Faker and Alice provide you natively, and there are two ways to solve the problem:
-
Embed PHP code in the yaml file. It is included by the loader so you can add arbitrary PHP as long as it outputs valid yaml. That said, this is like PHP templates, it quickly ends up very messy if you do too much logic, so it's best to extract logic out of the templates.
-
Add a custom Faker Provider class. These are just classes that expose public methods, all the public methods are available as
<method()>in the Alice fixture files. For example if you want a custom group name generator and you use the standard Doctrine Fixtures package in a Symfony2 project, you could do the following:<?php namespace Acme\DemoBundle\DataFixtures\ORM; use Doctrine\Common\Persistence\ObjectManager; use Doctrine\Common\DataFixtures\FixtureInterface; use Nelmio\Alice\Fixtures; class LoadFixtureData implements FixtureInterface { public function load(ObjectManager $om) { // pass $this as an additional faker provider to make the "groupName" // method available as a data provider Fixtures::load(__DIR__.'/fixtures.yml', $om, array('providers' => array($this))); } public function groupName() { $names = array( 'Group A', 'Group B', 'Group C', ); return $names[array_rand($names)]; } }
That way you can now use
name: <groupName()>to generate specific group names.
In case, you want to specify a custom function that will be used to set all the values,
you can specify a __set value:
Nelmio\Data\Geopoint:
geo1:
__set: customSetter
foo: barWhen the objects are populated, the customSetter function will be called, with the first parameter
being the key, the second one being the value (so similar to the magic PHP setter). In the above
example, the following call will be made on the instance when populating:
$geopoint->customSetter('foo', 'bar');In the end, using most of the tools above, we have this file creating a bunch of users and a group, all of it being linked together, and with little typing:
Nelmio\Entity\User:
user{1..10}:
username: <username()>
fullname: <firstName()> <lastName()>
birthDate: <date()>
email: <email()>
favoriteNumber: 50%? <numberBetween(1, 200)>
Nelmio\Entity\Group:
group1:
name: Admins
owner: @user1
members: <numberBetween(1, 10)>x @user*
created: <dateTimeBetween('-200 days', 'now')>
updated: <dateTimeBetween($created, 'now')>If you like to have a few specific users with specific data to write tests against of course you can define them above/below the ones using the randomized data. Combine it all as you see fit!
Released under the MIT License, see LICENSE.