PHPackages                             gawrys/counterparty-core - 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. [PSR & Standards](/categories/psr-standards)
4. /
5. gawrys/counterparty-core

ActiveLibrary[PSR & Standards](/categories/psr-standards)

gawrys/counterparty-core
========================

Framework-agnostic core for counterparty due diligence: domain model, ports, rule-based risk strategy, PSR-18 reference adapters and contract tests.

v0.1.2(today)011↑2627.3%1MITPHPPHP >=8.2CI passing

Since Jun 23Pushed todayCompare

[ Source](https://github.com/igorgawrys1/counterparty-core)[ Packagist](https://packagist.org/packages/gawrys/counterparty-core)[ RSS](/packages/gawrys-counterparty-core/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (18)Versions (4)Used By (1)

Counterparty Core
=================

[](#counterparty-core)

[![Packagist Version](https://camo.githubusercontent.com/e107fd7f42129ec361c9373fc979a8713d359d375cda524d8e9fe0140bef3cce/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6761777279732f636f756e74657270617274792d636f72652e737667)](https://packagist.org/packages/gawrys/counterparty-core)[![Total Downloads](https://camo.githubusercontent.com/169b6b0c620519c42b46aeca6bad00f264d10818061405765958e26c9caec0ca/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6761777279732f636f756e74657270617274792d636f72652e737667)](https://packagist.org/packages/gawrys/counterparty-core)[![CI](https://github.com/igorgawrys1/counterparty-core/actions/workflows/ci.yml/badge.svg)](https://github.com/igorgawrys1/counterparty-core/actions/workflows/ci.yml)[![PHP](https://camo.githubusercontent.com/dad72c42359ce03cc1cd9d1b3251dcc5769e6f45e218d6149e19bd7bcb1bfac0/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e32253230253743253230382e33253230253743253230382e342d3737376262342e737667)](https://www.php.net/)[![PHPStan](https://camo.githubusercontent.com/745eb989b9e4903dc598fe2cc63ed4226198be55b7c729001cbd1ece7676fef6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6d61782d627269676874677265656e2e737667)](https://phpstan.org/)[![Psalm](https://camo.githubusercontent.com/1516496318aec6e2baf9f8ed7888070c8c0c279848ee94165206d1fa8796d864/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5073616c6d2d6c6576656c253230312d627269676874677265656e2e737667)](https://psalm.dev/)[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE)

The framework-agnostic heart of the **Counterparty Verification** toolkit - per-country **registry lookups**, **sanctions screening** and a pluggable **risk engine** for counterparty due diligence. Hexagonal: it depends only on PSR interfaces, so it drops into any framework (or none).

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

$outcome->report->worstStatus();    // hard facts (deterministic)
$outcome->assessment->level;        // advisory RiskLevel
$outcome->requiresHumanReview();    // true on adverse / inconclusive / low-confidence
```

> ⚠️ **This is a due-diligence aid, not a compliance product.** It does **not** make you "AML compliant" - that remains your responsibility. The risk score is **advisory**.

Features
--------

[](#features)

- **Hexagonal & dependency-light** - PSR-18/17 (HTTP), PSR-16 (cache), PSR-3 (log), PSR-20 (clock). No framework, no vendor SDK in the core.
- **Capability-aware registries** - drivers declare a `RegistryCapability`; the verifier routes by *(country + capability)* and returns an honest `inconclusive` when nothing covers a request. Adding a country is one driver + one registration.
- **Reference adapters (PSR-18)** - PL White List (VAT status, IBAN match, search-id proof), EU VIES, KRS, CEIDG, REGON, CRBR, sanctions.network (default) and OpenSanctions.
- **Pluggable risk engine** - `RuleBasedRiskStrategy` composed of small `RiskRule`s; add your own without subclassing, or implement `RiskStrategy` for a bespoke model.
- **Contract tests as a feature** - `RegistryDriverContractTestCase` certifies any third-party driver.
- **Strict** - PHPStan max + Psalm level 1, fully typed.

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

[](#installation)

```
composer require gawrys/counterparty-core
```

This package is HTTP-client agnostic: it depends on the PSR-18 / PSR-17 **interfaces** and declares `psr/http-client-implementation` + `psr/http-factory-implementation` as virtual requirements, so Composer asks you to choose a client. Install any PSR-18 implementation, e.g.:

```
composer require symfony/http-client nyholm/psr7
# or a Guzzle PSR-18 adapter, etc.
```

Usage
-----

[](#usage)

### Quick start (auto-wired)

[](#quick-start-auto-wired)

The factory assembles the bundled checks (White List, VIES, sanctions.network) + the rule-based strategy. It auto-discovers 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('Acme', 'PL', nip: '1234567890', euVat: 'PL1234567890'));
```

### Manual wiring (full control)

[](#manual-wiring-full-control)

The clock is optional and defaults to `SystemClock`; pass a `FrozenClock` in tests.

```
use Gawrys\Counterparty\Verifier;
use Gawrys\Counterparty\Risk\RuleBasedRiskStrategy;
use Gawrys\Counterparty\Check\WhiteListCheck;
use Gawrys\Counterparty\Adapter\WhiteList\HttpWhiteListClient;
use Gawrys\Counterparty\Http\JsonHttpClient;

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

$verifier = new Verifier(
    checks: [new WhiteListCheck(new HttpWhiteListClient($http))], // clock defaults to SystemClock
    riskStrategy: RuleBasedRiskStrategy::withDefaultRules(),
);
```

### Add a country (one driver + one registration)

[](#add-a-country-one-driver--one-registration)

```
final readonly class GermanRegistryDriver extends AbstractRegistryDriver
{
    public function capabilities(): array { return [RegistryCapability::LegalEntityData]; }
    public function countries(): array    { return ['DE']; }
    public function lookup(LookupRequest $request): LookupResult { /* ... */ }
}

$registries->extend('de', fn () => new GermanRegistryDriver(/* ... */));
```

### Add a custom scoring rule

[](#add-a-custom-scoring-rule)

```
final class HighRiskCountryRule implements RiskRule
{
    public function evaluate(RiskContext $context): iterable
    {
        if (in_array($context->counterparty->country, ['XX', 'YY'], true)) {
            yield new RiskSignal('geo.high_risk', 0.6, adverse: false);
        }
    }
}

$strategy = new RuleBasedRiskStrategy([new HighRiskCountryRule(), /* ...defaults */]);
```

### Certify a third-party driver

[](#certify-a-third-party-driver)

```
final class GermanRegistryDriverTest extends RegistryDriverContractTestCase
{
    protected function createDriver(): RegistryDriver { /* wire to a mocked HTTP client */ }
    protected function supportedRequest(): LookupRequest { /* a request it supports */ }
}
```

Full guides live in the **[documentation](https://igorgawrys1.github.io/counterparty-verification/)**.

Part of the toolkit
-------------------

[](#part-of-the-toolkit)

PackagePurpose**counterparty-core** (this)Domain, registries, risk engine, PSR-18 adapters[counterparty-ai](https://github.com/igorgawrys1/counterparty-ai)Optional advisory AI risk research[counterparty-laravel](https://github.com/igorgawrys1/counterparty-laravel)Laravel bridge[counterparty-bundle](https://github.com/igorgawrys1/counterparty-bundle)Symfony bundleTesting
-------

[](#testing)

```
composer check   # php-cs-fixer + PHPStan max + Psalm level 1 + PHPUnit
composer test    # PHPUnit only
```

Changelog
---------

[](#changelog)

See [CHANGELOG.md](CHANGELOG.md).

Contributing & Security
---------------------------

[](#contributing--security)

Pull requests welcome. Please report security issues privately - see [SECURITY.md](SECURITY.md).

Credits
-------

[](#credits)

- [Igor Gawrys](https://github.com/igorgawrys1)

License
-------

[](#license)

The MIT License (MIT). See [LICENSE](LICENSE).

###  Health Score

39

—

LowBetter than 85% of packages

Maintenance100

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community5

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

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 ~2 days

Total

3

Last Release

0d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/b7e3d761ee1d0092d6f4400cf56467f93fa413fbc1cb7bc2e9776903cb52f5f7?d=identicon)[gawrys](/maintainers/gawrys)

---

Tags

psrvatvieskycsanctionsdue-diligencewhite-list

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Psalm

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/gawrys-counterparty-core/health.svg)

```
[![Health](https://phpackages.com/badges/gawrys-counterparty-core/health.svg)](https://phpackages.com/packages/gawrys-counterparty-core)
```

###  Alternatives

[telnyx/telnyx-php

Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network.

35729.6k2](/packages/telnyx-telnyx-php)[tempest/framework

The PHP framework that gets out of your way.

2.2k31.1k12](/packages/tempest-framework)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

84735.1k](/packages/flow-php-flow)[cakephp/cakephp

The CakePHP framework

8.8k19.1M1.7k](/packages/cakephp-cakephp)[n1ebieski/ksef-php-client

PHP API client that allows you to interact with the API Krajowego Systemu e-Faktur

8754.6k](/packages/n1ebieski-ksef-php-client)[phpro/http-tools

HTTP tools for developing more consistent HTTP implementations.

28146.3k](/packages/phpro-http-tools)

PHPackages © 2026

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