Fake Omnipay Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require --dev ebisbe/fake-omnipay
   

   The --dev flag is recommended since this is a testing tool.

2. Register the Service Provider In your config/app.php, add the provider to the providers array:

   Ebisbe\FakeOmnipay\FakeOmnipayServiceProvider::class,
   

3. First Use Case: Mocking Payments in Tests Use the fake gateway in your tests to simulate payment responses without hitting a real gateway:

   use Omnipay\Omnipay;
   use Ebisbe\FakeOmnipay\FakeGateway;
   
   $gateway = Omnipay::create('fake'); // 'fake' is the gateway name
   $gateway->setTestMode(true); // Optional, but recommended for clarity
   
   // Simulate a successful purchase
   $response = $gateway->purchase(['amount' => 100.00, 'currency' => 'USD'])->send();
   $this->assertTrue($response->isSuccessful());
   

4. Where to Look First

   • README for basic usage.
   • Omnipay Documentation for gateway methods (e.g., purchase, authorize, completePurchase).
   • Source code (src/FakeGateway.php) to understand how responses are structured.

Implementation Patterns

Workflows for Testing Payments

1. Simulating Success/Failure The fake gateway returns predefined responses for common Omnipay methods. Override defaults by setting custom responses:

   $gateway->setResponse('purchase', ['success' => true, 'transactionId' => 'fake_123']);
   $response = $gateway->purchase(['amount' => 50.00])->send();
   

2. Testing Redirects (e.g., completePurchase) Simulate a redirect response with a token:

   $gateway->setResponse('completePurchase', [
       'success' => true,
       'transactionId' => 'fake_redirect_456',
       'redirectData' => ['token' => 'test_token_123']
   ]);
   

3. Integration with Laravel Testing Use Laravel’s HTTP tests to verify redirect flows:

   $response = $this->post('/checkout', ['token' => 'test_token_123']);
   $response->assertRedirect('/success');
   

4. Dynamic Responses Use closures to generate dynamic responses (e.g., based on input):

   $gateway->setResponse('authorize', function ($data) {
       return [
           'success' => $data['amount'] > 0,
           'transactionId' => 'dynamic_' . uniqid()
       ];
   });
   

Common Use Cases

Gotchas and Tips

Pitfalls

1. Gateway Name Must Be "fake" Always use Omnipay::create('fake'). Other names (e.g., 'stripe') will fail silently or throw errors.

2. Test Mode Confusion While setTestMode(true) is harmless, it’s redundant since the fake gateway ignores real test modes. Use it only for clarity in tests.

3. Response Structure Mismatches Omnipay expects specific response formats (e.g., isSuccessful(), getTransactionReference()). Ensure your custom responses include these methods:

   // Bad: Missing required methods
   $gateway->setResponse('purchase', ['success' => true]);
   
   // Good: Mimics Omnipay's Response interface
   $gateway->setResponse('purchase', [
       'success' => true,
       'transactionId' => 'fake_123',
       'message' => 'Transaction completed'
   ]);
   

4. Thread Safety The fake gateway is stateless but may behave unexpectedly if responses are modified mid-test. Reset responses between tests:

   public function tearDown(): void {
       $gateway = Omnipay::create('fake');
       $gateway->resetResponses(); // Clear all custom responses
   }
   

Debugging Tips

1. Inspect Responses Dump the raw response to debug:

   $response = $gateway->purchase([])->send();
   dd($response->getData()); // Check structure
   

2. Enable Omnipay Logging Add this to your test setup to log all gateway calls:

   Omnipay\Common\AbstractGateway::setLogLevel(\Psr\Log\LogLevel::DEBUG);
   

3. Common Errors

   • Call to undefined method: Missing methods in custom responses (e.g., getTransactionReference()). Fix: Extend Omnipay\Common\Message\AbstractResponse or ensure all required methods are present.
   • Gateway not found: Forgetting to register the service provider or using the wrong gateway name. Fix: Verify config/app.php and use 'fake' as the gateway name.

Extension Points

1. Custom Response Classes Override the fake gateway’s response behavior by extending Ebisbe\FakeOmnipay\FakeGateway:

   class CustomFakeGateway extends FakeGateway {
       public function getDefaultParameters() {
           $defaults = parent::getDefaultParameters();
           $defaults['testMode'] = true; // Force test mode
           return $defaults;
       }
   }
   

   Register it in config/app.php:

   'gateways' => [
       'fake' => CustomFakeGateway::class,
   ],
   

2. Mocking Specific Gateways If you need to mock a specific gateway (e.g., Stripe) while using the fake gateway, alias it in config/services.php:

   'omnipay' => [
       'stripe' => 'fake', // Redirect Stripe tests to the fake gateway
   ],
   

3. Adding New Methods The fake gateway supports all Omnipay methods by default. To add custom methods (e.g., refundSpecific), extend the gateway and define the method:

   class ExtendedFakeGateway extends FakeGateway {
       public function refundSpecific(array $parameters) {
           return $this->createResponse('\Omnipay\Common\Message\RefundResponse', [
               'success' => true,
               'transactionId' => 'refund_' . uniqid()
           ]);
       }
   }