Woo Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require common-gateway/woo-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       CommonGateway\WooBundle\WooBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="CommonGateway\WooBundle\WooBundle" --tag="config"
   

   Edit config/woo.php to define:

   • open_index_endpoint (API URL)
   • koop_integration (boolean)
   • sync_cron_schedule (e.g., '* * * * *' for every minute)
   • default_publication_categories

3. First Use Case Sync a single publication manually:

   use CommonGateway\WooBundle\Service\PublicationService;
   
   $publicationService = app(PublicationService::class);
   $publication = $publicationService->syncFromOpenIndex('woo:publication:123');
   

Implementation Patterns

Core Workflows

1. Synchronization

   • Scheduled Syncs: Use Laravel's task scheduling in app/Console/Kernel.php:

     $schedule->command('woo:sync')->everyMinute();
     

   • Manual Syncs: Trigger via CLI:

     php artisan woo:sync
     

   • Incremental Syncs: Configure sync_strategy in woo.php:

     'sync_strategy' => 'incremental', // or 'full'
     

2. Querying Publications

   • Basic Query:

     $publications = $publicationService->search([
         'category' => 'wetgeving',
         'limit' => 10,
     ]);
     

   • Federated Search (via KOOP):

     $federatedResults = $publicationService->federatedSearch('wetgeving', ['koophulpje']);
     

3. Event-Driven Updates

   • Listen for sync events in EventServiceProvider:

     protected $listen = [
         'CommonGateway\WooBundle\Events\PublicationSynced' => [
             'App\Listeners\LogPublicationSync',
         ],
     ];
     

4. Custom Data Mapping

   • Extend the default PublicationTransformer:

     use CommonGateway\WooBundle\Transformer\PublicationTransformer;
     
     class CustomPublicationTransformer extends PublicationTransformer
     {
         public function transform($data)
         {
             $data = parent::transform($data);
             $data['custom_field'] = $this->extractCustomField($data);
             return $data;
         }
     }
     

   • Bind the transformer in WooBundle config:

     'transformer' => App\Transformer\CustomPublicationTransformer::class,
     

Integration Tips

1. Database Schema

   • The bundle uses Eloquent models (Publication, PublicationCategory). Extend them if needed:

     class Publication extends \CommonGateway\WooBundle\Entity\Publication
     {
         protected $casts = [
             'metadata' => 'array',
             'tags' => 'collection',
         ];
     }
     

2. API Clients

   • Override the default OpenIndexClient for custom API logic:

     use CommonGateway\WooBundle\Client\OpenIndexClient;
     
     class CustomOpenIndexClient extends OpenIndexClient
     {
         public function fetchPublications(array $query)
         {
             // Custom logic
             return parent::fetchPublications($query);
         }
     }
     

   • Bind the client in WooBundle config:

     'clients' => [
         'open_index' => App\Client\CustomOpenIndexClient::class,
     ],
     

3. Caching

   • Enable Redis caching for sync results:

     'cache' => [
         'enabled' => true,
         'driver' => 'redis',
         'ttl' => 3600, // 1 hour
     ],
     

4. Testing

   • Use the WooBundleTestCase base class:

     use CommonGateway\WooBundle\Tests\WooBundleTestCase;
     
     class PublicationServiceTest extends WooBundleTestCase
     {
         public function testSyncPublication()
         {
             // Test logic
         }
     }
     

Gotchas and Tips

Pitfalls

1. Sync Conflicts

   • Issue: Duplicate entries during incremental syncs if updated_at timestamps are inconsistent.
   • Fix: Implement a custom PublicationRepository to handle conflicts:

     class CustomPublicationRepository extends \CommonGateway\WooBundle\Repository\PublicationRepository
     {
         public function findOrCreate(array $attributes)
         {
             $existing = $this->findByExternalId($attributes['external_id']);
             if ($existing && $existing->updated_at > Carbon::parse($attributes['updated_at'])) {
                 return $existing; // Skip if local version is newer
             }
             return parent::findOrCreate($attributes);
         }
     }
     

   • Bind the repository in WooBundle config:

     'repositories' => [
         'publication' => App\Repository\CustomPublicationRepository::class,
     ],
     

2. KOOP Integration

   • Issue: KOOP API rate limits may throttle requests.
   • Fix: Configure retry logic in koop_client:

     'koop_integration' => [
         'enabled' => true,
         'retry_attempts' => 3,
         'retry_delay' => 1000, // ms
     ],
     

3. Category Mapping

   • Issue: Mismatched categories between Open Index and your local system.
   • Fix: Use a custom CategoryMapper:

     use CommonGateway\WooBundle\Mapper\CategoryMapper;
     
     class CustomCategoryMapper extends CategoryMapper
     {
         protected function getLocalCategory(string $externalCategory): ?string
         {
             $mapping = [
                 'wetgeving' => 'wetten-en-regels',
                 'besluiten' => 'overheidsbesluiten',
             ];
             return $mapping[$externalCategory] ?? null;
         }
     }
     

   • Bind the mapper in WooBundle config:

     'mappers' => [
         'category' => App\Mapper\CustomCategoryMapper::class,
     ],
     

4. Performance

   • Issue: Slow syncs for large datasets.
   • Fix: Batch processing in sync_strategy:

     'sync_strategy' => [
         'batch_size' => 50,
         'chunk' => true,
     ],
     

Debugging Tips

1. Enable Logging Add to config/logging.php:

   'channels' => [
       'woo' => [
           'driver' => 'single',
           'path' => storage_path('logs/woo.log'),
           'level' => 'debug',
       ],
   ],
   

   Then configure in woo.php:

   'logging' => [
       'channel' => 'woo',
       'level' => 'debug',
   ],
   

2. API Debugging

   • Use the --debug flag for CLI commands:

     php artisan woo:sync --debug
     

   • Inspect raw API responses with:

     $client = app(\CommonGateway\WooBundle\Client\OpenIndexClient::class);
     $response = $client->fetchPublications([], true); // $debug = true
     

3. Database Debugging

   • Enable query logging in .env:

     DB_LOG_QUERIES=true
     

   • Use Laravel Debugbar to inspect queries and models.

Extension Points

1. Custom Fields

   • Extend the Publication model to add custom fields:

     class Publication extends \CommonGateway\WooBundle\Entity\Publication
     {
         protected $fillable = ['custom_field'];
     }
     

   • Update the transformer to handle the new field:

     public function transform($data)
     {
         $data['custom_field'] = $data['raw_data']['custom_field'] ?? null;
         return parent::transform($data);
     }
     

2. Webhooks

   • Listen for external webhook updates:

     Route::post('/webhook/woo', function (Request $request) {
         $publicationService = app(PublicationService::class);
         $publicationService->handleWebhook($request->all());
     });
     

3. Custom Sync Sources

   • Add support for additional data sources (e.g., CSV, database):

     use CommonGateway\WooBundle\Sync