## Getting Started

### Minimal Setup
1. **Install the Bundle**
   ```bash
   composer require dbp/relay-sublibrary-connector-base-organization-bundle

Ensure your config/bundles.php includes:

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

Publish Configuration Publish the default config to customize API endpoints, authentication, and organization mappings:
```
php bin/console dbp:relay-sublibrary:config:publish
```
Edit config/packages/dbp_relay_sublibrary_connector_base_organization.yaml to match your Relay API gateway settings.

First Use Case: Fetching Organization Data Inject the RelayOrganizationClient into a service or controller:

use DigitalBlueprint\RelaySublibraryConnectorBaseOrganizationBundle\Client\RelayOrganizationClient;

class MyController extends AbstractController
{
    public function __construct(
        private RelayOrganizationClient $organizationClient
    ) {}

    public function showOrganization(string $organizationId)
    {
        $organization = $this->organizationClient->fetchOrganization($organizationId);
        return $this->json($organization);
    }
}

Verify API Connectivity Run a test endpoint to ensure the Relay gateway is reachable:
```
php bin/console dbp:relay-sublibrary:test-connection
```

Implementation Patterns

Core Workflows

Organization Data Synchronization Use the RelayOrganizationSyncService to sync local data with Relay:

$syncService = $this->container->get(RelayOrganizationSyncService::class);
$syncService->syncAllOrganizations(); // Triggers full sync
$syncService->syncOrganization($orgId); // Syncs a single org

Event-Driven Updates Subscribe to Relay webhooks (if supported) via the RelayWebhookListener:

# config/packages/dbp_relay_sublibrary_connector_base_organization.yaml
relay_webhooks:
    enabled: true
    endpoint: '/api/relay/webhook'

Implement a custom listener to handle incoming webhook events:

use DigitalBlueprint\RelaySublibraryConnectorBaseOrganizationBundle\Event\RelayWebhookEvent;

class CustomWebhookListener implements RelayWebhookListenerInterface
{
    public function onWebhook(RelayWebhookEvent $event)
    {
        // Handle event->getPayload()
    }
}

Custom Field Mapping Extend the base OrganizationMapper to handle custom Relay fields:

use DigitalBlueprint\RelaySublibraryConnectorBaseOrganizationBundle\Mapper\OrganizationMapperInterface;

class CustomOrganizationMapper implements OrganizationMapperInterface
{
    public function mapToLocal(array $relayData): array
    {
        $mapped = parent::mapToLocal($relayData);
        $mapped['custom_field'] = $relayData['custom_relay_field'] ?? null;
        return $mapped;
    }
}

services:
    DigitalBlueprint\RelaySublibraryConnectorBaseOrganizationBundle\Mapper\OrganizationMapperInterface: '@App\CustomOrganizationMapper'

Bulk Operations Use the RelayOrganizationBulkService for batch operations:

$bulkService = $this->container->get(RelayOrganizationBulkService::class);
$results = $bulkService->createOrUpdateOrganizations([
    ['name' => 'Org 1', 'externalId' => 'org_123'],
    ['name' => 'Org 2', 'externalId' => 'org_456'],
]);

Integration Tips

Laravel Queues: Offload sync operations to queues for long-running tasks:
```
$syncService->syncAllOrganizations()->onQueue('relay_sync');
```

Caching: Cache frequently accessed organization data:

$organization = Cache::remember("relay_org_{$orgId}", now()->addHours(1), function() use ($orgId) {
    return $this->organizationClient->fetchOrganization($orgId);
});

API Rate Limiting: Implement a decorator for rate-limited requests:

use DigitalBlueprint\RelaySublibraryConnectorBaseOrganizationBundle\Client\RelayOrganizationClientInterface;

class RateLimitedOrganizationClient implements RelayOrganizationClientInterface
{
    public function __construct(
        private RelayOrganizationClientInterface $client,
        private RateLimiter $limiter
    ) {}

    public function fetchOrganization(string $orgId)
    {
        $this->limiter->hit('relay_org_fetch');
        return $this->client->fetchOrganization($orgId);
    }
}

Gotchas and Tips

Common Pitfalls

Authentication Failures
- Symptom: 401 Unauthorized or 403 Forbidden errors when calling Relay.
- Fix: Verify relay_auth config in dbp_relay_sublibrary_connector_base_organization.yaml:
```
relay_auth:
    token: 'your_relay_api_token'
    method: 'header' # or 'query'
```
- Debug: Use php bin/console debug:config dbp_relay_sublibrary_connector_base_organization to inspect settings.
Field Mismatches
- Symptom: Data not mapping correctly between Relay and local DB.
- Fix: Override the OrganizationMapper (as shown in Implementation Patterns) or extend the base config:
```
relay_field_mapping:
    local_field: relay_field_name
```
Webhook Delays
- Symptom: Relay webhooks not triggering local updates promptly.
- Fix: Ensure your webhook endpoint is publicly accessible and configure retry logic:
```
relay_webhooks:
    retry_attempts: 3
    retry_delay: 60 # seconds
```
Archived Package Risks
- Symptom: No updates or community support.
- Mitigation:
  - Fork the repository to apply critical fixes.
  - Monitor for breaking changes in the Relay API (this bundle may not auto-update).
  - Consider wrapping calls in a feature flag for easier migration later.

Debugging Tips

Enable Verbose Logging Add to config/logging.php:

channels:
    relay:
        type: single
        path: var/log/relay.log
        level: debug

Then configure the bundle to use this channel:

# config/packages/dbp_relay_sublibrary_connector_base_organization.yaml
logging_channel: relay

HTTP Debugging Use the RelayHttpClient directly to inspect raw requests/responses:

$client = $this->container->get(RelayHttpClient::class);
$response = $client->get('/organizations/' . $orgId, [
    'headers' => ['Authorization' => 'Bearer ' . config('relay_auth.token')],
]);

Database Sync Issues Check the relay_organization_sync table for failed sync records:

SELECT * FROM relay_organization_sync WHERE status = 'failed' ORDER BY created_at DESC;

Extension Points

Custom Sync Strategies Implement RelaySyncStrategyInterface for custom sync logic:

class CustomSyncStrategy implements RelaySyncStrategyInterface
{
    public function shouldSync(array $localData, array $remoteData): bool
    {
        // Custom logic to determine if sync is needed
        return true;
    }
}

services:
    DigitalBlueprint\RelaySublibraryConnectorBaseOrganizationBundle\Strategy\RelaySyncStrategyInterface: '@App\CustomSyncStrategy'

Event Listeners Subscribe to bundle events for custom logic:

use DigitalBlueprint\RelaySublibraryConnectorBaseOrganizationBundle\Event\OrganizationSyncedEvent;

class CustomSyncListener
{
    public function onOrganizationSynced(OrganizationSyncedEvent $event)
    {
        // Trigger side effects after sync
    }
}

services:
    App\CustomSyncListener:
        tags:
            - { name: kernel.event_listener, event: organization.synced, method: onOrganizationSynced }

API Response Transformers Extend RelayResponseTransformer to modify API responses:

use DigitalBlueprint\RelaySublibraryConnectorBaseOrganizationBundle\Transformer\RelayResponseTransformerInterface;

class CustomResponseTransformer implements RelayResponseTransformerInterface
{
    public function transform(array $data, string $endpoint): array
    {
        $data['custom_metadata'] = ['

Relay Sublibrary Connector Base Organization Bundle Laravel Package