Skip to content

Latest commit

 

History

History
129 lines (82 loc) · 5.99 KB

usage.md

File metadata and controls

129 lines (82 loc) · 5.99 KB
Raw

Usage

Basic Usage

There are two primary methods you can use in the FixtureGenerator. These are:

  • string generateYaml ( object|array<object> $objects [, FixtureGenerationContext $context ] ) - Returns a string of formatted YAML Alice fixtures
  • array generateArray ( object|array<object> $objects [, FixtureGenerationContext $context ] ) - Returns an array of Alice fixtures

Example:

<?php
use Trappar\AliceGenerator\FixtureGeneratorBuilder;

class MyObject
{
    public $foo;
}

$obj = new MyObject();
$obj->foo = 'bar';

$yaml = FixtureGeneratorBuilder::create()->build()->generateYaml($obj);
echo $yaml; // Or save this to the filesystem

Fixture Generation Contexts

Fixture Generation Contexts allow you to specify options which will affect a particular fixture generation run. Using them is easy:

<?php
use Trappar\AliceGenerator\FixtureGenerationContext;

// This will include only the Post
$fixtureGenerator->generateYaml(
    $post,
    FixtureGenerationContext::create()
        ->setMaximumRecursion(2)
);

Limiting Recursion

Since generating fixtures involves recursing through objects, you will often find yourself in a situation where generating fixtures yields quite a lot more information than you would like - this is just the nature of recursion! FixtureGenerationContext offers two solutions to this problem.

Pictures make these concepts quite a lot easier to grok, but it's important to understand what these diagrams mean. Here's a key for these diagrams:

  • Each rounded square represents an Object
  • Objects store references to each other using properties like $user->posts (think Doctrine relations)
  • Green object(s) are initially passed to the FixtureGenerator
  • Blue object(s) are included in the generated fixtures (Green is also included)
  • Red object(s) are excluded due to the particular option set in the FixtureGenerationContext
  • White object(s) aren't touched in any way in the process of generating fixtures

Limiting Recursion Depth

setMaximumRecursion( int $depth ) - allows you to limit the recursion depth.

Examples:

depth0

depth1

depth2

Limiting Recursion With Object Constraints

Fixture generation will traverse from one object to related objects through an object's properties. In our example objects, generating Fixtures with no maximum recursion on virtually any object can theoretically result in practically the whole database being dumped as Fixtures. For example, since a Post has a User and that User is part of a Group - any Users also in that Group and all Posts for all of those Users will be returned. Object constraints give you a way to avoid this problem.

addPersistedObjectConstraint( object $constrainingObject ) - add an object as a persisted object constraint. This may be called multiple times with objects of the same or different classes.

All objects of a given class are constrained by adding one or more objects of that class as persisted object constraints. Once a class is constrained, any object of the same class which isn't also one of the constrained objects will be completely ignored.

Examples:

userconstrained

postsconstrained

Customizing Reference Naming Strategy

setReferenceNamer( ReferenceNamerInterface $referenceNamer ) - allows you to specify a custom class for handling reference names.

There are three ReferenceNamer classes included in this library:

  • Trappar\AliceGenerator\ReferenceNamer\ClassNamer (default) - names references like '@User-1'.
  • Trappar\AliceGenerator\ReferenceNamer\NamespaceNamer - names references like '@Appbundle-Entity-Post-1'.
  • Trappar\AliceGenerator\ReferenceNamer\PropertyReferenceNamer - uses a mapping to name references like '@User-trappar' (where "trappar" is the user's username).

Example:

<?php
use Trappar\AliceGenerator\FixtureGenerationContext;

// Using the alternative NamespaceNamer - references will be like @Appbundle-Entity-Post-1
$namer = new \Trappar\AliceGenerator\ReferenceNamer\NamespaceNamer();
$fixtureGenerator->generateYaml($post, FixtureGenerationContext::create()->setReferenceNamer($namer));

// NamespaceNamer has several options...
$namer->setIgnoredNamespaces(['AppBundle']);
$namer->setNamespaceSeparator('_');

// Now references will be like "Entity_Post_1"
$fixtureGenerator->generateYaml($post, FixtureGenerationContext::create()->setReferenceNamer($namer));

You can also create your own ReferenceNamer by implementing Trappar\AliceGenerator\ReferenceNamer\ReferenceNamerInterface in your class.

Force Inclusion of Properties at Default Values

setExcludeDefaultValues( bool $exclude ) - Setting this to true/false causes properties to be handled differently during fixture generation.

  • When true (default) - a property which is the same value as a newly initialized object of the same class will be excluded from fixture generation
  • When false - all properties will be included during fixture generation

Sorting Resulting Alice Fixtures

setSortResults( bool $sort ) - Setting this to true/false enables/disables sorting of returned Alice fixtures.

  • When true (default) - The returned Alice fixtures will be sorted both by object type, and in each object type by reference name
  • When false - no sorting will be used

Sorting results by default is partially an aesthetic choice, and partially to ensure that the returned results always appear in the same order so subsequent fixture generation on the same/similar objects will return the same results.

Back to Table of Contents