Wubookapi Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require kamwoz/wubookapi-bundle "dev-master"
   

   Register the bundle in AppKernel.php:

   new Kamwoz\WubookAPIBundle\WubookAPIBundle(),
   

2. Configuration Add credentials to config/parameters.yml:

   parameters:
       wubook_api.client_username: your_wubook_username
       wubook_api.client_password: your_wubook_password
   

   Configure the bundle in config/config.yml:

   wubook_api:
       client_username: %wubook_api.client_username%
       client_password: %wubook_api.client_password%
       provider_key: ~ # Obtain from Wubook support
       property_id: ~ # From your Wubook account
   

3. First Use Case Fetch provider info (requires valid token):

   use Kamwoz\WubookAPIBundle\Service\WubookAPI;
   
   $wubook = $this->get('wubook_api');
   $providerInfo = $wubook->providerInfo();
   

Implementation Patterns

Token Management

• Automatic Handling: The bundle auto-manages tokens via cache. No manual token storage needed.
• Validation Check:

  if (!$wubook->isTokenValid()) {
      $wubook->acquireToken(); // Auto-retrieves if invalid
  }
  

Common Workflows

1. Room Management

   // Fetch rooms
   $rooms = $wubook->fetchRooms();
   
   // Create a new room
   $newRoom = $wubook->newRoom([
       'name' => 'Deluxe Suite',
       'price' => 200.00,
       'description' => 'Luxury room',
   ]);
   

2. Booking Operations

   // Fetch bookings
   $bookings = $wubook->fetchBookings(['start_date' => '2023-12-01']);
   
   // Cancel a reservation
   $wubook->cancelReservation($bookingId);
   

3. Availability Updates

   // Update availability (sparse)
   $wubook->updateSparseAvail($roomId, [
       ['date' => '2023-12-01', 'available' => true],
       ['date' => '2023-12-02', 'available' => false],
   ]);
   

Integration Tips

• Dependency Injection: Inject WubookAPI service into controllers/services:

  public function __construct(WubookAPI $wubook) {
      $this->wubook = $wubook;
  }
  

• Error Handling: Wrap API calls in try-catch:

  try {
      $data = $wubook->fetchBookings();
  } catch (\Exception $e) {
      $this->addFlash('error', 'Wubook API error: ' . $e->getMessage());
  }
  

• Async Operations: Use push_url for webhook callbacks:

  $wubook->pushUrl('https://yourdomain.com/webhook', 'booking_created');
  

Gotchas and Tips

Pitfalls

1. Token Expiry

   • The bundle caches tokens but doesn’t auto-refresh silently. Always check isTokenValid() before critical operations.
   • Fix: Implement a retry logic for failed requests:

     if (!$wubook->isTokenValid()) {
         $wubook->acquireToken();
         retry($attempts = 3);
     }
     

2. Missing Methods

   • Not all Wubook API endpoints are implemented. Refer to the Wubook API docs for unsupported methods.
   • Workaround: Extend the bundle or use raw HTTP requests as a fallback.

3. Configuration Sensitivity

   • provider_key and property_id are mandatory but not auto-generated. Contact Wubook support for these values.
   • Tip: Store sensitive params in environment variables (e.g., .env) and reference them in parameters.yml:

     wubook_api.provider_key: "%env(WUBOOK_PROVIDER_KEY)%"
     

4. Rate Limiting

   • Wubook’s API has rate limits. Avoid rapid successive calls (e.g., in loops).
   • Tip: Add delays between batch operations:

     sleep(1); // Pause between API calls
     

Debugging

• Enable Debug Mode: Set debug: true in config to log raw API responses:

  wubook_api:
      debug: true
  

  Check logs in var/log/dev.log.

• HTTP Client Errors: Use Symfony’s HttpClient for debugging:

  $client = $this->get('http_client');
  $response = $client->request('GET', 'https://api.wubook.net/...');
  

Extension Points

1. Custom Endpoints Extend the service by creating a decorator:

   class CustomWubookAPI extends WubookAPI {
       public function customMethod() {
           return $this->makeRequest('custom_endpoint', [], 'POST');
       }
   }
   

   Register the decorator in services.yml:

   services:
       custom_wubook_api:
           class: AppBundle\Service\CustomWubookAPI
           decorates: wubook_api
   

2. Event Listeners Listen for booking events via push_url webhooks. Example in a controller:

   public function handleWebhook(Request $request) {
       $data = json_decode($request->getContent(), true);
       // Process $data (e.g., new booking, cancellation)
   }
   

3. Testing Mock the WubookAPI service in PHPUnit:

   $mock = $this->createMock(WubookAPI::class);
   $mock->method('fetchRooms')->willReturn([...]);
   $this->container->set('wubook_api', $mock);