Php Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require hivelink/php
   

   Add the service provider and facade to config/app.php:

   'providers' => [
       // ...
       HiveLink\HiveLinkServiceProvider::class,
   ],
   'aliases' => [
       // ...
       'HiveLink' => HiveLink\Facades\HiveLink::class,
   ],
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="HiveLink\HiveLinkServiceProvider"
   

   Update .env with your API credentials:

   HIVE_LINK_API_KEY=your_api_key
   HIVE_LINK_API_SECRET=your_api_secret
   

3. First Use Case Send a basic SMS:

   use HiveLink\Facades\HiveLink;
   
   HiveLink::send([
       'to' => '989123456789',
       'text' => 'Hello from HiveLink!'
   ]);
   

Where to Look First

• Documentation: HiveLink SMS API Docs
• Config File: config/hivelink.php (for API settings, retries, logging)
• Facade: HiveLink:: for quick method calls
• Service Container: Bind custom configurations if needed.

Implementation Patterns

Core Workflows

1. Sending SMS Use the facade for simplicity:

   HiveLink::send([
       'to' => '989123456789',
       'text' => 'Your OTP is {code}.',
       'variables' => ['code' => '123456']
   ]);
   

2. OTP Management Generate and verify OTPs:

   // Generate OTP
   $otp = HiveLink::otp()->generate([
       'to' => '989123456789',
       'length' => 6,
       'expire_after' => 300 // 5 minutes
   ]);
   
   // Verify OTP
   $result = HiveLink::otp()->verify($otp['id'], '123456');
   

3. Batch Processing Send SMS to multiple recipients:

   $recipients = ['989123456789', '989123456780'];
   $text = 'Hello!';
   
   HiveLink::batch($recipients, $text);
   

Integration Tips

• Queue Jobs: Wrap API calls in Laravel queues for async processing:

  dispatch(new SendHiveLinkSmsJob($recipient, $message));
  

• Logging: Enable logging in config/hivelink.php to debug failed requests.
• Error Handling: Use try-catch with HiveLinkException:

  try {
      HiveLink::send([...]);
  } catch (\HiveLink\Exceptions\HiveLinkException $e) {
      Log::error($e->getMessage());
  }
  

Advanced Patterns

• Custom HTTP Client: Bind a custom Guzzle client for retry logic:

  $client = new \GuzzleHttp\Client(['timeout' => 10]);
  $this->app->bind(\GuzzleHttp\Client::class, fn() => $client);
  

• Middleware: Add middleware to modify requests/responses globally.

Gotchas and Tips

Common Pitfalls

1. API Key/Secret Mismatch

   • Ensure .env values match the HiveLink dashboard.
   • Test with HiveLink::config('api_key') to verify.

2. Character Limits

   • SMS length is capped at 160 characters (GSM-7 encoding). Use Unicode for Persian/Arabic (70 chars per segment).
   • Split long messages automatically:

     HiveLink::send([
         'to' => '989123456789',
         'text' => str_repeat('a', 200) // Auto-split
     ]);
     

3. OTP Expiry

   • OTPs expire by default after 5 minutes. Adjust with expire_after (seconds).
   • Verify OTPs before they expire to avoid failures.

4. Rate Limits

   • HiveLink enforces 1 request/second by default. Use batching or queues for high volumes.

Debugging Tips

• Enable Debug Mode:

  HiveLink::setDebug(true); // Logs raw requests/responses
  

• Check Response Codes:

  • 200: Success.
  • 400: Invalid parameters (e.g., malformed phone number).
  • 401: API key/auth failure.
  • 429: Rate limit exceeded.

• Phone Number Format:

  • Use international format (e.g., +989123456789).
  • Remove 0 or + inconsistencies:

    $phone = preg_replace('/[^0-9]/', '', '09123456789'); // => '9123456789'
    

Extension Points

1. Custom Responses Override the default response handler:

   HiveLink::extend(function ($response) {
       return json_decode($response->getBody(), true);
   });
   

2. Webhook Integration Use the HiveLink::webhook() method to listen for delivery reports:

   HiveLink::webhook()->listen('sms_delivered', function ($data) {
       Log::info('SMS delivered to: ' . $data['to']);
   });
   

3. Testing Mock the client in PHPUnit:

   $mock = Mockery::mock(\GuzzleHttp\Client::class);
   $this->app->instance(\GuzzleHttp\Client::class, $mock);