Getting Started

Minimal Setup

Installation

composer require dbp/relay-base-publication-bundle

Add the bundle to config/bundles.php:

DigitalBlueprint\RelayBasePublicationBundle\DigitalBlueprintRelayBasePublicationBundle::class => ['all' => true],

Configuration Publish the default config:
```
php bin/console dbp:relay:config:init
```
Review and customize config/packages/digital_blueprint_relay_base_publication.yaml.
First Use Case Create a basic publication endpoint:
```
php bin/console make:dbp-publication MyPublication
```
This generates a skeleton in src/Publication/MyPublication/.

Key Files to Review

docs/README.md: Core concepts, architecture, and API design.
config/packages/digital_blueprint_relay_base_publication.yaml: Default settings (e.g., API routes, middleware, serialization).
src/Publication/: Example publication structures (e.g., MyPublication/Controller.php, MyPublication/Resource.php).

Implementation Patterns

1. Publication Workflow

Define a Publication: Extend DigitalBlueprint\RelayBasePublicationBundle\Publication\AbstractPublication:

namespace App\Publication\MyPublication;

use DigitalBlueprint\RelayBasePublicationBundle\Publication\AbstractPublication;

class MyPublication extends AbstractPublication
{
    protected string $name = 'my_publication';
    protected string $description = 'My custom publication';

    public function getData(): array
    {
        return ['key' => 'value'];
    }
}

Register in services.yaml:

services:
    App\Publication\MyPublication\MyPublication:
        tags: ['dbp.relay.publication']

Route Handling: The bundle auto-registers routes under /api/publications/{name} (configurable). Use #[Route] for custom paths if needed.

2. Data Serialization

Resources: Implement DigitalBlueprint\RelayBasePublicationBundle\Publication\ResourceInterface:

namespace App\Publication\MyPublication;

use DigitalBlueprint\RelayBasePublicationBundle\Publication\ResourceInterface;

class MyResource implements ResourceInterface
{
    public function toArray($data): array
    {
        return ['data' => $data];
    }
}

Bind the resource in MyPublication:

protected string $resourceClass = MyResource::class;

Custom Serializers: Override getSerializer() in AbstractPublication to use Symfony’s SerializerInterface or a custom implementation.

3. Middleware Integration

Add Middleware: Configure in config/packages/digital_blueprint_relay_base_publication.yaml:
```
relay:
    middleware:
        - App\Middleware\MyMiddleware
```

Publication-Specific Middleware: Use addMiddleware() in your publication class:

public function build(): void
{
    $this->addMiddleware(MyMiddleware::class);
}

4. Testing

Unit Tests: Mock AbstractPublication and test getData()/getResource():

$publication = $this->createMock(MyPublication::class);
$publication->method('getData')->willReturn(['test' => true]);
$this->assertEquals(['data' => ['test' => true]], $publication->getResource()->toArray($publication->getData()));

Functional Tests: Use client->request('GET', '/api/publications/my_publication') and assert responses.

5. Event-Driven Extensions

Listen to Events: Subscribe to DigitalBlueprint\RelayBasePublicationBundle\Event\PublicationEvent:

namespace App\EventListener;

use DigitalBlueprint\RelayBasePublicationBundle\Event\PublicationEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class MySubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            PublicationEvent::PRE_FETCH => 'onPreFetch',
        ];
    }

    public function onPreFetch(PublicationEvent $event): void
    {
        $event->setData(['modified' => true]);
    }
}

Gotchas and Tips

1. Configuration Quirks

Route Prefix: The default route prefix (/api/publications) is not configurable via YAML. Override getRoutePrefix() in your publication class if needed.
```
protected function getRoutePrefix(): string
{
    return '/custom/prefix';
}
```
Caching: Enable/disable caching in config/packages/digital_blueprint_relay_base_publication.yaml:
```
relay:
    cache: true  # Defaults to false
```
Clear cache after changes:
```
php bin/console cache:clear
```

2. Debugging

Enable Verbose Logging: Set in .env:
```
DBP_RELAY_DEBUG=1
```
Logs appear in var/log/dev.log.
Common Issues:
- "Publication not found": Ensure the service is tagged dbp.relay.publication and the class implements AbstractPublication.
- Serialization errors: Validate ResourceInterface implementations with php bin/console debug:container App\Publication\MyPublication\MyResource.

3. Performance Tips

Lazy-Loading: Use #[ORM\LazyLoadingProxy] for Doctrine entities in publications to defer loading until serialization.

Batch Processing: For large datasets, implement getData() with pagination:

public function getData(int $page = 1, int $limit = 20): array
{
    return $this->entityManager->getRepository(MyEntity::class)
        ->createQueryBuilder('e')
        ->setFirstResult(($page - 1) * $limit)
        ->setMaxResults($limit)
        ->getQuery()
        ->getResult();
}

4. Extension Points

Custom HTTP Methods: Override supportedMethods() in AbstractPublication:

protected function supportedMethods(): array
{
    return ['GET', 'POST'];
}

Authentication: Integrate with Symfony’s security system by extending AbstractPublication and overriding checkAccess():
```
protected function checkAccess(): bool
{
    return $this->security->isGranted('ROLE_USER');
}
```
GraphQL Support: The bundle lacks native GraphQL support, but you can extend ResourceInterface to return GraphQL-compatible data and use overblog/graphql-bundle for serialization.

5. Migration Pitfalls

Version Compatibility: The bundle is pre-1.0. Check composer.json for breaking changes between minor versions.
Database Schema: If using Doctrine, ensure your MyPublication entity mappings align with the bundle’s expected structure (e.g., id, createdAt).

Relay Base Publication Bundle Laravel Package