Relay Maker Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require dbp/relay-maker-bundle
   

   Ensure the bundle is enabled in config/bundles.php:

   return [
       // ...
       DigitalBlueprint\RelayMakerBundle\DbpRelayMakerBundle::class => ['all' => true],
   ];
   

2. First Use Case: Generate a Relay-compatible bundle with an example entity:

   ./bin/console dbp:relay:maker:make:bundle \
       --vendor=YourVendor \
       --unique-name=YourBundle \
       --friendly-name="Your Bundle" \
       --example-entity=User
   

   This creates a bundles/YourBundle directory with:

   • Bundle registration (YourBundle.php).
   • Example entity (User.php) with Relay annotations.
   • Basic services.yaml and config/ structure.

3. Where to Look First:

   • Command Help: Run ./bin/console dbp:relay:maker:make:bundle --help to explore options.
   • Generated Files: Check bundles/ for the new bundle’s structure.
   • Relay Annotations: Focus on @RelayType and @RelayField in generated entities.

Implementation Patterns

Workflows

1. Bundle Development:

   • Use the maker to scaffold a new bundle, then extend it with custom logic.
   • Example: Add a Mutation or Query resolver by creating files in src/Resolver/ and referencing them in services.yaml.

2. Entity Generation:

   • Generate entities with Relay-specific fields:

     ./bin/console dbp:relay:maker:make:entity User --fields="name:string,email:string!@unique"
     

   • Fields support Relay types (string, id, boolean) and directives (@unique, @default).

3. Integration with Relay:

   • GraphQL Schema: The bundle auto-generates a schema.graphql file in the bundle’s Resources/ directory. Extend it by adding custom directives or types.
   • Services: Generated services.yaml includes Relay-specific services (e.g., relay.resolver). Override defaults by extending the bundle’s configuration.

4. Testing:

   • Use the --dry-run flag to preview changes:

     ./bin/console dbp:relay:maker:make:bundle --dry-run --vendor=Test
     

   • Test bundles locally by enabling them in config/bundles.php and running:

     ./bin/console debug:container | grep relay
     

Tips for Daily Use

• Reuse Templates: Customize the maker’s templates by overriding the bundle’s Resources/skeleton/ directory in your project.
• Automation: Use --no-confirm for CI/CD pipelines:

  ./bin/console dbp:relay:maker:make:bundle --no-confirm --vendor=Acme --unique-name=AcmeRelayBundle
  

• Documentation: Cross-reference with Relay’s official docs for field types and directives.

Gotchas and Tips

Pitfalls

1. Namespace Conflicts:

   • Ensure --vendor and --unique-name match your project’s PSR-4 autoloading. Example:

     ./bin/console dbp:relay:maker:make:bundle --vendor=App --unique-name=AppRelayBundle
     

   • Verify autoloading in composer.json:

     "autoload": {
         "psr-4": {
             "App\\": "src/",
             "App\\Relay\\": "bundles/AppRelayBundle/src/"
         }
     }
     

2. Missing Dependencies:

   • The bundle requires digital-blueprint/relay and symfony/maker-bundle. Install them first:

     composer require digital-blueprint/relay symfony/maker-bundle
     

3. Schema Merging:

   • If extending an existing schema, manually merge schema.graphql files to avoid conflicts. Use tools like graphql-tools for validation.

4. Entity Validation:

   • Generated entities use Relay’s @RelayField for validation. Custom validation (e.g., @Assert\Email) requires manual addition to the entity class.

Debugging

• Command Errors:

  • Check the bundle’s logs in var/log/dev.log for maker-related issues.
  • Run with -v for verbose output:

    ./bin/console dbp:relay:maker:make:bundle -v
    

• Generated Code:

  • Use git diff to inspect changes before confirming:

    ./bin/console dbp:relay:maker:make:bundle --dry-run | git diff
    

Extension Points

1. Custom Templates:

   • Override skeletons in config/packages/dev/dbp_relay_maker.yaml:

     dbp_relay_maker:
         skeleton_dir: '%kernel.project_dir%/custom-skeletons'
     

2. Post-Generation Hooks:

   • Extend the maker by creating a custom command that runs after generation (e.g., add tests or migrations).

3. Relay Configuration:

   • Customize Relay’s behavior by overriding the bundle’s relay.yaml:

     # config/packages/relay.yaml
     relay:
         schema:
             query: App\\Relay\\Query\\CustomQuery
     

4. Field Directives:

   • Add custom directives to entities by extending the bundle’s RelayFieldType class or using PHP attributes:

     use DigitalBlueprint\Relay\Attribute\RelayField;
     
     #[RelayField(type: 'string', directives: ['@custom(detail="...")'])]
     private string $customField;
     

```markdown
### Config Quirks
- **Bundle Registration**:
  The maker auto-registers bundles in `config/bundles.php`, but manually verify the entry exists after generation.

- **Environment-Specific Config**:
  The bundle generates `config/packages/dev/relay.yaml` and `prod/relay.yaml`. Override these for environment-specific settings (e.g., caching).

- **Symfony Maker Compatibility**:
  Ensure `symfony/maker-bundle` is up-to-date to avoid template rendering issues. Run:
  ```bash
  composer require symfony/maker-bundle:^1.0