PHPackages                             adscore/php-common - 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. [Utility & Helpers](/categories/utility)
4. /
5. adscore/php-common

ActiveLibrary[Utility & Helpers](/categories/utility)

adscore/php-common
==================

PHP client library for Adscore

v0.1.5(7mo ago)033.1k↓29.8%MITPHPPHP >=7.4.0

Since Sep 15Pushed 7mo ago2 watchersCompare

[ Source](https://github.com/Adscore/php-common)[ Packagist](https://packagist.org/packages/adscore/php-common)[ Docs](https://github.com/Adscore/php-common)[ RSS](/packages/adscore-php-common/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (6)DependenciesVersions (8)Used By (0)

php-common
==========

[](#php-common)

[![Software License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE.md)

This library provides various utilities for producing and parsing [Adscore](https://adscore.com) signatures, generating custom request payloads, and virtually anything that might be useful for customers doing server-side integration with the service.

Install
-------

[](#install)

Via Composer

```
$ composer require adscore/php-common
```

Usage
-----

[](#usage)

### V4 signature verification

[](#v4-signature-verification)

When zone's "Response signature algorithm" is set to "Hashing" or "Signing", it means that V4 signatures are in use. They provide basic means to check incoming traffic for being organic and valuable, but do not carry any additional information.

```
use AdScore\Common\Signature\Signature4;
use AdScore\Common\Signature\Exception\{VersionException, ParseException, VerifyException};
use AdScore\Common\Definition\Judge;

/*  Replace  with "Zone Response Key" which you might find in "Zone Encryption" page for given zone.
    Those keys are base64-encoded and the library expects raw binary, so we need to decode it now. */
$cryptKey = \base64_decode("");

/*  Three things are necessary to verify the signature - at least one IP address, User Agent string
    and the signature itself. */
$signature = $_GET['signature']; /* for example */
$userAgent = $_SERVER['HTTP_USER_AGENT'] ?? '';
/*  You might want to use X-Forwarded-For or other IP-forwarding headers coming from for example load
    balancing services, but make sure you trust them and they are not vulnerable to user modification! */
$ipAddresses = [ $_SERVER['REMOTE_ADDR'] ];

try {
    $parser = Signature4::createFromRequest($signature, $ipAddresses, $userAgent, $cryptKey);
    /*  Result contains numerical result value */
    $result = $parser->getResult();
    /*  Judge is the module evaluating final result in the form of single score. RESULTS constant
        contains array with human-readable descriptions of every numerical result, if needed. */
    $humanReadable = Judge::RESULTS[$result];
    print $humanReadable['verdict'] . ' (' . $humanReadable['name'] . ')';
} catch (VersionException $e) {
    /*  It means that the signature is not the V4 one, check your zone settings and ensure the signatures
        are coming from the chosen zone. */
} catch (ParseException $e) {
    /*  It means that the signature metadata is malformed and cannot be parsed, or contains invalid data,
        check for corruption underway. */
} catch (VerifyException $e) {
    /*  Signature could not be verified - usually this is a matter of IP / user agent mismatch (or spoofing).
        They must be bit-exact, so even excessive whitespace or casing change can trigger the problem. */
}
```

### V5 signature decryption

[](#v5-signature-decryption)

V5 is in fact an encrypted payload containing various metadata about the traffic. Its decryption does not rely on IP address nor User Agent string, so it is immune for environment changes usually preventing V4 to be even decoded. Judge result is also included in the payload, but client doing the integration can make its own decision basing on the metadata accompanying.

Zone has to be set explicitly to V5 signature, if you don't see the option, please contact support as we are rolling this mode on customer's demand. The format supports a wide variety of encryption and serialization methods, some of them are included in this repository, but it can be extended to fulfill specific needs.

It can be integrated in V4-compatible mode, not making use of any V5 features (see V4 verification):

```
use AdScore\Common\Signature\Signature5;
use AdScore\Common\Signature\Exception\{VersionException, ParseException, VerifyException};
use AdScore\Common\Definition\Judge;

$cryptKey = \base64_decode("");
$signature = $_GET['signature'];
$userAgent = $_SERVER['HTTP_USER_AGENT'] ?? '';
$ipAddresses = [ $_SERVER['REMOTE_ADDR'] ];

try {
    $parser = Signature5::createFromRequest($signature, $ipAddresses, $userAgent, $cryptKey);
    $result = $parser->getResult();
    $humanReadable = Judge::RESULTS[$result];
    print $humanReadable['verdict'] . ' (' . $humanReadable['name'] . ')';
} catch (VersionException $e) {
    /*  It means that the signature is not the V5 one, check your zone settings and ensure the signatures
        are coming from the chosen zone. */
} catch (ParseException $e) {
    /*  It means that the signature metadata is malformed and cannot be parsed, or contains invalid data,
        check for corruption underway. */
} catch (VerifyException $e) {
    /*  Signature could not be verified - see error message for details. */
}
```

The first difference is that now `$cryptKey` may be also a `Closure` instance (lambda function), accepting single `int` argument - zone ID and returning raw key as binary string. This is useful in scenarios, where signatures coming from different zones are handled at a single point. This is not possible for V4 signatures, as they do not carry over any zone information.

As we can see, `createFromRequest` also requires a list of IP addresses and User Agent string. This is used for built-in verification routine, but this time the verification is completely unrelated to decryption. Client integrating might want to replace the verification with its own implementation, so here is the extended example (without any exception handling for readability):

```
use AdScore\Common\Signature\Signature5;

$signature = $_GET['signature'];
/*  An example structure holding keys for every zone supported */
$cryptKeys = [
    123 => \base64_decode("123456789abcdefghijklmn")
];

$parser = new Signature5();
/*  Parsing/decryption stage */
$parser->parse($signature, function ($zoneId) use ($cryptKeys) {
    if (!isset($cryptKeys[$zoneId])) {
        throw new RuntimeException('Unsupported zone ' . $zoneId);
    }
    return $cryptKeys[$zoneId];
});
/*  The payload now contains a decrypted signature data which might be used to verify the signature */
$payload = $parser->getPayload();
/*  We can still make use of built-in signature validator and only then getResult() is being populated */
$userAgent = $_SERVER['HTTP_USER_AGENT'] ?? '';
$ipAddresses = [ $_SERVER['REMOTE_ADDR'] ];
$parser->verify($ipAddresses, $userAgent);
$result = $parser->getResult();
```

The `result` field and its associated `getResult()` getter method return result score only after a successful `verify()` call. This is expected behavior, to preserve compliance with V4 behavior - the result is only valid when it's proven belonging to a visitor. For custom integrations not relying on built-in verification routines (usually more tolerant), the result is present also in payload retrieved via `getPayload()` call, but it's then the integrator's reponsibility to ensure whether it's trusted or not. When desired validation is more strict than the built-in one, the `verify()` can be called first, populating `getResult()` value, and after that any additional verification may take place.

Note: V4 signature parser also holds the payload, but it does not contain any useful informations, only timestamps and signed strings; especially - it does not contain any Judge result value, it is derived from the signature via several hashing/verification approaches.

Integration
-----------

[](#integration)

Any questions you have with custom integration, please contact our . Please remember that we do require adequate technical knowledge in order to be able to help with the integration; there are other integration methods which do not require any, or require very little programming.

###  Health Score

37

—

LowBetter than 83% of packages

Maintenance63

Regular maintenance activity

Popularity28

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

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

Recently: every ~180 days

Total

7

Last Release

223d ago

### Community

Maintainers

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

---

Top Contributors

[![bderleta](https://avatars.githubusercontent.com/u/4968080?v=4)](https://github.com/bderleta "bderleta (18 commits)")

---

Tags

adscoresignaturetrafficadscore

### Embed Badge

![Health badge](/badges/adscore-php-common/health.svg)

```
[![Health](https://phpackages.com/badges/adscore-php-common/health.svg)](https://phpackages.com/packages/adscore-php-common)
```

###  Alternatives

[laracrafts/laravel-url-shortener

Powerful URL shortening tools in Laravel

97110.7k](/packages/laracrafts-laravel-url-shortener)[ffi/location

PHP library for determining the physical location of binaries

1339.8k7](/packages/ffi-location)

PHPackages © 2026

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