包简介

An HTTP-header-based "access / entitlement token" library for Zero Ad Network partnering sites using PHP

README 文档

README

The official PHP module for integrating websites with the Zero Ad Network platform.

What is Zero Ad Network?

Zero Ad Network is a browser-based platform that creates a better web experience for both users and content creators:

For Users:

Browse without ads, trackers, cookie consent dialogs, and marketing pop-ups
Access paywalled content across multiple sites with a single subscription
Support content creators directly through fair revenue distribution

For Publishers:

Generate revenue from users who would otherwise use ad blockers
Provide a cleaner user experience while maintaining income
Get paid based on actual user engagement with your content

How It Works:

Users subscribe and install the Zero Ad Network browser extension
The extension sends cryptographically signed tokens to partner sites
Partner sites verify tokens and enable premium features (ad-free, paywall-free)
Monthly revenue is distributed to publishers based on user engagement time

Features

This module provides:

✅ Zero dependencies - Lightweight and secure (only requires ext-sodium)
✅ Cryptographic verification - ED25519 signature validation using ext-sodium
✅ Performance optimized - Built-in APCu caching for 10-20x performance boost
✅ PHP 7.2+ compatible - Works with legacy and modern PHP versions
✅ Easy integration - Simple API with minimal configuration

Runtime Compatibility

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

Required:

ext-sodium (included by default in PHP 7.2+)

Recommended:

ext-apcu (for caching - provides 10-20x performance improvement)

Installation

composer require zeroad.network/token

Optional: Install APCu for Caching

Highly recommended for production environments:

# Debian/Ubuntu
sudo apt-get install php-apcu

# CentOS/RHEL
sudo yum install php-pecl-apcu

# Enable in php.ini
extension=apcu.so
apc.enabled=1
apc.shm_size=32M

Quick Start

1. Register Your Site

Before implementing, you need to:

Sign up for a Zero Ad Network account
Register your site to receive your unique Client ID

2. Choose Your Features

Decide which features your site will support:

Constants::FEATURE['CLEAN_WEB']: Remove ads, cookie consent screens, trackers, and marketing dialogs
Constants::FEATURE['ONE_PASS']: Provide free access to paywalled content and base subscription plans

3. Basic Implementation

<?php

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

use ZeroAd\Token\Site;
use ZeroAd\Token\Constants;

// Initialize once at startup
$site = new Site([
  "clientId" => "YOUR_CLIENT_ID_HERE",
  "features" => [Constants::FEATURE["CLEAN_WEB"], Constants::FEATURE["ONE_PASS"]]
]);

// In your middleware/controller
header("{$site->SERVER_HEADER_NAME}: {$site->SERVER_HEADER_VALUE}");

// Parse the user's subscription token
$tokenContext = $site->parseClientToken($_SERVER[$site->CLIENT_HEADER_NAME] ?? null);

// Use token context in templates
render("index", ["tokenContext" => $tokenContext]);

4. In Your Templates

<!-- index.php -->
<!DOCTYPE html>
<html>
<head>
  <title>My Site</title>
</head>
<body>
  <h1>Welcome to My Site</h1>
  
  <!-- Only show ads to non-subscribers -->
  <?php if (!$tokenContext["HIDE_ADVERTISEMENTS"]): ?>
    <div class="advertisement">
      <!-- Ad code here -->
    </div>
  <?php endif; ?>
  
  <!-- Only show cookie consent to non-subscribers -->
  <?php if (!$tokenContext["HIDE_COOKIE_CONSENT_SCREEN"]): ?>
    <div class="cookie-consent">
      <!-- Cookie consent dialog -->
    </div>
  <?php endif; ?>
  
  <!-- Content -->
  <article>
    <h2>Article Title</h2>
    
    <!-- Show preview or full content based on subscription -->
    <?php if ($tokenContext["DISABLE_CONTENT_PAYWALL"]): ?>
      <p>Full article content for Zero Ad Network subscribers...</p>
    <?php else: ?>
      <p>Article preview... <a href="/subscribe">Subscribe to read more</a></p>
    <?php endif; ?>
  </article>
</body>
</html>

Token Context

After parsing, the token context contains boolean flags for each feature:

[
  // CLEAN_WEB features
  "HIDE_ADVERTISEMENTS" => bool,
  "HIDE_COOKIE_CONSENT_SCREEN" => bool,
  "HIDE_MARKETING_DIALOGS" => bool,
  "DISABLE_NON_FUNCTIONAL_TRACKING" => bool,

  // ONE_PASS features
  "DISABLE_CONTENT_PAYWALL" => bool,
  "ENABLE_SUBSCRIPTION_ACCESS" => bool
];

Important: All flags default to false for:

Users without subscriptions
Expired tokens
Invalid/forged tokens
Missing tokens

Performance & Caching

APCu Cache (Highly Recommended)

The module includes built-in APCu caching to dramatically improve performance by avoiding redundant cryptographic operations.

Performance Impact:

Without cache: ~100-200μs per token verification
With APCu cache: ~10-20μs per cached token (10-20x faster!)
Cache is shared between all PHP-FPM workers
Automatically respects token expiration

Configuration

use ZeroAd\Token\Site;
use ZeroAd\Token\Constants;

$site = new Site([
  "clientId" => "YOUR_CLIENT_ID",
  "features" => [Constants::FEATURE["CLEAN_WEB"]],
  "cacheConfig" => [
    "ttl" => 10, // Cache for 10 seconds (default: 5)
    "prefix" => "myapp:zeroad:" // Custom cache key prefix
  ]
]);

How Caching Works:

Token header is hashed (xxHash) to create cache key
If cached and not expired, returns immediately (~15μs)
If cache miss, performs crypto verification (~150μs)
Result cached with TTL = min(config TTL, token expiry time)
Expired tokens automatically removed from cache

Cache automatically respects token expiration - even with long cache TTL, expired tokens are never served from cache.

Without APCu

If APCu is not available, the module works normally but performs full crypto verification on every request. Consider:

Enabling OPcache to cache compiled PHP code
Using a reverse proxy cache (Varnish, nginx)
Installing APCu for best performance

Performance Benchmarks

Typical performance on modern hardware:

Operation	Without Cache	With APCu Cache	Improvement
Parse token	~150μs	~15μs	10x faster
1000 req/sec	150ms blocking	15ms blocking	90% less CPU

Advanced Configuration

Cache Configuration

use ZeroAd\Token\Site;
use ZeroAd\Token\Constants;

$site = new Site([
  "clientId" => $_ENV["ZERO_AD_CLIENT_ID"],
  "features" => [Constants::FEATURE["CLEAN_WEB"]],
  "cacheConfig" => [
    "ttl" => 10, // Cache for 10 seconds
    "prefix" => "myapp:zeroad:" // Namespace your cache keys
  ]
]);

Recommended TTL Settings:

Scenario	TTL	Reason
High traffic (1000+ req/sec)	10-30s	Maximize cache hits
Normal traffic (100-1000 req/sec)	5-10s	Balance freshness and performance
Low traffic (<100 req/sec)	2-5s	Keep data fresh

Logging

Set Log Level:

use ZeroAd\Token\Logger;

// Development
Logger::setLogLevel("debug"); // error, warn, info, debug

// Production
Logger::setLogLevel("error");

Custom Log Handler:

use ZeroAd\Token\Logger;

// Integrate with Monolog
$monolog = new Monolog\Logger("zeroad");
$monolog->pushHandler(new StreamHandler("/var/log/zeroad.log"));

Logger::setLogHandler(function ($level, $message) use ($monolog) {
  $monolog->log($level, $message);
});

// Disable logging in production
Logger::setLogHandler(function ($level, $message) {
  // No-op: discard all logs
});

// Send errors to monitoring service
Logger::setLogHandler(function ($level, $message) {
  if ($level === "error") {
    Sentry\captureMessage($message);
  }
});

Security

Token Verification

All tokens are cryptographically signed using ED25519 by Zero Ad Network:

Signature verification happens locally on your server using Zero Ad Network's official public key
Trusted authority - Only tokens signed by Zero Ad Network are valid
No external API calls - verification is instant and offline
Tamper-proof - modified tokens fail verification automatically (constant-time comparison)
Time-limited - expired tokens are automatically rejected

Token Structure

Each token contains:

Protocol version - Currently v1
Nonce - Random 4-byte value
Expiration timestamp - Unix timestamp
Feature flags - Bitmask of enabled features
Client ID (optional) - For developer tokens
Cryptographic signature - ED25519 signature

Example token:

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

Privacy

Tokens contain no personally identifiable information:

❌ No user IDs
❌ No email addresses
❌ No tracking data
✅ Only: expiration date and feature flags

Framework Examples

Laravel

// app/Http/Middleware/ZeroAdNetwork.php
<?php

namespace App\Http\Middleware;

use Closure;
use ZeroAd\Token\Site;
use ZeroAd\Token\Constants;

class ZeroAdNetwork
{
    private $site;

    public function __construct()
    {
        $this->site = new Site([
            'clientId' => config('zeroad.client_id'),
            'features' => [Constants::FEATURE['CLEAN_WEB'], Constants::FEATURE['ONE_PASS']],
            'cacheConfig' => ['ttl' => 10]
        ]);
    }

    public function handle($request, Closure $next)
    {
        // Set Welcome Header
        header("{$this->site->SERVER_HEADER_NAME}: {$this->site->SERVER_HEADER_VALUE}");

        // Parse token
        $tokenContext = $this->site->parseClientToken(
            $_SERVER[$this->site->CLIENT_HEADER_NAME] ?? null
        );

        // Add to request
        $request->attributes->set('tokenContext', $tokenContext);

        return $next($request);
    }
}

// In your controller
public function index(Request $request)
{
    $tokenContext = $request->attributes->get('tokenContext');
    return view('index', ['tokenContext' => $tokenContext]);
}

Symfony

// src/EventListener/ZeroAdNetworkListener.php
<?php namespace App\EventListener;

use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\Event\ResponseEvent;
use ZeroAd\Token\Site;
use ZeroAd\Token\Constants;

class ZeroAdNetworkListener
{
  private $site;

  public function __construct(string $clientId)
  {
    $this->site = new Site([
      "clientId" => $clientId,
      "features" => [Constants::FEATURE["CLEAN_WEB"]],
      "cacheConfig" => ["ttl" => 10]
    ]);
  }

  public function onKernelRequest(RequestEvent $event)
  {
    $request = $event->getRequest();

    $tokenContext = $this->site->parseClientToken($_SERVER[$this->site->CLIENT_HEADER_NAME] ?? null);

    $request->attributes->set("tokenContext", $tokenContext);
  }

  public function onKernelResponse(ResponseEvent $event)
  {
    $response = $event->getResponse();
    $response->headers->set($this->site->SERVER_HEADER_NAME, $this->site->SERVER_HEADER_VALUE);
  }
}

WordPress

// wp-content/themes/your-theme/functions.php
<?php

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

use ZeroAd\Token\Site;
use ZeroAd\Token\Constants;

// Initialize once
$GLOBALS['zeroad_site'] = new Site([
    'clientId' => get_option('zeroad_client_id'),
    'features' => [Constants::FEATURE['CLEAN_WEB'], Constants::FEATURE['ONE_PASS']],
    'cacheConfig' => ['ttl' => 10]
]);

// Add Welcome Header
add_action('send_headers', function() {
    $site = $GLOBALS['zeroad_site'];
    header("{$site->SERVER_HEADER_NAME}: {$site->SERVER_HEADER_VALUE}");
});

// Parse token and make available globally
add_action('init', function() {
    $site = $GLOBALS['zeroad_site'];
    $GLOBALS['zeroad_context'] = $site->parseClientToken(
        $_SERVER[$site->CLIENT_HEADER_NAME] ?? null
    );
});

// Use in templates
function zeroad_context() {
    return $GLOBALS['zeroad_context'] ?? [];
}

// In your template files
<?php if (!zeroad_context()['HIDE_ADVERTISEMENTS']): ?>
    <!-- Show ads -->
<?php endif; ?>

Complete Usage Example

<?php

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

use ZeroAd\Token\Site;
use ZeroAd\Token\Constants;
use ZeroAd\Token\Logger;

// Configure logging
Logger::setLogLevel("error");

// Initialize site instance
$site = new Site([
  "clientId" => $_ENV["ZERO_AD_CLIENT_ID"] ?? "DEMO-Z2CclA8oXIT1e0Qmq",
  "features" => [Constants::FEATURE["CLEAN_WEB"], Constants::FEATURE["ONE_PASS"]],
  "cacheConfig" => [
    "ttl" => 10,
    "prefix" => "myapp:zeroad:"
  ]
]);

// Middleware function
function tokenMiddleware($site, callable $handler)
{
  // Set Welcome Header
  header("{$site->SERVER_HEADER_NAME}: {$site->SERVER_HEADER_VALUE}");

  // Parse token
  $tokenContext = $site->parseClientToken($_SERVER[$site->CLIENT_HEADER_NAME] ?? null);

  // Call handler with context
  $handler($tokenContext);
}

// Routes
$uri = $_SERVER["REQUEST_URI"];

if ($uri === "/") {
  tokenMiddleware($site, function ($tokenContext) {
    require __DIR__ . "/views/index.php";
  });
} elseif ($uri === "/article/1") {
  tokenMiddleware($site, function ($tokenContext) {
    $article = [
      "title" => "The Future of Web Publishing",
      "preview" => "In recent years, the landscape has changed...",
      "fullContent" => "Full article content here..."
    ];
    require __DIR__ . "/views/article.php";
  });
} elseif ($uri === "/api/premium") {
  tokenMiddleware($site, function ($tokenContext) {
    header("Content-Type: application/json");

    if (!$tokenContext["ENABLE_SUBSCRIPTION_ACCESS"]) {
      http_response_code(403);
      echo json_encode(["error" => "Premium subscription required"]);
      return;
    }

    echo json_encode(["data" => "Premium content"]);
  });
} else {
  http_response_code(404);
  echo "Not Found";
}

Implementation Requirements

When implementing Zero Ad Network features, you must fulfill these requirements to remain in good standing:

CLEAN_WEB Requirements

✅ Disable all advertisements on the page
✅ Disable all cookie consent screens (headers, footers, dialogs)
✅ Fully opt out users from non-functional trackers
✅ Disable all marketing dialogs or popups (newsletters, promotions)

ONE_PASS Requirements

✅ Provide free access to content behind paywalls
✅ Provide free access to your base subscription plan (if applicable)

⚠️ Failure to comply will result in removal from the Zero Ad Network platform.

Troubleshooting

Tokens Not Working

use ZeroAd\Token\Logger;

// Enable debug logging
Logger::setLogLevel("debug");

// Check if token is being received
$headerValue = $_SERVER[$site->CLIENT_HEADER_NAME] ?? null;
error_log("Header value: " . ($headerValue ?? "NULL"));

// Verify token context
$context = $site->parseClientToken($headerValue);
error_log("Token context: " . json_encode($context));

Check APCu Status

if (!extension_loaded("apcu") || !apcu_enabled()) {
  error_log("WARNING: APCu not available - caching disabled");
} else {
  error_log("APCu enabled - caching active");
}

Common Issues

All flags are false - Token is expired, invalid, or missing
Performance slow - Install APCu for 10-20x speedup
Token rejected - Verify Client ID matches registered site
Headers not sent - Ensure header() is called before any output

API Reference

`Site`

Creates a site instance with helper methods.

$site = new Site([
    'clientId' => 'YOUR_CLIENT_ID',          // Required: Your Zero Ad Network client ID
    'features' => [Constants::FEATURE[...]],  // Required: Array of feature flags
    'cacheConfig' => [                        // Optional: Cache configuration
        'ttl' => 5,                           // Cache TTL in seconds
        'prefix' => 'zeroad:token:'           // Cache key prefix
    ]
]);

// Properties
$site->CLIENT_HEADER_NAME;    // Request header name (e.g., "HTTP_X_BETTER_WEB_HELLO")
$site->SERVER_HEADER_NAME;    // Response header name ("X-Better-Web-Welcome")
$site->SERVER_HEADER_VALUE;   // Response header value (encoded)

// Methods
$context = $site->parseClientToken(?string $headerValue): array

`Constants`

use ZeroAd\Token\Constants;

// Features
Constants::FEATURE['CLEAN_WEB']  // = 1
Constants::FEATURE['ONE_PASS']   // = 2

// Headers
Constants::SERVER_HEADER['WELCOME']  // = "X-Better-Web-Welcome"
Constants::CLIENT_HEADER['HELLO']    // = "X-Better-Web-Hello"

// Protocol
Constants::CURRENT_PROTOCOL_VERSION  // = 1

`Logger`

use ZeroAd\Token\Logger;

Logger::setLogLevel(string $level): void
// Set minimum log level: 'error', 'warn', 'info', 'debug'

Logger::setLogHandler(?callable $handler): void
// Set custom log handler: function(string $level, string $message): void

Logger::log(string $level, ...$args): void
// Log a message

Resources

License

Apache License 2.0 - see LICENSE file for details

About Zero Ad Network

Zero Ad Network is building a fairer internet where:

Users enjoy cleaner, faster browsing
Publishers earn sustainable revenue
Privacy is respected by default

Join thousands of publishers creating a better web experience.

Get Started →

zeroad.network/token 适用场景与选型建议

zeroad.network/token 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 37 次下载、GitHub Stars 达 0，最近一次更新时间为 2025 年 11 月 29 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「php」「authorization」「api」「composer」「subscription」「middleware」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 zeroad.network/token 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 zeroad.network/token 我们能提供哪些服务？

定制开发 / 二次开发

基于 zeroad.network/token 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 zeroad.network/token 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

vantt/oauth2-hydra-php 0

Ory-Hydra OAuth 2.0 Client Provider for The PHP League OAuth2-Client

gener1c-code/oauth2-server 0

A lightweight and powerful OAuth 2.0 authorization and resource server library with support for all the core specification grants. This library will allow you to secure your API with OAuth and allow your applications users to approve apps that want to access their data from your API.

theodorejb/phaster 6

A PSR-7 compatible library for making CRUD API endpoints

diplodocker/auth-service 0

Laravel JWT auth service package

shahariaazam/zoho-oauth2 1

Zoho OAuth 2.0 Client Provider for The PHP League OAuth2-Client

foxtes/alfabank-rest 1

Alfabank REST API integration

zeroad.network/token

包简介

关键字：