PHP Composer Module Support

The PHP Composer module (available on Packagist) is designed for sites running PHP that participate in the Zero Ad Network program.

The zeroad.network/token module provides a lightweight, open-source, and fully tested HTTP-header-based "access/entitlement token" library with no external production dependencies.

For detailed guides and implementation instructions, see the official Zero Ad Network documentation.

Runtime Compatibility

Runtime	Version	Ready
PHP 7	7.2+	✅
PHP 8	8.0+	✅

Note: ext-sodium must be installed on your PHP runtime.

Purpose

The module allows site developers to:

• Inject a valid site's HTTP Response Header known as Welcome Header into every endpoint. Example:

  X-Better-Web-Welcome: "AZqnKU56eIC7vCD1PPlwHg^1^3"

• Detect and parse Zero Ad Network user's token sent via HTTP Request Header by their browser extension. Example:

  X-Better-Web-Hello: "Aav2IXRoh0oKBw==.2yZfC2/pM9DWfgX+von4IgWLmN9t67HJHLiee/gx4+pFIHHurwkC3PCHT1Kaz0yUhx3crUaxST+XLlRtJYacAQ=="

• Verify the token's integrity locally.

• Optionally generate a valid "Welcome Header" when siteId and features are provided.

Implementation Details

• Uses ext-sodium to verify token signatures with Zero Ad Network's public ED25519 key.
• Decodes token payload to extract protocol version, expiration timestamp, and site features.
• Generates a feature map with toggle states; expired tokens produce all flags as false.

Parsed token example:

{
  ADS_OFF: boolean,
  COOKIE_CONSENT_OFF: boolean,
  MARKETING_DIALOG_OFF: boolean,
  CONTENT_PAYWALL_OFF: boolean,
  SUBSCRIPTION_ACCESS_ON: boolean,
};

• Token verification happens locally; no data leaves your server.
• Adds roughly 0.06ms–0.6ms to endpoint execution time (based on M1 MacBook Pro tests).
• Redis caching tests showed local verification is faster than retrieving cached results.

Benefits of Joining

Partnering with Zero Ad Network allows your site to:

• Create a new revenue stream
• Provide a clean, unobstructed user experience
• Contribute to reshaping the internet into a joyful and user-friendly environment

Onboarding Your Site

1. Sign up with Zero Ad Network.
2. Register your site.
3. Receive your unique X-Better-Web-Welcome header.

Your site must include this header on all publicly accessible HTML or RESTful endpoints for the Zero Ad Network browser extension to recognize participation.

Module Installation

Install via PHP Composer:

composer require zeroad.network/token

Examples

The PHP module example demonstrates how to:

• Inject the "Welcome Header" into responses
• Parse the user's token from the request header
• Use the $tokenContext in controllers and templates

The most basic example looks like this:

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

// -----------------------------------------------------------------------------
// Module initialization (once at startup)
// -----------------------------------------------------------------------------
// Initialize the Zero Ad Network Site module.
// Option 1: Use pre-generated server "Welcome Header" value:
//   $site = new Site(getenv('ZERO_AD_NETWORK_WELCOME_HEADER_VALUE'));
// Option 2: Dynamically construct "Welcome Header" using siteId and features:
$site = new ZeroAd\Token\Site([
    'siteId' => "073C3D79-B960-4335-B948-416AC1E3DBD4",
    'features' => [
        ZeroAd\Token\Constants::FEATURES['ADS_OFF']
    ]
]);

// -----------------------------------------------------------------------------
// Middleware simulation function
// -----------------------------------------------------------------------------
function tokenMiddleware(callable $handler)
{
    global $site;

    // Inject the server "X-Better-Web-Welcome" header
    header("{$site->SERVER_HEADER_NAME}: {$site->SERVER_HEADER_VALUE}");

    // Read and parse the client's token header if present
    $tokenContext = $site->parseToken($_SERVER[$site->CLIENT_HEADER_NAME] ?? null);

    // Pass the parsed token context to the handler
    $handler($tokenContext);
}

// -----------------------------------------------------------------------------
// Routing example (basic PHP routing)
// -----------------------------------------------------------------------------
$uri = $_SERVER['REQUEST_URI'];

if ($uri === '/') {
    tokenMiddleware(function ($tokenContext) {
        // Render HTML page with token context for demonstration
        $template = '<html>
            <body>
                <h1>Hello</h1>
                <pre>tokenContext = ' . htmlspecialchars(json_encode($tokenContext, JSON_PRETTY_PRINT)) . '</pre>
            </body>
        </html>';
        echo $template;
    });
} elseif ($uri === '/json') {
    tokenMiddleware(function ($tokenContext) {
        // Return JSON response with token context
        header('Content-Type: application/json');
        echo json_encode([
            'message' => 'OK',
            'tokenContext' => $tokenContext
        ]);
    });
} else {
    // Handle 404 Not Found
    http_response_code(404);
    echo 'Not Found';
}