Openx Api Client Laravel Package

Getting Started

1. Install and inspect first. Add the package with Composer.

   composer require rohea/openx-api-client
   

   Before writing any code, open composer.json in the package and check two things: (a) which XML-RPC transport it depends on (ext-xmlrpc, phpxmlrpc/phpxmlrpc, or a Zend component), and (b) whether the autoload is PSR-0 or PSR-4. This is a PHP5-era port; expect PSR-0 class paths and possibly a hard dependency on ext-xmlrpc, which was removed from PHP core in 8.0.

2. Check the source tree, not the README. Since this is a "work in progress", the README is likely thin. Read the client class and the Struct/type classes to see which OpenX v2 methods are actually implemented. Grep for function to get a real method list rather than trusting the docs.

3. Point at your OpenX/Revive endpoint. The classic v2 XML-RPC URL is:

   https://ads.example.com/www/api/v2/xmlrpc/
   

   or the ox/api/v2/xmlrpc/ plugin path on newer Revive installs. Confirm the endpoint responds by hitting logon first.

4. First use case: authenticate and list inventory. A good smoke test is to log on and pull the zone list for a publisher:

   // Verify namespace/class name in the repo first
   $client = new \Rohea\OpenXApiClient\OpenXApiClient(
       'https://ads.example.com/www/api/v2/xmlrpc/'
   );
   
   $sessionId = $client->logon('admin', 'secret');
   $zones     = $client->getZoneList($sessionId, $publisherId);
   print_r($zones);
   

   Once logon and getZoneList work, you have proven the transport, auth, and struct serialization are all functional.

Implementation Patterns

Wrap the client in a Laravel service. Bind it as a singleton on a dedicated manager, and keep the raw client out of controllers.

// AppServiceProvider
$this->app->singleton(OpenXManager::class, fn () => new OpenXManager(
    config('services.openx.endpoint'),
    config('services.openx.username'),
    config('services.openx.password'),
));

Use scoped() if you want a fresh session per request; use singleton() only inside queue workers where you control the lifecycle.

Manage the session explicitly. The v2 API is session-oriented: logon returns a session ID that must be passed as the first argument to nearly every subsequent call. Put this in the wrapper and cache it per request/job:

class OpenXManager {
    private ?string $sessionId = null;

    public function session(): string {
        return $this->sessionId ??= $this->client->logon($this->user, $this->pass);
    }

    public function __call($m, $args) {
        try {
            return $this->client->{$m}($this->session(), ...$args);
        } catch (XmlRpcFault $e) {
            if ($this->isSessionFault($e)) { $this->sessionId = null; }
            throw $e;
        }
    }
}

Typical ad-ops workflow — create a campaign end-to-end:

1. addAdvertiser → returns advertiser ID.
2. addCampaign (start/end dates, impressions, clicks, priority, weight) → campaign ID.
3. addBanner (campaign ID, name, storage type, image/HTML, size) → banner ID.
4. linkBanner (banner ID + zone ID) to put it live.

Store the returned OpenX IDs on your local models (e.g. advertisers.openx_id) so subsequent syncs can update rather than duplicate.

Reporting ingestion. Nightly jobs calling getCampaignStatistics / getBannerStatistics / getZoneStatistics and writing rows into a local ad_stats table is the single most common production use. Always pass a narrow startDate/endDate range, and use the statsBreakdown struct to request only the dimensions you need.

Sync jobs over webhooks. Treat the API as a batch system: queue jobs, chunk over ID lists, and make each operation idempotent by checking for an existing remote ID before creating.

Gotchas and Tips

• License is GPL-2.0. This is the biggest risk for a commercial Laravel app — GPL is viral copyleft. Treat it as an internal-tool-only dependency or fork it under a compatible license before shipping in proprietary software.
• "Work in progress" means partial coverage. Do not assume a method exists. The upstream OpenX v2 API has dozens of methods; this port likely covers a subset (agencies, advertisers, campaigns, banners, zones, stats). Missing methods require you to add them or bypass the wrapper with a raw XML-RPC call.
• ext-xmlrpc is gone in PHP 8. If the package calls xmlrpc_encode_request / xmlrpc_decode, it will not run on modern PHP. You'll need to shim it or swap the transport for phpxmlrpc/phpxmlrpc.
• No dependents, 13 stars, low activity. Pin the version and vendor/audit it. Expect no security patches; budget for a fork if you depend on it long term.
• Session expiry and faults. OpenX faults look like generic XML-RPC faults; a session timeout is not always distinguishable from a permissions error. Log the raw fault code/message and re-logon on the recognizable session-expired codes only.
• Type strictness. OpenX structs expect integers, floats, booleans, and ISO-8601 dates. PHP sends "1" where 1 is needed, or 0 where false is needed, and the API rejects or silently misbehaves. Cast aggressively before building structs.
• Dates and timezone. Date fields use the OpenX server's timezone, not yours. Convert explicitly with DateTime + setTimezone rather than date().
• Stats API is expensive. Full-history global stats calls can time out the ad server. Paginate by date and set an HTTP timeout on the client; large pulls should be resumable jobs.
• Debugging. Log the raw XML request and response (temporarily wrapping the transport is the cleanest extension point). The API error messages are often vague; the raw XML is the only reliable signal.
• Extension points. Subclass the client or the wrapper to add missing methods; the struct classes are usually simple value objects you can extend with typed builders to avoid hand-writing arrays on every add* call.