Relay Frontend Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dbp/relay-frontend-bundle
   

   Ensure your config/bundles.php includes:

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

2. First Use Case: The bundle provides APIs for frontend apps to interact with Laravel backend services. Start by inspecting the config/packages/dbp_relay_frontend.yaml for available endpoints and configurations. Example:

   # config/packages/dbp_relay_frontend.yaml
   relay:
       endpoints:
           auth: '/api/auth'
           data: '/api/data'
   

3. Frontend Integration: Use the generated API routes (e.g., /api/auth/login) in your frontend app. The bundle assumes a Relay-based frontend (likely GraphQL), so ensure your frontend is configured to query these endpoints.

Implementation Patterns

API Endpoint Workflows

1. Authentication: The bundle likely provides JWT or OAuth endpoints. Example usage in frontend:

   // Fetch token via Relay API
   const response = await fetch('/api/auth/login', {
       method: 'POST',
       body: JSON.stringify({ email, password }),
       headers: { 'Content-Type': 'application/json' },
   });
   const { token } = await response.json();
   

2. Data Fetching: Use the /api/data endpoint for GraphQL queries. Configure your Relay frontend to point to this route:

   // Example Relay query
   const data = await request({
       query: gql`
           query GetUser($id: ID!) {
               user(id: $id) { name, email }
           }
       `,
       variables: { id: '1' },
   });
   

3. Middleware Integration: The bundle may include middleware for CORS, rate-limiting, or authentication. Verify in config/routes/api.php:

   use DigitalBlueprint\RelayFrontendBundle\Middleware\RelayAuthMiddleware;
   
   $router->group(['middleware' => RelayAuthMiddleware::class], function () {
       // Protected routes
   });
   

Common Patterns

• Environment-Specific Configs: Override configs in config/packages/dbp_relay_frontend_{env}.yaml (e.g., dev, prod).

  relay:
      endpoints:
          data: '%env(RELAY_DATA_ENDPOINT)%'
  

• Event Listeners: Subscribe to frontend events (e.g., RelayFrontendEvent) in your backend services:

  use DigitalBlueprint\RelayFrontendBundle\Event\RelayFrontendEvent;
  
  public function onFrontendEvent(RelayFrontendEvent $event) {
      // Handle event logic
  }
  

Gotchas and Tips

Pitfalls

1. Relay-Specific Assumptions: The bundle is tightly coupled with Relay/GraphQL. If your frontend isn’t Relay-based, expect integration challenges. Verify compatibility with your frontend stack.

2. CORS Configuration: Ensure your backend CORS settings (config/cors.php) allow requests from your frontend domain:

   'paths' => ['api/*', 'graphql'],
   'allowed_methods' => ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
   

3. Authentication Quirks: If using JWT, validate token expiration and refresh logic in your frontend:

   // Check token expiry before each request
   if (isTokenExpired(token)) {
       refreshToken().then(newToken => { /* retry request */ });
   }
   

Debugging

• API Route Issues: Use php bin/console debug:router | grep relay to list available routes. If routes are missing, clear the cache:

  php bin/console cache:clear
  

• GraphQL Errors: Enable GraphQL debugging in config/packages/dbp_relay_frontend.yaml:

  relay:
      debug: true
  

  This exposes detailed error messages in responses.

Extension Points

1. Custom Endpoints: Extend the bundle by adding new endpoints in config/packages/dbp_relay_frontend.yaml:

   relay:
       endpoints:
           custom: '/api/custom'
   

   Then create a controller to handle /api/custom.

2. Event Customization: Dispatch custom events by extending the bundle’s event system:

   use Symfony\Component\EventDispatcher\EventDispatcherInterface;
   
   $dispatcher->dispatch(new CustomRelayEvent($data));
   

3. Middleware Overrides: Replace or extend middleware in config/bundles.php:

   DigitalBlueprint\RelayFrontendBundle\Middleware\CustomAuthMiddleware::class => ['all' => true],
   

Pro Tips

• Version Pinning: Pin the package version in composer.json to avoid breaking changes:

  "dbp/relay-frontend-bundle": "1.0.0"
  

• Testing: Use the bundle’s test utilities (if available) to mock frontend requests in PHPUnit:

  $client = static::createClient();
  $client->request('POST', '/api/auth/login', ['json' => ['email' => '[email protected]']]);
  

• Documentation: Since the README is minimal, explore the src/ directory for undocumented features (e.g., Event, Middleware classes).

```markdown
---