Laravel Notification Fax Ir Laravel Package

Getting Started

Minimal Setup

1. Install the Package Run:

   composer require grschannel/laravel-faxir-notification
   

   Publish the config file:

   php artisan vendor:publish --provider="Grschannel\FaxirNotification\FaxirNotificationServiceProvider" --tag="config"
   

2. Configure .env Add your Fax.ir API credentials:

   FAXIR_API_KEY=your_api_key_here
   FAXIR_API_SECRET=your_api_secret_here
   

3. First Use Case: Sending a Fax Use the FaxirChannel in a notification class:

   use Grschannel\FaxirNotification\Channels\FaxirChannel;
   
   class InvoiceFaxNotification extends Notification
   {
       public function via($notifiable)
       {
           return [FaxirChannel::class];
       }
   
       public function toFaxir($notifiable)
       {
           return (new FaxirMessage())
               ->to('[email protected]') // Fax.ir recipient email
               ->subject('Invoice Notification')
               ->content('Your invoice details: ...');
       }
   }
   

Implementation Patterns

Workflows

1. Integrating with Notifications

   • Extend Laravel’s Notification class and use FaxirChannel in the via() method.
   • Override toFaxir() to customize the fax content (subject, body, attachments).

2. Dynamic Recipient Handling

   • Use $notifiable->fax_number or a custom attribute to fetch recipients dynamically:

     public function toFaxir($notifiable)
     {
         return (new FaxirMessage())
             ->to($notifiable->fax_number)
             ->subject('Dynamic Subject');
     }
     

3. Attachments

   • Attach PDFs or documents via the attach() method:

     public function toFaxir($notifiable)
     {
         return (new FaxirMessage())
             ->to('[email protected]')
             ->attach(storage_path('app/invoice.pdf'));
     }
     

4. Queueing Faxes

   • Dispatch notifications with the queue method to avoid blocking:

     $user->notify((new InvoiceFaxNotification())->queue());
     

Integration Tips

• Laravel Queues: Ensure your queue worker (php artisan queue:work) is running for async fax delivery.
• Logging: Use Laravel’s logging to track fax failures:

  try {
      $user->notify(new InvoiceFaxNotification());
  } catch (\Exception $e) {
      \Log::error("Fax failed: " . $e->getMessage());
  }
  

• Testing: Mock the FaxirChannel in unit tests:

  $this->fake()->fake(FaxirChannel::class);
  

Gotchas and Tips

Pitfalls

1. API Credentials

   • Hardcoding FAXIR_API_KEY/FAXIR_API_SECRET in .env is insecure. Use Laravel’s environment variables or a secrets manager.

2. Recipient Format

   • Fax.ir expects recipient emails (e.g., [email protected]), not phone numbers. Verify the API docs for exact requirements.

3. Attachment Limits

   • Check Fax.ir’s API limits (e.g., max file size, allowed formats). The package may not enforce these by default.

4. Queue Failures

   • If faxes fail silently, enable Laravel’s queue failure channels:

     'failed' => [
         'database' => env('DB_CONNECTION', 'mysql'),
     ],
     

     in config/queue.php.

Debugging

• Enable Debug Mode: Set FAXIR_DEBUG=true in .env to log API responses.
• Check HTTP Status Codes: Use Laravel’s Http facade to inspect responses:

  \Log::debug('Faxir Response:', [
      'status' => $response->status(),
      'body'   => $response->body(),
  ]);
  

Extension Points

1. Customize the Channel Override the send() method in a service provider to add logic:

   public function boot()
   {
       $this->app->bind(FaxirChannel::class, function ($app) {
           return new CustomFaxirChannel($app['config']['services.faxir']);
       });
   }
   

2. Add Retry Logic Extend the channel to retry failed faxes:

   use Illuminate\Support\Facades\Retry;
   
   public function send($notifiable, $message)
   {
       Retry::times(3)->attempt(function () use ($notifiable, $message) {
           // Original send logic here
       });
   }
   

3. Webhook Integration Use Fax.ir’s webhooks to track delivery status. Store the webhook secret in config and validate requests in a route:

   Route::post('/faxir-webhook', function (Request $request) {
       if ($request->header('X-Signature') !== config('services.faxir.webhook_secret')) {
           abort(403);
       }
       // Process webhook data
   });