Vcc Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require lonban/vcc
   

   Add to config/app.php under providers:

   Lonban\Vcc\VccServiceProvider::class,
   

2. Publish Config

   php artisan vendor:publish --provider="Lonban\Vcc\VccServiceProvider" --tag="config"
   

   Edit config/vcc.php to set your API credentials (e.g., api_key, base_uri).

3. First Use Case Fetch a VCC (Virtual Credit Card) number:

   use Lonban\Vcc\Facades\Vcc;
   
   $vcc = Vcc::generate();
   dd($vcc); // Returns an array with card details (number, expiry, etc.)
   

Where to Look First

• Facade: Lonban\Vcc\Facades\Vcc (primary entry point).
• Config: config/vcc.php (API settings, retries, logging).
• Exceptions: Lonban\Vcc\Exceptions\VccException (handle API errors).

Implementation Patterns

Core Workflows

1. Generating VCCs

   // Basic generation
   $vcc = Vcc::generate(['type' => 'visa', 'amount' => 1000]);
   
   // Batch generation
   $vccs = Vcc::generateBatch(5, ['type' => 'mastercard']);
   

2. Validating VCCs

   $isValid = Vcc::validate($vccNumber);
   if (!$isValid) throw new \InvalidArgumentException("Invalid VCC");
   

3. Integration with Payments Use the generated VCC in payment gateways (e.g., Stripe, PayPal) via their SDKs:

   $paymentIntent = \Stripe\PaymentIntent::create([
       'amount' => 1000,
       'currency' => 'usd',
       'payment_method' => [
           'card' => [
               'number' => $vcc['number'],
               'exp_month' => $vcc['expiry_month'],
               'exp_year' => $vcc['expiry_year'],
               'cvc' => $vcc['cvc'],
           ],
       ],
   ]);
   

4. Testing Transactions Simulate transactions with test VCCs:

   $testVcc = Vcc::generate(['is_test' => true]);
   // Use $testVcc in sandbox environments.
   

Advanced Patterns

• Retry Logic: Configure retries in config/vcc.php for transient failures.
• Logging: Enable log_enabled in config to debug API calls.
• Custom Responses: Extend the facade to add domain-specific logic:

  namespace App\Services;
  use Lonban\Vcc\Facades\Vcc;
  
  class PaymentService {
      public function createTestPayment() {
          $vcc = Vcc::generate(['type' => 'visa', 'is_test' => true]);
          // Custom logic here...
      }
  }
  

Gotchas and Tips

Pitfalls

1. API Rate Limits

   • The package doesn’t handle rate limiting by default. Monitor config/vcc.php for max_retries and adjust accordingly.
   • Fix: Implement middleware to throttle requests if needed.

2. Sensitive Data Exposure

   • VCC details (CVC, expiry) are returned in plain arrays. Never log or expose these in production.
   • Fix: Use Laravel’s encrypt() or a dedicated secrets manager:

     $encryptedCvc = encrypt($vcc['cvc']);
     

3. Deprecated Methods

   • The package is immature (0 stars, no active maintenance). Assume breaking changes in future updates.
   • Fix: Pin the version in composer.json:

     "require": {
         "lonban/vcc": "1.0.0"
     }
     

4. No Built-in Mocking

   • No native support for testing. Manually mock the facade in PHPUnit:

     $this->mock(Vcc::class)->shouldReceive('generate')->andReturn(['number' => '4242424242424242']);
     

Debugging Tips

• Enable Logging: Set log_enabled => true in config/vcc.php to see raw API responses.
• Check HTTP Status Codes: Wrap calls in try-catch:

  try {
      $vcc = Vcc::generate();
  } catch (\Lonban\Vcc\Exceptions\VccException $e) {
      if ($e->getCode() === 429) {
          // Handle rate limiting
      }
  }
  

Extension Points

1. Custom VCC Providers Override the default provider by binding a new implementation in a service provider:

   $this->app->bind(\Lonban\Vcc\Contracts\VccProvider::class, \App\Providers\CustomVccProvider::class);
   

2. Event Listeners Listen for VCC generation events (if the package emits them):

   // config/listeners.php
   'vcc.generated' => [
       \App\Listeners\LogVccGeneration::class,
   ];
   

3. API Response Transformation Extend the base response class to add custom fields:

   namespace App\Extensions;
   use Lonban\Vcc\Responses\VccResponse;
   
   class ExtendedVccResponse extends VccResponse {
       public function getFormattedNumber() {
           return preg_replace('/(\d{4})(\d{4})(\d{4})(\d{4})/', '$1-$2-$3-$4', $this->number);
       }
   }