Itop Client Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Run composer require combodo/itop-client-bundle in your Laravel project (note: this bundle is Symfony-based, so use a Laravel-compatible bridge like spatie/laravel-symfony-support if needed).

2. Configuration Add the bundle’s config to config/services.php (or a custom config file):

   'itop' => [
       'servers' => [
           'itop_server_foo' => [
               'base_url' => env('ITOP_BASE_URL', 'https://itop.example.com'),
               'auth_user' => env('ITOP_AUTH_USER'),
               'auth_pwd' => env('ITOP_AUTH_PWD'),
               'extra_headers' => ['Accept' => 'application/json'],
           ],
       ],
   ],
   

   Publish the bundle’s config (if available) or manually define the service in config/services.php:

   'itop_client.rest_client.itop_server_foo' => \Combodo\ItopClientBundle\RestClient\RestClient::class,
   

3. First Use Case Inject the client into a service/controller and call an iTop operation:

   use Combodo\ItopClientBundle\RestClient\RestClient;
   use Combodo\ItopClientBundle\RestClient\RequestOperation\Core\RequestOperationCoreCreate;
   
   class MyController extends Controller {
       public function __construct(private RestClient $itopClient) {}
   
       public function createUser() {
           $operation = new RequestOperationCoreCreate();
           $operation->setData(['name' => 'John Doe', 'email' => 'john@example.com']);
           $response = $this->itopClient->execute('itop_server_foo', $operation);
           return response()->json($response);
       }
   }
   

Implementation Patterns

Core Workflows

1. Operation Execution

   • Use predefined RequestOperation* classes (e.g., RequestOperationCoreCreate, RequestOperationCoreSearch) for common CRUD operations.
   • Example for searching:

     $searchOp = new RequestOperationCoreSearch();
     $searchOp->setFilter(['name' => 'John']);
     $results = $this->itopClient->execute('itop_server_foo', $searchOp);
     

2. Dynamic Requests

   • For non-standard endpoints, use raw HTTP requests via the client:

     $response = $this->itopClient->get('itop_server_foo', '/api/core/search', ['filter' => ['name' => 'Test']]);
     

3. Service Integration

   • Laravel Service Providers: Bind the bundle’s services in AppServiceProvider:

     public function register() {
         $this->app->bind(RestClient::class, function ($app) {
             return new RestClient($app['config']['itop.servers.itop_server_foo']);
         });
     }
     

   • Dependency Injection: Inject RestClient directly into controllers/services.

4. Batch Operations

   • Use iTop’s bulk endpoints (e.g., /api/core/batch) for multi-record updates:

     $batchOp = new RequestOperationCoreBatch();
     $batchOp->setOperations([
         ['method' => 'create', 'data' => ['name' => 'User1']],
         ['method' => 'update', 'data' => ['id' => 123, 'name' => 'UpdatedUser']],
     ]);
     $this->itopClient->execute('itop_server_foo', $batchOp);
     

5. Event Listeners

   • Subscribe to iTop webhooks (if enabled) via Laravel’s HandleIncomingWebhook or a custom listener:

     use Illuminate\Http\Request;
     
     class iTopWebhookHandler {
         public function handle(Request $request) {
             $data = json_decode($request->getContent(), true);
             // Process iTop webhook data (e.g., trigger Laravel events)
         }
     }
     

Integration Tips

• Error Handling: Wrap execute() calls in try-catch blocks to handle iTop-specific errors (e.g., 400 Bad Request for invalid data):

  try {
      $response = $this->itopClient->execute('itop_server_foo', $operation);
  } catch (\Exception $e) {
      Log::error("iTop Error: " . $e->getMessage());
      return response()->json(['error' => 'iTop operation failed'], 500);
  }
  

• Logging: Log requests/responses for debugging:

  $this->itopClient->setLogger(function ($message) {
      Log::debug('iTop Client: ' . $message);
  });
  

• Caching: Cache frequent iTop responses (e.g., dropdown lists) using Laravel’s cache:

  $cacheKey = 'itop_dropdown_categories';
  $data = Cache::remember($cacheKey, 3600, function () {
      return $this->itopClient->get('itop_server_foo', '/api/core/dropdowns/categories');
  });
  

Gotchas and Tips

Pitfalls

1. Authentication Issues

   • Problem: Hardcoded credentials in config or incorrect permissions.
   • Fix: Use Laravel’s .env for credentials and ensure the iTop user has API access:

     # .env
     ITOP_AUTH_USER=api_user
     ITOP_AUTH_PWD=secure_password
     

   • Debug: Check iTop logs (/itop/logs/) for authentication failures.

2. Endpoint Mismatches

   • Problem: Using incorrect iTop REST endpoints (e.g., /api/core/create vs. /api/core/search).
   • Fix: Always refer to the iTop REST API docs. Example:

     // Wrong: Non-existent endpoint
     $this->itopClient->get('itop_server_foo', '/api/core/invalid');
     
     // Correct: Valid search endpoint
     $this->itopClient->get('itop_server_foo', '/api/core/search');
     

3. Data Format Errors

   • Problem: iTop rejects malformed JSON or missing required fields.
   • Fix: Validate data against iTop’s schema before sending. Example:

     $data = ['name' => 'Test', 'email' => 'test@example.com']; // Ensure 'email' is required
     $operation->setData($data);
     

4. Rate Limiting

   • Problem: iTop throttles requests during bulk operations.
   • Fix: Implement exponential backoff in Laravel:

     use Symfony\Component\Process\Exception\TimeoutException;
     
     try {
         $response = $this->itopClient->execute($server, $operation, ['timeout' => 30]);
     } catch (TimeoutException $e) {
         sleep(2); // Retry after delay
         retry();
     }
     

5. Bundle Version Mismatch

   • Problem: The bundle may not support newer iTop versions.
   • Fix: Check the iTop changelog and fork the bundle if needed.

Debugging Tips

1. Enable Verbose Logging

   • Set the client’s log level to DEBUG:

     $this->itopClient->setLoggerLevel(\Psr\Log\LogLevel::DEBUG);
     

   • Check Laravel logs (storage/logs/laravel.log) for raw HTTP requests/responses.

2. Inspect Headers

   • Add custom headers for debugging (e.g., X-Debug: true):

     # config/itop.php
     extra_headers:
         X-Debug: 'true'
         Accept: 'application/json'
     

3. Test with Postman/cURL

   • Replicate requests in Postman to isolate issues:

     curl -X POST "https://itop.example.com/api/core/create" \
          -H "Content-Type: application/json" \
          -u "api_user:secure_password" \
          -d '{"name": "Test"}'
     

4. Validate iTop Server

   • Test connectivity with a simple GET request:

     $response = $this->itopClient->get('itop_server_foo', '/api/core/version');
     

Extension Points

1. Custom Operations
   • Extend the bundle by creating your own RequestOperation classes:

     namespace App\Itop\Operations;
     
     use Combodo\ItopClientBundle\RestClient\RequestOperation;
     
     class CustomOperation extends RequestOperation {
         protected $endpoint = '/api/custom/endpoint';
         protected $method = 'POST';
     }
     

   • Register the class in Laravel’s service container:

     $this->app->bind(
         \App\Itop\Operations\CustomOperation::class,
         \App