README

Laravel integration for reporting server-side conversion events to the Result Vector API.

This package supports one operation: POST /api/v1/conversions/report with the att and event fields. It does not provide browser collectors, attribution management, queues, retries, or other Result Vector APIs.

Requirements

• PHP 8.4+
• Laravel 11, 12, or 13

Installation

Install the tagged package in a Laravel application:

composer require resultvector/laravel

Laravel discovers the service provider automatically. Configuration is merged automatically; publishing is optional:

php artisan vendor:publish --tag="resultvector-config"

Configuration

Add the required API token to the consuming application's .env file:

RESULTVECTOR_API_TOKEN=your-server-side-api-token

Optional values are:

RESULTVECTOR_API_URL=https://api.resultvector.com
RESULTVECTOR_TIMEOUT=5

The endpoint path is fixed by the package. Runtime code reads the resultvector Laravel configuration and does not read environment variables directly.

Usage

Safe reporting

Use report() in normal production workflows. It returns a result and does not interrupt the consuming application's business operation when configuration, transport, or HTTP reporting fails.

Report only after the business operation succeeds:

use Illuminate\Http\RedirectResponse;
use ResultVector\Laravel\Facades\ResultVector;

public function store(StoreOrderRequest $request): RedirectResponse
{
    $order = $this->orders->create($request->validated());

    $result = ResultVector::report(
        att: $request->user()?->attribution_token,
        event: 'purchase_completed',
    );

    return to_route('orders.show', $order);
}

att and event are trimmed before submission. The request payload contains exactly:

{
  "att": "att_existing_attribution_token",
  "event": "purchase_completed"
}

Strict reporting

Use reportOrFail() when the caller deliberately needs reporting failures to propagate:

use ResultVector\Laravel\Facades\ResultVector;

$result = ResultVector::reportOrFail(
    att: $attributionToken,
    event: 'purchase_completed',
);

Both methods return a reported result for any successful 2xx response. Strict reporting propagates missing configuration, connection failures, and unsuccessful HTTP responses. A blank event identifier throws InvalidArgumentException because it is a developer error.

Results

ReportResult exposes these states:

if ($result->wasReported()) {
    // Result Vector accepted the request; statusCode contains the 2xx status.
} elseif ($result->wasSkipped()) {
    // No attribution was available; no HTTP request was made.
} elseif ($result->hasFailed()) {
    // Safe reporting caught an operational failure.
}

Missing, empty, or whitespace-only attribution is a normal skipped result and never sends a request. Safe reporting logs a warning with the event, exception type, and sanitized diagnostic message. It never logs the API token or attribution token.

Dependency injection

Inject the concrete client instead of using the facade when preferred:

use ResultVector\Laravel\ReportResult;
use ResultVector\Laravel\ResultVectorClient;

final class CheckoutReporter
{
    public function __construct(private ResultVectorClient $resultVector) {}

    public function report(string $att): ReportResult
    {
        return $this->resultVector->report($att, 'purchase_completed');
    }
}

ResultVectorClient is registered as a container singleton.

Testing a consuming application

Use Laravel's HTTP fake; no live network request is required:

use Illuminate\Support\Facades\Http;
use ResultVector\Laravel\Facades\ResultVector;

Http::fake(['https://api.resultvector.com/*' => Http::response(status: 202)]);

$result = ResultVector::report('att-test', 'purchase_completed');

expect($result->wasReported())->toBeTrue();
Http::assertSent(fn ($request) => $request->url() ===
    'https://api.resultvector.com/api/v1/conversions/report');

Security

This is a server-side package. Keep RESULTVECTOR_API_TOKEN in .env, do not commit it, and never expose it to browser-side code. The package does not persist attribution tokens or report payloads.

Package verification

From the package repository:

composer test
composer analyse
composer format

Changelog

See CHANGELOG.md.

Contributing

Contributions are welcome through the GitHub repository. Keep changes focused and include tests for behavior changes.

Security vulnerabilities

Please report suspected vulnerabilities privately to the maintainers rather than opening a public issue. See the GitHub repository for the current contact process.

Credits

Result Vector — github.com/resultvector/resultvector-laravel

License

The MIT License (MIT). See LICENSE.md.