Skip to content

Commit

Permalink
Update documentation (#544)
Browse files Browse the repository at this point in the history
  • Loading branch information
@theofidry
theofidry authored Sep 14, 2016
1 parent ab2fbe2 commit 4134579
Show file tree
Hide file tree
Showing 7 changed files with 285 additions and 294 deletions.
47 changes: 39 additions & 8 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,22 +7,22 @@ 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.

**Warning**: this doc is behind updated for alice 3.0. If you want to check the documentation for 2.x, head
[this way](https://github.com/nelmio/alice/tree/2.x).
**Warning**: this doc is behind updated for alice 3.0. If you want to check the
documentation for 2.x, head [this way](https://github.com/nelmio/alice/tree/2.x).

## Table of Contents

1. [Installation](#installation)
1. [Example](#example)
1. [Getting Started](doc/getting-started.md)
1. [Basic Usage](doc/getting-started.md#basic-usage)
2. [Detailed Usage](doc/getting-started.md#detailed-usage)
1. [Framework integration](doc/getting-started.md#)
1. [Symfony](doc/getting-started.md#)
1. [Complete Reference](doc/complete-reference.md)
1. [Creating Fixtures](doc/complete-reference.md#creating-fixtures)
1. [Fixture Ranges](doc/complete-reference.md#fixture-ranges)
1. [Calling Methods](doc/complete-reference.md#calling-methods)
1. [Specifying Constructor Arguments](doc/complete-reference.md#specifying-constructor-arguments)
1. [Custom Setter](doc/complete-reference.md#custom-setter)
1. [Optional Data](doc/complete-reference.md#optional-data)
1. [Handling Unique Constraints](doc/complete-reference.md#handling-unique-constraints)
1. [Handling Relations](doc/relations-handling.md)
Expand All @@ -37,9 +37,12 @@ to edit way, so that everyone on your team can tweak the fixtures if needed.
1. [Parameters](doc/fixtures-refactoring.md#parameters)
1. [Customize Data Generation](doc/customizing-data-generation.md)
1. [Faker Data](doc/customizing-data-generation.md#faker-data)
1. [Localized Fake Data]() **TODO: port that change to v2**
1. [Default Providers]()
1. [Identity]()
1. [Reuse generated data using objects value](doc/customizing-data-generation.md#reuse-generated-data-using-objects-value)
1. [Custom Faker Data Providers](doc/customizing-data-generation.md#custom-faker-data-providers)
1. [Event handling with Processors](doc/processors.md)
1. [Identity]()
1. [Third-party libraries](#third-party-libraries)
1. [Contribute](#contribute)
1. [Upgrade](#upgrade)
Expand All @@ -50,9 +53,10 @@ Other references:

## Installation

This is installable via [Composer](https://getcomposer.org/) as [nelmio/alice](https://packagist.org/packages/nelmio/alice):
This is installable via [Composer](https://getcomposer.org/) as
[nelmio/alice](https://packagist.org/packages/nelmio/alice):

composer require nelmio/alice
composer require --dev nelmio/alice


## Example
Expand Down Expand Up @@ -80,7 +84,34 @@ Nelmio\Entity\Group:
You can then load them easily with:
```php
$objects = \Nelmio\Alice\Fixtures::load(__DIR__.'/fixtures.yml', $objectManager);
$loader = new Nelmio\Alice\Loader\NativeLoader();
$objectSet = $loader->loadFile(__DIR__.'/fixtures.yml');
```

Or load an array right away:

```php
$loader = new Nelmio\Alice\Loader\NativeLoader();
$objectSet = $loader->loadData([
\Nelmio\Entity\User::class => [
'user{1..10}' => [
'username' => '<username()>',
'fullname' => '<firstName()> <lastName()>',
'birthDate' => '<date()>',
'email' => '<email()>',
'favoriteNumber' => '50%? <numberBetween(1, 200)>',
],
],
\Nelmio\Entity\Group::class => [
'group1' => [
'name' => Admins,
'owner' => '@user1',
'members' => '<numberBetween(1, 10)>x @user*',
'created' => '<dateTimeBetween("-200 days", "now")>',
'updated' => '<dateTimeBetween($created, "now")>',
],
],
]);
```

For more information, refer to [the documentation](#table-of-contents).
Expand Down
77 changes: 45 additions & 32 deletions doc/complete-reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Nelmio\Entity\User:
birthDate: 1980-10-10
email: bob@example.org
favoriteNumber: 42

user1:
username: alice
fullname: Alice
Expand All @@ -33,26 +33,26 @@ still have to do most of the work. Let's see how to make this more interesting.
### PHP
You can also specify fixtures in PHP by returing an array where each key with the following structure:
You can also specify fixtures in PHP by returing an array where each key with
the following structure:
```php
<?php

return [
'Nelmio\Alice\support\models\User' => [
'user1' => [
'username' => '<identity($fake("upperCaseProvider", null, "John Doe"))>',
'fullname' => '<upperCaseProvider("John Doe")>',
'username' => 'bob',
'fullname' => 'Bob',
],
'user2' => [
'username' => $fake('identity', null, $fake('upperCaseProvider', null, 'John Doe')),
'fullname' => $fake('upperCaseProvider', null, 'John Doe'),
'username' => 'alice',
'fullname' => 'Alice',
],
],
];
```

**Warning**: the usage of the `$fake` closure has been deprecated since in v2.2.0 and will be removed in v3.0.0.

## Fixture Ranges

Expand All @@ -71,27 +71,41 @@ Nelmio\Entity\User:
favoriteNumber: 42
```
Now it will generate ten users, with names user1 to user10. Pretty good but
Now it will generate ten users, with IDs `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:

```yaml
Nelmio\Entity\User:
user{alice, bob}:
user_{alice, bob}:
username: '<current()>'
fullname: '<current()>'
birthDate: 1980-10-10
email: '<current()>@example.org'
favoriteNumber: 42
```

To go further we can just randomize data.
>The `<current()>` function is a bit special as it can only be called in the
>context of a collection (list of values or a range).

>In the case of a list of values like the example above, it will return for the
>first fixture `user_alice` the value `alice`, and `bob` for the fixture
>`user_bob`.

>In the case of a range (e.g. `user{1..10}`), `<current()>` will return `1` for
>`user1`, `2` for `user2` etc.

>Using this function outside of this case will cause an exception.

To go further we the example above, we can just randomize data.


## Calling Methods

**TODO: update with https://github.com/nelmio/alice/issues/388**

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
Expand Down Expand Up @@ -126,38 +140,26 @@ Nelmio\Entity\User:
__construct: { create: ['<username()>'] }
```

If you specify `false` in place of constructor arguments, Alice will
instantiate the object without executing the constructor:
If the static factory belongs to another class, you can call it as follows:

```yaml
Nelmio\Entity\User:
user1:
__construct: false
__construct: { Nelmio\User\UserFactory::create: ['<username()>'] }
```

Note: If you are using a private constructor without any mandatory arguments you can omit the constructor altogether.
Private constructors with mandatory arguments should use the static factory method described above.


## Custom Setter

In case, you want to specify a custom function that will be used to set all the values,
you can specify a `__set` value:
If you specify `false` in place of constructor arguments, Alice will
instantiate the object without executing the constructor:

```yaml
Nelmio\Data\Geopoint:
geo1:
__set: customSetter
foo: bar
Nelmio\Entity\User:
user1:
__construct: false
```

When 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:

```php
$geopoint->customSetter('foo', 'bar');
```
Note: If you are using a private constructor without any mandatory arguments you
can omit the constructor altogether. Private constructors with mandatory
arguments should use the static factory method described above.


## Optional Data
Expand Down Expand Up @@ -201,5 +203,16 @@ Nelmio\Entity\User:
username (unique): '<username()>'
```

In a case of a method call or a constructor, you can specify the unique flag
like so:

```yaml
Nelmio\Entity\User:
user{1..10}:
__construct:
0 (unique): '<username()>'
```


Next chapter: [Handling Relations](relations-handling.md)<br />
Previous chapter: [Getting Started](getting-started.md)
Loading

0 comments on commit 4134579

Please sign in to comment.