Getting started

1. Requirements
2. Installation
3. Your first verification (auto-wired)
4. Manual wiring (full control)
5. Reading the result

Requirements

• PHP 8.2, 8.3 or 8.4
• A PSR-18 HTTP client + PSR-17 factories. The core is client-agnostic - it depends on the PSR interfaces and declares psr/http-client-implementation + psr/http-factory-implementation as virtual requirements, so Composer asks you to pick an implementation. Cache is PSR-16, logging PSR-3, clock PSR-20.

Installation

composer require gawrys/counterparty-core
# choose any PSR-18 client + PSR-17 factories, e.g.:
composer require symfony/http-client nyholm/psr7

Why a separate HTTP client? A library shouldn’t force one on you - your app may already use Guzzle, Symfony HttpClient, etc. The core targets the PSR interfaces; you supply the implementation (or let auto-discovery find it). See the FAQ.

Optional add-ons:

composer require gawrys/counterparty-ai        # advisory AI risk research
composer require gawrys/counterparty-laravel   # Laravel bridge
composer require gawrys/counterparty-bundle    # Symfony bundle

Your first verification (auto-wired)

The factory assembles the bundled checks (White List, VIES, sanctions.network) + the rule-based strategy, auto-discovering your installed PSR-18 client and PSR-17 factories:

use Gawrys\Counterparty\CounterpartyVerifierFactory;
use Gawrys\Counterparty\Counterparty;

$verifier = CounterpartyVerifierFactory::discover();   // or ::create($psr18Client)

$outcome = $verifier->verify(new Counterparty(
    name: 'Acme Sp. z o.o.',
    country: 'PL',
    nip: '1234567890',
    euVat: 'PL1234567890',
));

foreach ($outcome->report->results() as $result) {
    printf("[%s] %s: %s\n", $result->status->value, $result->checkName, $result->summary);
}

echo $outcome->assessment->level->value;        // low | medium | high | critical
var_dump($outcome->requiresHumanReview());       // bool

Manual wiring (full control)

Wire it yourself to choose the checks, strategy, cache or logger. The clock is optional and defaults to SystemClock (inject a FrozenClock in tests):

use Gawrys\Counterparty\Verifier;
use Gawrys\Counterparty\Risk\RuleBasedRiskStrategy;
use Gawrys\Counterparty\Check\WhiteListCheck;
use Gawrys\Counterparty\Check\ViesCheck;
use Gawrys\Counterparty\Check\SanctionsScreeningCheck;
use Gawrys\Counterparty\Adapter\WhiteList\HttpWhiteListClient;
use Gawrys\Counterparty\Adapter\Vies\HttpViesClient;
use Gawrys\Counterparty\Adapter\Sanctions\SanctionsNetworkProvider;
use Gawrys\Counterparty\Http\JsonHttpClient;

$http = new JsonHttpClient($psr18Client, $psr17Factory, $psr17Factory);

$verifier = new Verifier(
    checks: [
        new WhiteListCheck(new HttpWhiteListClient($http)),
        new ViesCheck(new HttpViesClient($http)),
        new SanctionsScreeningCheck(new SanctionsNetworkProvider($http)),
    ],
    riskStrategy: RuleBasedRiskStrategy::withDefaultRules(),
);

On a framework, prefer the Laravel bridge or Symfony bundle, which wire all of the above for you.

Reading the result

• VerificationReport - the hard facts: a list of CheckResults, each pass, warning, fail or inconclusive, with a source and an optional proof identifier.
• RiskAssessment - the advisory output: a RiskLevel, a score, grounded Evidence, and requiresHumanReview().

Next: Architecture · Registries · Risk engine.