PHPackages                             blob-solutions/laravel-vcr-am - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Payment Processing](/categories/payments)
4. /
5. blob-solutions/laravel-vcr-am

ActiveLibrary[Payment Processing](/categories/payments)

blob-solutions/laravel-vcr-am
=============================

Official Laravel adapter for the VCR.AM Virtual Cash Register PHP SDK — ServiceProvider, Facade, config publishing, and Artisan commands.

v0.6.0(2w ago)02ISCPHPPHP ^8.2

Since May 4Pushed 2w agoCompare

[ Source](https://github.com/blob-am/laravel-vcr-am)[ Packagist](https://packagist.org/packages/blob-solutions/laravel-vcr-am)[ Docs](https://vcr.am)[ RSS](/packages/blob-solutions-laravel-vcr-am/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (51)Versions (6)Used By (0)

Laravel adapter for the VCR.AM PHP SDK
======================================

[](#laravel-adapter-for-the-vcram-php-sdk)

[![Packagist Version](https://camo.githubusercontent.com/944d642e64251d25dde421b98da060c27787e32600aab145085571d6843b043b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f626c6f622d736f6c7574696f6e732f6c61726176656c2d7663722d616d2e737667)](https://packagist.org/packages/blob-solutions/laravel-vcr-am)[![PHP Version Require](https://camo.githubusercontent.com/bb000b3f57bc46abd0632e2ff6b0efc0a76c99154aad5cd508c925d04a307508/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f626c6f622d736f6c7574696f6e732f6c61726176656c2d7663722d616d2f706870)](https://packagist.org/packages/blob-solutions/laravel-vcr-am)[![License](https://camo.githubusercontent.com/4f60419440afb378500bd0c431606bf9206998a51f21c0b0a5a8b33cffb871ba/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f626c6f622d736f6c7574696f6e732f6c61726176656c2d7663722d616d2e737667)](LICENSE)[![CI](https://github.com/blob-am/vcr-am-php/actions/workflows/ci.yml/badge.svg)](https://github.com/blob-am/vcr-am-php/actions/workflows/ci.yml)

A thin Laravel adapter around [`blob-solutions/vcr-am-sdk`](https://packagist.org/packages/blob-solutions/vcr-am-sdk). Wires the SDK's `VcrClient` into Laravel's container, publishes a config file, exposes a facade, and registers an Artisan health-check command.

The adapter contains **zero business logic** — every API call goes straight through to the SDK. If the SDK supports it, the adapter exposes it.

Requirements
------------

[](#requirements)

- PHP **8.2 or newer**
- Laravel **11.x or 12.x**
- A VCR.AM account and API key — sign up at [vcr.am](https://vcr.am)

Installation
------------

[](#installation)

```
composer require blob-solutions/laravel-vcr-am
```

The service provider and facade are auto-discovered.

Add your API key to `.env`:

```
VCR_AM_API_KEY=your-api-key-here
```

That's it — the package is ready to use.

Configuration
-------------

[](#configuration)

To customise the configuration (e.g. point at a staging environment), publish the config file:

```
php artisan vendor:publish --tag=vcr-am-config
```

This creates `config/vcr-am.php`:

```
return [
    'api_key' => env('VCR_AM_API_KEY'),
    'base_url' => env('VCR_AM_BASE_URL'), // null = SDK default (https://vcr.am/api/v1)
];
```

Usage
-----

[](#usage)

### Via the facade

[](#via-the-facade)

```
use BlobSolutions\LaravelVcrAm\Facades\VcrAm;
use BlobSolutions\VcrAm\Input\RegisterSaleInput;

$response = VcrAm::registerSale(new RegisterSaleInput(/* ... */));
```

### Via dependency injection

[](#via-dependency-injection)

```
use BlobSolutions\VcrAm\VcrClient;

class CheckoutController
{
    public function __construct(private readonly VcrClient $vcr) {}

    public function __invoke(): RedirectResponse
    {
        $response = $this->vcr->registerSale(/* ... */);
        // ...
    }
}
```

`VcrClient` is bound as a singleton, so the same instance is reused for the lifetime of every request.

### Via the container

[](#via-the-container)

```
$client = app(VcrClient::class);
```

Health check
------------

[](#health-check)

To verify connectivity from a running app or as part of your deployment pipeline:

```
php artisan vcr-am:health
```

```
VCR.AM API reachable.
  VCR    : "My Shop" (CRN 1234567890123)
  Mode   : production
  Entity : My Shop LLC (TIN 01234567)

```

`Mode` is `production` or `sandbox` — useful at a glance for confirming which VCR your API key is wired to. Add `--sandbox` to point the check at the parallel sandbox client (see [Testing against a sandbox VCR](#testing-against-a-sandbox-vcr) below).

Exit code is `0` on success, `1` on failure (with the SDK's error message printed).

Testing
-------

[](#testing)

There are two distinct testing strategies. Pick whichever fits the seam you're testing:

You want…UseUnit tests that never touch the network[`VcrAm::fake()`](#unit-tests-vcramfake)Smoke tests / staging against a real VCR[Sandbox channel](#testing-against-a-sandbox-vcr)### Unit tests: `VcrAm::fake()`

[](#unit-tests-vcramfake)

Modelled on Laravel's `Http::fake()`. After calling `VcrAm::fake()`, every resolution of `VcrClient` (via the facade, `app(VcrClient::class)`, or constructor DI) returns a fake that records every request and rejects every un-stubbed endpoint with a clear `RuntimeException` — so SDK calls the test didn't expect surface as test failures, not as silent passes.

```
use BlobSolutions\LaravelVcrAm\Facades\VcrAm;

it('fiscalises checkout via VCR.AM', function (): void {
    VcrAm::fake([
        'POST /sales' => [
            'urlId' => 'abc',
            'saleId' => 42,
            'crn' => '1234567890123',
            'srcReceiptId' => 100,
            'fiscal' => 'F-1',
        ],
    ]);

    $this->postJson('/checkout', [/* ... */])->assertSuccessful();

    VcrAm::assertSentCount(1);
    VcrAm::assertSent(
        'POST /sales',
        fn (?array $body) => ($body['cashier']['deskId'] ?? null) === 'desk-1',
    );
});
```

Stub forms:

```
// Plain array — turned into a 200 JSON response.
VcrAm::fake([
    'POST /sales' => ['urlId' => 'X', /* ... */],
]);

// Closure — receives the captured PSR-7 request, returns either a
// ResponseInterface or a plain array.
VcrAm::fake([
    'POST /sales' => function (Psr\Http\Message\RequestInterface $request) {
        return ['urlId' => 'dyn', /* ... */];
    },
]);

// Throw a server-side error to test how your code handles failures.
use Nyholm\Psr7\Response;

VcrAm::fake([
    'POST /sales' => fn () => new Response(
        400,
        ['Content-Type' => 'application/json'],
        '{"code":"VALIDATION","message":"price must be positive"}',
    ),
]);
```

Assertions:

```
VcrAm::assertSent('POST /sales');                          // any matching request
VcrAm::assertSent('POST /sales', fn (?array $body) => /* ... */);  // narrow on body
VcrAm::assertNotSent('POST /prepayments');                 // negative assertion
VcrAm::assertNothingSent();                                // no SDK calls at all
VcrAm::assertSentCount(2);                                 // exact request count
```

The matcher syntax is `"METHOD /path"`. Method is case-insensitive, path is exact. The SDK base path (`/api/v1`) is stripped automatically so stubs read like the endpoints documented in the SDK source (`POST /sales`, not `POST /api/v1/sales`).

### Testing against a sandbox VCR

[](#testing-against-a-sandbox-vcr)

The SDK has no operating-mode flag of its own — sandbox is determined entirely by the VCR an API key authenticates against. To run real HTTP calls during integration testing without touching production, create a sandbox VCR at [vcr.am](https://vcr.am), generate an API key for it, and point this package at it.

Quickest setup — overwrite the default key in your testing environment:

```
# .env.testing
VCR_AM_API_KEY=sk_sandbox_...
```

Or run two clients side-by-side — useful when a single app needs both for different flows (e.g. real receipts in production paths, sandbox receipts in an E2E suite that runs against the same deploy):

```
# .env
VCR_AM_API_KEY=sk_live_...
VCR_AM_SANDBOX_API_KEY=sk_sandbox_...
```

```
VcrAm::registerSale($input);             // hits the production VCR
VcrAm::sandbox()->registerSale($input);  // hits the sandbox VCR
```

The sandbox `VcrClient` is also resolvable through the container:

```
use BlobSolutions\LaravelVcrAm\VcrAmServiceProvider;
use BlobSolutions\VcrAm\VcrClient;

$sandbox = app(VcrAmServiceProvider::SANDBOX_BINDING); // returns VcrClient
```

Calling `VcrAm::sandbox()` without `VCR_AM_SANDBOX_API_KEY` set throws a `RuntimeException` — deliberately, so production code never silently downgrades to the default key.

### Health check, sandbox edition

[](#health-check-sandbox-edition)

`vcr-am:health` also accepts `--sandbox` and reports the sandbox VCR's identity:

```
php artisan vcr-am:health --sandbox
```

```
VCR.AM API reachable.
  VCR    : "My Shop (sandbox)" (CRN not activated)
  Mode   : sandbox
  Entity : My Shop LLC (TIN 01234567)

```

Logging
-------

[](#logging)

The package forwards Laravel's PSR-3 logger into the SDK automatically. Every request and response is logged at the level configured in your `config/logging.php`. To filter only VCR.AM log entries, give the SDK its own channel:

```
// config/logging.php
'channels' => [
    'vcr-am' => [
        'driver' => 'daily',
        'path' => storage_path('logs/vcr-am.log'),
        'days' => 14,
    ],
],
```

```
// AppServiceProvider::register()
$this->app->bind(\Psr\Log\LoggerInterface::class, fn () => Log::channel('vcr-am'));
```

HTTP client override
--------------------

[](#http-client-override)

The SDK ships with Guzzle 7 by default. To swap it (e.g. for testing or to use a shared HTTP client with custom retry policies), bind a PSR-18 implementation in your `AppServiceProvider`:

```
$this->app->bind(\Psr\Http\Client\ClientInterface::class, fn () => new MyHttpClient());
```

The adapter detects this binding and passes it into the SDK constructor.

Documentation for SDK methods
-----------------------------

[](#documentation-for-sdk-methods)

See the [SDK README](https://github.com/blob-am/vcr-am-sdk-php) for every endpoint, every input DTO, and every response type. The Laravel adapter is a 1:1 wrapper — anything documented for `VcrClient` works through the facade or container binding.

Status
------

[](#status)

> **Pre-release.** API tracks the SDK's `0.x` releases. Pin tightly until `1.0`.

License
-------

[](#license)

[ISC](LICENSE)

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance97

Actively maintained with recent releases

Popularity3

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity40

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~17 days

Total

5

Last Release

14d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/24254622?v=4)[Alex Kraiz](/maintainers/lobotomoe)[@lobotomoe](https://github.com/lobotomoe)

---

Top Contributors

[![lobotomoe](https://avatars.githubusercontent.com/u/24254622?v=4)](https://github.com/lobotomoe "lobotomoe (1 commits)")

---

Tags

phplaravellaravel-packagefiscalizationsrcvcrfiscalarmeniaarmeniancash-registervcr-amvirtual-cash-registertax-servicee-receiptblob-solutions

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/blob-solutions-laravel-vcr-am/health.svg)

```
[![Health](https://phpackages.com/badges/blob-solutions-laravel-vcr-am/health.svg)](https://phpackages.com/packages/blob-solutions-laravel-vcr-am)
```

###  Alternatives

[laravel/ai

The official AI SDK for Laravel.

1.0k3.2M246](/packages/laravel-ai)[laravel/sail

Docker files for running a basic Laravel application.

1.9k205.7M1.3k](/packages/laravel-sail)[spatie/laravel-health

Monitor the health of a Laravel application

87912.0M177](/packages/spatie-laravel-health)[tallstackui/tallstackui

TallStackUI is a powerful suite of Blade components that elevate your workflow of Livewire applications.

728176.2k14](/packages/tallstackui-tallstackui)[laravel/surveyor

Static analysis tool for Laravel applications.

86121.4k14](/packages/laravel-surveyor)[masterix21/laravel-licensing

Laravel licensing package with polymorphic assignment to any model, activation keys, expirations/renewals, and seat control via LicenseUsage. Supports offline verification with public-key–signed tokens, a CLI to generate/rotate/revoke keys, and an extensible architecture via config and contracts.

1613.3k4](/packages/masterix21-laravel-licensing)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)