Blueprint Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require dakatsuka/blueprint-bundle:^1.1.0
   

   Register the bundle in config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3.x) under dev/test environments.

2. First Blueprint: Create a PHP file in src/YourBundle/Tests/Blueprints/post.php:

   use Dakatsuka\BlueprintBundle\Blueprint;
   
   Blueprint::register('post', 'App\Entity\Post', function ($post, $blueprint) {
       $post->setTitle('Default Title');
       $post->setBody('Default Body');
   });
   

3. First Usage: In a test case, inject the blueprint service and create an entity:

   $post = $this->get('blueprint')->create('post');
   $this->assertInstanceOf('App\Entity\Post', $post);
   

Where to Look First

• Blueprint Files: src/YourBundle/Tests/Blueprints/ (convention).
• Service Container: The blueprint service is auto-registered.
• Documentation: The README is minimal; focus on the Blueprint::register() method signature.

Implementation Patterns

Core Workflow

1. Define Blueprints: Register blueprints in dedicated files (e.g., user.php, product.php) under Tests/Blueprints/. Use the $blueprint object to:

   • Generate sequences ($blueprint->sequence()).
   • Create related entities ($blueprint->create('related_blueprint')).
   • Access the container ($blueprint->get('service_id')).

   Example:

   Blueprint::register('user', 'App\Entity\User', function ($user, $blueprint) {
       $user->setEmail('user' . $blueprint->sequence() . '@example.com');
       $user->setPosts($blueprint->createMany('post', 3)); // Create 3 posts
   });
   

2. Test Setup: Use the blueprint service in setUp() to preload test data:

   public function setUp(): void {
       $this->user = $this->get('blueprint')->create('user');
       $this->post = $this->get('blueprint')->create('post', ['title' => 'Custom Title']);
   }
   

3. Dynamic Data: Pass overrides as the second argument to create():

   $post = $this->get('blueprint')->create('post', ['title' => 'Dynamic Title']);
   

Integration Tips

• Fixtures vs. Blueprints: Use blueprints for test-specific data (e.g., users, posts) and fixtures (e.g., DoctrineFixturesBundle) for static reference data (e.g., countries, roles).
• Environment Awareness: Register blueprints only in dev/test environments to avoid runtime overhead.
• Dependency Injection: Inject the blueprint service directly into test classes or use the container:

  $this->blueprint = self::$container->get('blueprint');
  

Gotchas and Tips

Pitfalls

1. Circular Dependencies: Avoid bidirectional blueprint references (e.g., A creates B, B creates A). Use lazy loading or separate blueprints for complex hierarchies.

   // Anti-pattern (risk of infinite recursion)
   Blueprint::register('a', 'App\Entity\A', function ($a, $blueprint) {
       $a->setB($blueprint->create('b')); // 'b' might try to create 'a'
   });
   

2. Sequence Collisions: Sequences are global per test run. Reset them manually if needed:

   $this->get('blueprint')->resetSequence('post');
   

3. Entity Manager Flush: Blueprints do not auto-flush the EM. Manually flush after creation if needed:

   $post = $this->get('blueprint')->create('post');
   $this->get('doctrine')->getManager()->flush();
   

4. Namespace Conflicts: Ensure blueprint class namespaces match the bundle structure (e.g., Acme\BlogBundle\Tests\Blueprints\post.php for Acme\BlogBundle).

Debugging

• Missing Blueprints: Verify the blueprint file exists in the correct Tests/Blueprints/ directory and is auto-loaded (Symfony’s autoloader).
• Entity Not Found: Check the FQCN in Blueprint::register() matches the actual entity class.
• Sequence Issues: Use var_dump($blueprint->sequence()) to debug sequence generation.

Extension Points

1. Custom Sequence Generators: Extend the bundle by overriding the sequence logic:

   $blueprint->setSequenceGenerator('post', function () {
       return uniqid();
   });
   

2. Post-Creation Callbacks: Use the $blueprint object’s afterCreate callback (if supported in newer versions) or wrap creation in a closure:

   $post = $this->get('blueprint')->create('post');
   $post->setSlug($this->generateSlug($post->getTitle()));
   

3. Bulk Operations: Combine with createMany() for batch creation:

   $users = $this->get('blueprint')->createMany('user', 10);
   

Config Quirks

• No Configuration File: The bundle relies on convention over configuration. All settings are hardcoded (e.g., blueprint directory).
• Doctrine Dependency: Assumes Doctrine ORM is available. Register the bundle after Doctrine in bundles.php.