PHPackages                             ridebuilder/affiliate - 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. ridebuilder/affiliate

ActiveLibrary

ridebuilder/affiliate
=====================

Server-side SDK for RideBuilder FirstParty affiliate tracking: capture click\_id and send checkout/return postbacks.

v0.1.1(today)00MITPHPPHP >=8.1

Since Aug 4Pushed todayCompare

[ Source](https://github.com/RideBuilder/affiliate-php)[ Packagist](https://packagist.org/packages/ridebuilder/affiliate)[ Docs](https://ridebuilder.com)[ RSS](/packages/ridebuilder-affiliate/feed)WikiDiscussions main Synced today

READMEChangelogDependenciesVersions (3)Used By (0)

ridebuilder/affiliate (PHP)
===========================

[](#ridebuilderaffiliate-php)

Server-side SDK for RideBuilder's FirstParty affiliate program. It does two things:

1. **Capture** the `click_id` a shopper arrives with, so your backend can bind it to the cart/order.
2. **Report** checkout and return postbacks to RideBuilder (auth, retries, idempotency handled).

Mirrors the Node/.NET/Python SDKs — same contract, verified by the shared [conformance suite](../conformance).

Install
-------

[](#install)

```
composer require ridebuilder/affiliate
```

Requires **PHP 8.1+** and `ext-curl` (bundled with virtually every PHP). No third-party runtime dependencies — the default transport uses cURL. To run from source without Composer, `require 'sdk/php/autoload.php'`.

The pattern: capture at landing, bind to the order
--------------------------------------------------

[](#the-pattern-capture-at-landing-bind-to-the-order)

Capture the `click_id` on landing, store it with the cart, and send it at purchase.

```
use RideBuilder\Affiliate\{RideBuilderClient, Capture, CheckoutInput};

// 1. On landing, read a validated click_id off the request URL and persist it onto YOUR cart record.
$clickId = Capture::fromUrl($_SERVER['REQUEST_URI']);
if ($clickId !== null) {
    $cart->ridebuilderClickId = $clickId;
}

// 2. At order time, send the postback from your backend.
$rb = new RideBuilderClient(apiKey: getenv('RIDEBUILDER_API_KEY'));
$rb->reportCheckout(new CheckoutInput(
    orderId: $order->id,
    subtotal: '199.99',   // major units; string keeps it exact
    currency: 'USD',
    clickId: $order->ridebuilderClickId,
));
```

Store the API key server-side (env/secrets) — never in frontend code.

Decoupled frontend (e.g. React) + separate PHP backend
------------------------------------------------------

[](#decoupled-frontend-eg-react--separate-php-backend)

If the frontend is separate, the browser **snippet** captures the `click_id` into a first-party cookie, and you get it to your backend one of two ways:

```
// Same registrable domain — the cookie rides along; read it off the Cookie header:
$clickId = Capture::fromCookieHeader($_SERVER['HTTP_COOKIE'] ?? null);

// Cross-domain / mobile — the frontend forwards it in the checkout call:
$clickId = Capture::fromHeaders(getallheaders());   // default header: X-RideBuilder-Click-Id
```

Either way, `reportCheckout` is unchanged — that's the SDK's real value in a decoupled setup.

### Refunds

[](#refunds)

```
$rb->reportReturn(new ReturnInput(
    returnId: $refund->id, orderId: $order->id, refundAmount: '49.95', currency: 'USD',
));
```

Integration protocol (register / verify / heartbeat)
----------------------------------------------------

[](#integration-protocol-register--verify--heartbeat)

```
$rb = new RideBuilderClient(apiKey: $apiKey, environment: 'production'); // or 'sandbox'

$reg = $rb->register();   // handshake on install/startup; returns a stable integration id
$rb->verify();            // deploy/CI self-test — throws RideBuilderException on a bad/rotated key
$rb->heartbeat();         // periodic liveness (call from cron; PHP has no persistent process)
```

The SDK reports its own `type` (`php_sdk`), `version`, and default capabilities.

Capture helpers
---------------

[](#capture-helpers)

All validate `ref == "ridebuilder"` and the UUID-v4 `click_id`, returning `null` otherwise:

- `Capture::fromUrl($url)` — from an absolute or relative URL.
- `Capture::fromQuery($query)` — from a decoded query map.
- `Capture::fromCookieHeader($cookieHeader)` — recover it from the `ridebuilder_attribution` cookie.
- `Capture::fromHeaders($headers, $name = 'X-RideBuilder-Click-Id')` — from a forwarding header (decoupled path).

Client options
--------------

[](#client-options)

```
new RideBuilderClient(
    apiKey: $key,
    baseUrl: null,          // defaults to https://api.ridebuilder.com/v1
    maxRetries: 3,          // retries on network errors, timeouts, 5xx, 429
    timeoutMs: 10000,       // per-attempt timeout
    environment: 'production',
    transport: null,        // inject a RideBuilder\Affiliate\Transport\Transport (e.g. wrap a PSR-18 client)
);
```

`reportCheckout` / `reportReturn` return `PostbackResult(accepted, status)` (`202` = accepted, validated asynchronously). Invalid input throws a non-retryable `RideBuilderException`; auth/size failures (`401`, `413`) throw with `->status` and `->errorCode`. Amounts must be `> 0` with at most 2 decimal places (pass a **string** to avoid float rounding) or the call throws up front.

Tests
-----

[](#tests)

Plain PHP, no PHPUnit/Composer required:

```
php tests/conformance.php   # the shared cross-language fixtures
php tests/unit.php          # validation, capture, money, retry/error, identity
```

Contract
--------

[](#contract)

Wraps the RideBuilder affiliate REST contract — `POST /v1/postback/checkout`, `/postback/return`, `/postback/health`, the `/integration/*` endpoints, the `/redirect` link format, and API-key provisioning. Verified byte-for-byte against the Node/.NET/Python SDKs by the shared conformance fixtures.

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance100

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity33

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

Total

2

Last Release

0d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/245913199?v=4)[drider1219](/maintainers/drider1219)[@drider1219](https://github.com/drider1219)

---

Top Contributors

[![drider1219](https://avatars.githubusercontent.com/u/245913199?v=4)](https://github.com/drider1219 "drider1219 (3 commits)")

---

Tags

attributionaffiliatepostbackridebuilder

### Embed Badge

![Health badge](/badges/ridebuilder-affiliate/health.svg)

```
[![Health](https://phpackages.com/badges/ridebuilder-affiliate/health.svg)](https://phpackages.com/packages/ridebuilder-affiliate)
```

###  Alternatives

[jijunair/laravel-referral

Laravel package for a referral system

9635.2k](/packages/jijunair-laravel-referral)[hypeit/tradetracker-api-client

TradeTracker API client

1023.3k](/packages/hypeit-tradetracker-api-client)

PHPackages © 2026

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