Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require hivelink/laravel
   

2. Register Service Provider in config/app.php:

   'providers' => [
       // ...
       Hivelink\Laravel\ServiceProvider::class,
   ],
   

3. Add Facade Alias in config/app.php:

   'aliases' => [
       // ...
       'Hivelink' => Hivelink\Laravel\Facade::class,
   ],
   

4. Publish Config (if needed):

   php artisan vendor:publish --provider="Hivelink\Laravel\ServiceProvider"
   

   This generates config/hivelink.php.

5. Configure API Key in .env:

   HIVE_LINK_API_KEY=your_api_key_here
   

First Use Case: Sending an SMS

use Hivelink\Facades\Hivelink;

Hivelink::sms()
    ->to('2348012345678')
    ->message('Hello from Laravel!')
    ->send();

Implementation Patterns

Core Workflows

1. SMS Operations

• Send SMS:

  Hivelink::sms()
      ->to('2348012345678')
      ->message('Your OTP is 12345')
      ->send();
  

• Schedule SMS (via Laravel Queues):

  Hivelink::sms()
      ->to('2348012345678')
      ->message('Scheduled message')
      ->schedule(Carbon::now()->addMinutes(10))
      ->send();
  

2. Inquiry API (Balance/Usage)

• Check Balance:

  $balance = Hivelink::inquiry()->balance();
  

• Fetch Usage:

  $usage = Hivelink::inquiry()->usage();
  

3. Transaction Logging

• Log Sent SMS (auto-enabled if HIVE_LINK_LOG_ENABLED=true in .env):

  // Logs to `hivelink_logs` table by default
  

4. Error Handling

• Custom Error Handling:

  try {
      Hivelink::sms()->to('2348012345678')->message('Test')->send();
  } catch (\Hivelink\Exceptions\HivelinkException $e) {
      Log::error('Hivelink Error: ' . $e->getMessage());
  }
  

Integration Tips

1. Queue-Based SMS

• Configure HIVE_LINK_QUEUE_CONNECTION in .env (e.g., database, redis).
• Use send() to dispatch jobs asynchronously.

2. Rate Limiting

• Implement middleware to throttle requests:

  use Hivelink\Facades\Hivelink;
  
  Route::middleware(['throttle:10,1'])->group(function () {
      Route::post('/send-sms', function () {
          Hivelink::sms()->to('2348012345678')->message('Test')->send();
      });
  });
  

3. Dynamic API Key

• Load API key from a secure source (e.g., AWS Secrets Manager):

  config(['hivelink.api_key' => getApiKeyFromSecureSource()]);
  

4. Testing

• Mock the facade in tests:

  Hivelink::shouldReceive('sms')
      ->once()
      ->andReturnSelf()
      ->shouldReceive('send')
      ->once();
  

Gotchas and Tips

Pitfalls

1. API Key Exposure:

   • Never hardcode keys in .env for production. Use environment variables or secret managers.
   • Validate HIVE_LINK_API_KEY exists in config/hivelink.php:

     'api_key' => env('HIVE_LINK_API_KEY') ?: throw new \RuntimeException('API key not set'),
     

2. Queue Failures:

   • Ensure HIVE_LINK_QUEUE_CONNECTION is properly configured. Monitor failed jobs in failed_jobs table.

3. Rate Limits:

   • Hivelink may throttle requests. Implement retries with exponential backoff:

     use Hivelink\Facades\Hivelink;
     
     $attempts = 0;
     $maxAttempts = 3;
     do {
         try {
             Hivelink::sms()->to('2348012345678')->message('Test')->send();
             break;
         } catch (\Hivelink\Exceptions\RateLimitException $e) {
             $attempts++;
             sleep(2 ** $attempts);
         }
     } while ($attempts < $maxAttempts);
     

4. Logging Overhead:

   • Disable logging in production if not needed (HIVE_LINK_LOG_ENABLED=false).

Debugging Tips

1. Enable Debug Mode:

   HIVE_LINK_DEBUG=true
   

   • Logs raw API responses to storage/logs/hivelink.log.

2. Check HTTP Status Codes:

   • Wrap calls in try-catch to inspect HivelinkException for HTTP errors (e.g., 401 Unauthorized).

3. Validate Phone Numbers:

   • Use Laravel Validation:

     $request->validate(['phone' => 'required|string|hivelink_phone']);
     

   • Add a custom rule:

     Validator::extend('hivelink_phone', function ($attribute, $value) {
         return preg_match('/^\+\d{10,15}$/', $value);
     });
     

Extension Points

1. Custom Responses:

   • Override the facade to extend functionality:

     class CustomHivelink extends \Hivelink\Laravel\Facade {
         public static function bulkSend(array $messages) {
             // Custom logic
         }
     }
     

2. Webhook Integration:

   • Listen for Hivelink webhook events (e.g., delivery reports):

     Route::post('/hivelink-webhook', function (Request $request) {
         $payload = $request->json()->all();
         // Process delivery status, etc.
     });
     

3. Template Management:

   • Store SMS templates in the database and fetch dynamically:

     $template = DB::table('sms_templates')->where('key', 'welcome')->first();
     Hivelink::sms()->to('2348012345678')->message($template->content)->send();
     

4. Fallback Mechanisms:

   • Implement fallback to another SMS provider if Hivelink fails:

     try {
         Hivelink::sms()->to('2348012345678')->message('Fallback')->send();
     } catch (\Exception $e) {
         // Fallback to Twilio, etc.
     }