Dtone Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ghanem/dtone
   php artisan vendor:publish --provider="Ghanem\Dtone\DtoneServiceProvider" --tag="config"
   

2. Configure .env: Add your API keys (production/sandbox) and set DTONE_IS_PRODUCTION to true/false.

   DTONE_KEY=your_prod_key
   DTONE_SECRET=your_prod_secret
   DTONE_IS_PRODUCTION=false
   

3. First Use Case: Fetch a customer list (example from API docs):

   use Ghanem\Dtone\Facades\Dtone;
   
   $customers = Dtone::customers()->list();
   dd($customers);
   

Where to Look First

• API Documentation: DT One DVS API Docs (maps directly to package methods).
• Facade: Ghanem\Dtone\Facades\Dtone (primary entry point).
• Config File: config/dtone.php (customize endpoints, retries, or logging).

Implementation Patterns

Core Workflows

1. API Resource Operations: Use fluent methods for CRUD operations. Example:

   // Create a customer
   $customer = Dtone::customers()->create([
       'name' => 'John Doe',
       'email' => 'john@example.com',
   ]);
   
   // Update a customer
   $customer->update(['email' => 'new@example.com']);
   
   // Delete a customer
   $customer->delete();
   

2. Pagination: Handle paginated responses with paginate():

   $customers = Dtone::customers()->paginate(10);
   foreach ($customers as $customer) {
       // Process each customer
   }
   

3. Webhooks: Validate incoming DT One webhooks using the validateWebhook helper:

   use Ghanem\Dtone\Helpers\Webhook;
   
   if (Webhook::validate($request->all())) {
       // Process webhook payload
   }
   

4. Error Handling: Wrap API calls in try-catch blocks:

   try {
       $response = Dtone::payments()->list();
   } catch (\Ghanem\Dtone\Exceptions\DtoneException $e) {
       Log::error('DT One API Error: ' . $e->getMessage());
       // Fallback logic
   }
   

Integration Tips

• Service Layer: Create a dedicated service class to abstract DT One logic:

  class DtoneCustomerService {
      public function __construct(private Dtone $dtone) {}
  
      public function fetchActiveCustomers() {
          return $this->dtone->customers()->list(['status' => 'active']);
      }
  }
  

• Event-Driven: Trigger Laravel events on DT One webhook payloads:

  event(new CustomerCreated($customerData));
  

• Testing: Use the sandbox environment (DTONE_IS_PRODUCTION=false) for tests:

  $this->app->singleton(Dtone::class, function ($app) {
      return new Dtone(config('dtone.sandbox'));
  });
  

Gotchas and Tips

Pitfalls

1. Environment Switching:

   • Forgetting to toggle DTONE_IS_PRODUCTION can lead to unexpected API calls to production.
   • Fix: Use a .env.local file for environment-specific overrides.

2. Rate Limiting:

   • DT One may throttle requests. Configure retries in .env:

     DTONE_RETRIES=3
     DTONE_RETRY_DELAY=500
     

3. Webhook Validation:

   • Always validate webhooks server-side. Client-side validation is insufficient.
   • Tip: Use Webhook::validate() and log failed validations for debugging.

4. Deprecated Methods:

   • The package is new (last release: 2026). Check for breaking changes in future updates by monitoring the GitHub repo.

Debugging

• Logging: Enable debug mode in config/dtone.php:

  'debug' => env('DTONE_DEBUG', false),
  

  Logs will appear in storage/logs/laravel.log.

• API Responses: Inspect raw responses for debugging:

  $response = Dtone::customers()->list();
  dd($response->original); // Raw HTTP response
  

Extension Points

1. Custom Endpoints: Extend the package by adding new API endpoints:

   // In a service provider
   $this->app->extend(Dtone::class, function ($dtone) {
       $dtone->extend('customers/bulk', function ($api) {
           return new CustomBulkCustomerApi($api);
       });
       return $dtone;
   });
   

2. Middleware: Add middleware to modify requests/responses:

   Dtone::middleware(function ($request) {
       $request->header('X-Custom-Header', 'value');
   });
   

3. Testing: Mock the DT One API in tests:

   $this->mock(Dtone::class, function ($mock) {
       $mock->shouldReceive('customers')
            ->andReturnSelf()
            ->shouldReceive('list')
            ->andReturn(['data' => []]);
   });
   

Config Quirks

• Retry Logic: Retries are exponential by default. Adjust DTONE_RETRY_DELAY (in milliseconds) for aggressive/fine-tuned retries.
• Timeouts: The package uses Laravel’s HTTP client defaults. Override in config/dtone.php:

  'timeout' => 30, // seconds