Dtone Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require mohamedhamdy5/dtone
   

   Publish the config file:

   php artisan vendor:publish --provider="Hamdy\Dtone\DtoneServiceProvider"
   

2. Configuration Edit .env with your DT One API credentials:

   DTONE_API_KEY=your_api_key_here
   DTONE_API_SECRET=your_api_secret_here
   DTONE_BASE_URL=https://api.dtone.com
   

3. First Use Case Initialize the client in a service or controller:

   use Hamdy\Dtone\Facades\Dtone;
   
   $client = Dtone::client();
   

   Fetch a test response (verify connectivity):

   $response = $client->get('/v1/accounts');
   

Implementation Patterns

Core Workflows

1. API Client Initialization Use the facade for simplicity:

   $client = Dtone::client(['timeout' => 30]);
   

   Or inject the service directly into a service provider:

   $this->app->bind('dtone.client', function ($app) {
       return new \Hamdy\Dtone\DtoneClient($app['config']['dtone']);
   });
   

2. Handling API Responses Wrap API calls in a service layer for consistency:

   class DtoneService {
       protected $client;
   
       public function __construct(DtoneClient $client) {
           $this->client = $client;
       }
   
       public function fetchAccount($accountId) {
           return $this->client->get("/v1/accounts/{$accountId}");
       }
   }
   

3. Webhook Integration Validate and process DT One webhooks in a middleware:

   public function handle(Request $request, Closure $next) {
       $payload = $request->getContent();
       $signature = $request->header('X-Dtone-Signature');
   
       if (!Dtone::validateWebhook($payload, $signature)) {
           abort(403, 'Invalid webhook signature');
       }
   
       return $next($request);
   }
   

4. Error Handling Centralize error responses:

   try {
       $response = $client->post('/v1/transactions', $data);
   } catch (\Hamdy\Dtone\Exceptions\DtoneException $e) {
       Log::error("DT One API Error: " . $e->getMessage());
       return response()->json(['error' => 'Payment failed'], 400);
   }
   

Gotchas and Tips

Common Pitfalls

1. Authentication Failures

   • Ensure DTONE_API_KEY and DTONE_API_SECRET are correctly set in .env.
   • Verify the API credentials have the required permissions in the DT One dashboard.
   • Debug with:

     Dtone::client()->get('/v1/accounts')->dump();
     

2. Webhook Validation

   • Always validate webhook signatures to prevent spoofing.
   • Use the provided validateWebhook() method:

     Dtone::validateWebhook($payload, $signature);
     

   • Store the secret key securely (e.g., in .env).

3. Rate Limiting

   • DT One may enforce rate limits. Implement exponential backoff in retries:

     use Symfony\Component\HttpClient\RetryableHttpClient;
     
     $client = new RetryableHttpClient(
         Dtone::client()->getHttpClient(),
         [
             'max_retries' => 3,
             'delay' => 1000,
             'multiplier' => 2,
         ]
     );
     

4. Endpoint Changes

   • The package assumes DT One’s API endpoints are stable. Monitor the DT One API docs for updates and adjust calls accordingly.

Debugging Tips

• Enable Debug Mode Set DTONE_DEBUG=true in .env to log raw API requests/responses.

• Inspect Headers Add custom headers for debugging:

  $client->withHeaders(['X-Debug' => 'true']);
  

• Mocking for Tests Use Laravel’s HTTP client mocking:

  $this->mock(DtoneClient::class, function ($mock) {
      $mock->shouldReceive('get')->andReturn(['data' => 'mocked']);
  });
  

Extension Points

1. Custom HTTP Client Override the default Guzzle client in config/dtone.php:

   'http_client' => \App\Services\CustomHttpClient::class,
   

2. Response Transformers Extend the DtoneResponse class to modify responses:

   class CustomDtoneResponse extends \Hamdy\Dtone\DtoneResponse {
       public function transform() {
           return parent::transform()->merge(['custom_field' => 'value']);
       }
   }
   

   Bind it in a service provider:

   $this->app->bind(\Hamdy\Dtone\DtoneResponse::class, CustomDtoneResponse::class);
   

3. Event Listeners Dispatch custom events for webhooks:

   event(new \App\Events\DtoneWebhookReceived($payload));