Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require linepayamak/laravel
   composer dump-autoload
   

2. Register Provider Add to config/app.php under Package Service Providers:

   LinePayamak\Support\Laravel\ServiceProvider::class,
   

3. Publish Config

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

   Update .env with your LinePayamak credentials (e.g., LINEPAYAMAK_USERNAME, LINEPAYAMAK_PASSWORD).

4. First Use Case Fetch remaining credit in a controller:

   use LinePayamak\Support\Laravel\Facade as LinePayamak;
   
   public function checkCredit()
   {
       $credit = LinePayamak::GetCredit();
       return response()->json(['credit' => $credit]);
   }
   

Implementation Patterns

Core Workflows

1. Service Initialization

   • Use the facade (LinePayamak::method()) for simplicity or resolve the service manually:

     $client = resolve('LinePayamak');
     $client->SendSMS($to, $message);
     

2. SMS Sending

   LinePayamak::SendSMS(
       $recipient,  // e.g., '09123456789'
       $message,    // string
       $senderID?   // optional, e.g., 'MyBrand'
   );
   

3. Balance Management

   $balance = LinePayamak::GetCredit(); // Returns remaining credit
   LinePayamak::GetLastError();         // Check for errors after operations
   

4. Batch Operations For bulk SMS, loop and handle errors:

   foreach ($recipients as $phone) {
       $result = LinePayamak::SendSMS($phone, 'Hello!');
       if ($result !== true) {
           Log::error("Failed to send to $phone: " . LinePayamak::GetLastError());
       }
   }
   

5. Integration with Queues Dispatch SMS jobs to avoid timeouts:

   SendSMSJob::dispatch($recipient, $message)->onQueue('sms');
   

   (Note: Requires custom job class; package doesn’t natively support queues.)

Advanced Patterns

1. Customizing Requests Override the default SOAP client in config/linepayamak.php:

   'soap_options' => [
       'trace' => 1, // Enable for debugging
       'exceptions' => true,
   ],
   

2. Logging Responses Extend the service provider to log all requests/responses:

   // In a custom service provider
   $this->app->extend('LinePayamak', function ($client) {
       $client->setLogger(app(\Psr\Log\LoggerInterface::class));
       return $client;
   });
   

3. Testing Mock the SOAP client in tests:

   $mock = Mockery::mock('LinePayamak\Support\LinePayamakClient');
   $mock->shouldReceive('SendSMS')->andReturn(true);
   $this->app->instance('LinePayamak', $mock);
   

Gotchas and Tips

Pitfalls

1. SOAP Extension Missing

   • Error: Class 'SoapClient' not found.
   • Fix: Enable extension=soap in php.ini and restart PHP.

2. Character Limits

   • LinePayamak enforces a 300-character limit per SMS. Longer messages auto-split (but may incur extra costs).
   • Tip: Use mb_strlen() to validate message length:

     if (mb_strlen($message, 'UTF-8') > 300) {
         throw new \InvalidArgumentException('Message exceeds 300 characters.');
     }
     

3. Error Handling

   • GetLastError() only captures the last operation’s error. Clear it after checking:

     $result = LinePayamak::SendSMS($to, $msg);
     if (!$result) {
         $error = LinePayamak::GetLastError();
         LinePayamak::ClearLastError(); // Reset for next call
         throw new \RuntimeException($error);
     }
     

4. Rate Limits

   • Unofficial limits: ~1 SMS/sec. Throttle requests to avoid 503 errors:

     sleep(1); // Delay between bulk SMS sends
     

5. UTF-8 Encoding

   • Issue: Non-Latin characters (e.g., Persian) may corrupt.
   • Fix: Ensure messages are UTF-8 encoded:

     $message = mb_convert_encoding($message, 'UTF-8');
     

Tips

1. Configuration

   • Store API credentials in .env:

     LINEPAYAMAK_USERNAME=your_username
     LINEPAYAMAK_PASSWORD=your_password
     LINEPAYAMAK_SENDER_ID=YourBrand
     

2. Debugging SOAP Enable trace in config/linepayamak.php to log raw SOAP requests/responses:

   'soap_options' => ['trace' => 1],
   

   Access logs via:

   $client = resolve('LinePayamak');
   $logs = $client->getSoapClient()->__getLastRequest();
   

3. Extending Functionality

   • Add custom methods to the facade by extending the service:

     // In a custom service provider
     $this->app->extend('LinePayamak', function ($client) {
         $client->setCustomMethod(function ($params) {
             return $client->__soapCall('CustomMethod', [$params]);
         });
         return $client;
     });
     

4. Fallback for Failures Implement a retry mechanism for transient failures:

   use Illuminate\Support\Facades\Retry;
   
   Retry::times(3)->attempt(function () {
       LinePayamak::SendSMS($to, $msg);
   });
   

5. Documentation Gaps

   • The package lacks docs for all SOAP methods. Refer to LinePayamak’s API docs (Persian) for unsupported methods.
   • Workaround: Use __soapCall() directly:

     $client->__soapCall('UnsupportedMethod', [$params]);