Advcash Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require volkandm/advcash
   

2. Configure .env:

   ADVCASH_API_NAME=your_api_name
   ADVCASH_API_EMAIL=your_api_email
   ADVCASH_API_PASS=your_api_password
   

3. First Use Case: Send money via a controller or service:

   use Volkandm\Advcash\Advcash;
   
   $adv = new Advcash();
   $response = $adv->SendMoney(1, "user@example.com", "USD", "Payment for service");
   

Where to Look First

• Source Code: Review src/Advcash.php for available methods and logic.
• Environment Variables: Ensure .env is correctly populated.
• Response Handling: Check the SendMoney() return structure (success and response keys).

Implementation Patterns

Core Workflow

1. Service Layer Integration: Create a dedicated service class to abstract AdvCash logic:

   namespace App\Services;
   
   use Volkandm\Advcash\Advcash;
   
   class AdvCashService {
       protected $advCash;
   
       public function __construct() {
           $this->advCash = new AdvCash();
       }
   
       public function sendPayment($amount, $recipient, $currency, $note) {
           return $this->advCash->SendMoney($amount, $recipient, $currency, $note);
       }
   }
   

2. Dependency Injection: Bind the service in AppServiceProvider:

   public function register() {
       $this->app->singleton(AdvCashService::class, function ($app) {
           return new AdvCashService();
       });
   }
   

3. Controller Usage:

   public function sendPayment(Request $request, AdvCashService $service) {
       $response = $service->sendPayment(
           $request->amount,
           $request->recipient,
           $request->currency,
           $request->note
       );
   
       return response()->json($response);
   }
   

Integration Tips

• Validation: Validate amount, recipient, and currency before calling SendMoney().
• Logging: Log responses for debugging:

  \Log::info('AdvCash Response', $response);
  

• Error Handling: Check $response['success'] and handle failures gracefully:

  if ($response['success'] === 0) {
      throw new \Exception($response['response']);
  }
  

Gotchas and Tips

Pitfalls

1. No Facade Support: The package lacks a facade, so instantiate Advcash manually or create a facade wrapper. Example facade:

   namespace App\Facades;
   
   use Illuminate\Support\Facades\Facade;
   
   class AdvCash extends Facade {
       protected static function getFacadeAccessor() {
           return 'advCash';
       }
   }
   

   Bind in AppServiceProvider:

   $this->app->bind('advCash', function () {
       return new \Volkandm\Advcash\Advcash();
   });
   

2. No Rate Limiting: AdvCash API may throttle requests. Implement retries or rate limiting in your service layer.

3. Response Ambiguity: The response key may contain both success/error messages. Validate $response['success'] explicitly.

Debugging

• API Credentials: Double-check .env values for typos or incorrect permissions.
• Network Issues: Use try-catch to log exceptions:

  try {
      $response = $adv->SendMoney(...);
  } catch (\Exception $e) {
      \Log::error('AdvCash Error: ' . $e->getMessage());
  }
  

Extension Points

1. Add More Methods: Extend the Advcash class to support additional AdvCash API endpoints (e.g., balance checks, transaction history). Example:

   namespace Volkandm\Advcash;
   
   class Advcash extends \Volkandm\Advcash\Advcash {
       public function getBalance() {
           // Implement using AdvCash API
       }
   }
   

2. Custom Response Handling: Override response parsing in a decorator pattern:

   class AdvCashDecorator {
       protected $advCash;
   
       public function __construct(Advcash $advCash) {
           $this->advCash = $advCash;
       }
   
       public function sendMoney($amount, $recipient, $currency, $note) {
           $response = $this->advCash->SendMoney($amount, $recipient, $currency, $note);
           return $this->formatResponse($response);
       }
   
       protected function formatResponse($response) {
           // Custom formatting logic
           return $response;
       }
   }
   

3. Testing: Mock the Advcash class in unit tests:

   $mock = Mockery::mock(Advcash::class);
   $mock->shouldReceive('SendMoney')
        ->once()
        ->andReturn(['success' => 1, 'response' => 'Test']);