PHPackages                             adquesto/adquesto-php-sdk - 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. adquesto/adquesto-php-sdk

ActiveLibrary

adquesto/adquesto-php-sdk
=========================

Adquesto PHP integration toolkit

v0.4.8(4y ago)31.4k1PHPPHP ^5.3.2 || ^7.0

Since Sep 4Pushed 4y ago3 watchersCompare

[ Source](https://github.com/adquesto/adquesto-php-sdk)[ Packagist](https://packagist.org/packages/adquesto/adquesto-php-sdk)[ RSS](/packages/adquesto-adquesto-php-sdk/feed)WikiDiscussions master Synced today

READMEChangelog (5)Dependencies (2)Versions (23)Used By (0)

Adquesto PHP SDK
================

[](#adquesto-php-sdk)

Easy custom integration with only few steps required to start displaying ads.

[![Travis-ci](https://camo.githubusercontent.com/fcf6818474c74e6eea3407fecdd87cc55af024dee39172c3a7444735948de0e5/68747470733a2f2f6170692e7472617669732d63692e6f72672f616471756573746f2f616471756573746f2d7068702d73646b2e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/adquesto/adquesto-php-sdk/)

Install
-------

[](#install)

`composer require adquesto/adquesto-php-sdk`

Quick start
-----------

[](#quick-start)

Create `Content` with your defaults to start serving ads.

```
use Adquesto\SDK\Content;
use Adquesto\SDK\InMemoryStorage;
use Adquesto\SDK\CurlHttpClient;
use Adquesto\SDK\PositioningSettings;

$adquesto = new Content(
    # Adquesto API endpoint that provides latest javascript
    'https://api.adquesto.com/v1/publishers/services/',
    # Unique Service identifier
    'Paste Service UUID here',
    # Implementation that will hold javascript file contents
    new InMemoryStorage,
    new CurlHttpClient,
    PositioningSettings::factory(PositioningSettings::STRATEGY_UPPER)
);
```

It is a façade which provides all of the functionalities for displaying ads and maintaining its placement.

Constructor arguments are:

`apiUrl` Adquesto services endpoint

`serviceId` Can be either a Service UUID or callable which is used when fetching javascript file contents from API. You can find yours by navigating to details of a service from Dashboard.

`storage` Instance of Storage implementation which holds javascript file contents to prevent performing API requests everytime we need to display it. We provide two implementations: `WordpressStorage` and `InMemoryStorage`

`httpClient` Implementation of HTTP client which is used to fetch JavaScript

`positioningSettings` Instance of an PositioningSettings that returns values that are used to position a quest during rendering the content. There are two pre-defined strategies: `PositioningSettings::STRATEGY_UPPER` and `PositioningSettings::STRATEGY_LOWER`. Use `factory` method as a best practice.

`contextProviders` (`optional`) An array of context providers which are used to get template values used in rendering javascript file. There are ready to use implementations which are functionaly divided, i.e. `ElementsContextProvider`.

Now, we can fetch javascript file that will eventually render ads.

```
use Adquesto\SDK\ElementsContextProvider;

try {
    $javascript = $adquesto->javascript([
        $elementsProvider = new ElementsContextProvider,
        new \Adquesto\SDK\SubscriptionsContextProvider,
    ]);
} catch (Adquesto\SDK\NetworkErrorException $e) {
    // Handle exception here
}
```

We can pass an array of context providers just like for constructor. They are responsible for replacing placeholders inside javascript file fetched from API with integration specific values.

Example above will return javascript source code what will use random IDs as containers for ads. It's then possible to fetch generated IDs by using methods:

```
$mainQuestElementId = $elementsProviders->mainQuestId();
$reminderQuestElementId = $elementsProviders->reminderQuestId();
```

### Automatic Ad placement

[](#automatic-ad-placement)

We provide method to help you place ad in best spot inside HTML content. To make use of it call `prepare` method with arguments:

- `htmlContent` which is an HTML of your content (eg. blog post)
- `adContainerHtml` is an HTML of a container, which will hold ad (eg. ``)
- `reminderAdContainerHtml` being the same as above, only difference it will hold reminder ad (``)

NOTE: `adContainerHtml` and `reminderAdContainerHtml` must be the same as those used when fetching javascript file.

```
$preparedContent = $adquesto->autoPrepare(
    $htmlContent,
    $adContainerHtml,
    $reminderAdContainerHtml
);
```

### Manual Ad placement

[](#manual-ad-placement)

You can also use function below to find `` and replace with the ad:

```
$preparedContent = $adquesto->manualPrepare(
    $htmlContent,
    $adContainerHtml,
    $reminderAdContainerHtml
);
```

If you just want to check if there is a div in the content use:

```
$hasQuesto = $adquesto->hasQuestoInContent($content);
```

The function will return `true` if `` exists in the content.

### Prepared content

[](#prepared-content)

Both `autoPrepare` and `manualPrepare` return `PreparedContent` instances which in addition to hold the content also has a flag which tells wether it is valid to display a questo - `isAdReady` method.

To apply JavaScript plugin source:

```
$preparedContent->setJavaScript($javascript);
```

Overview
--------

[](#overview)

### Javascript Storages

[](#javascript-storages)

We use Storage interface to communicate intentions related to javascript contents persistance not to perform multiple API calls and thus provide better user experience.

#### WordpressStorage

[](#wordpressstorage)

Uses Wordpress `get_option` function to persist Javascript file contents and caches it for 24 hours.

#### InMemoryStorage

[](#inmemorystorage)

Basic implementation which holds Javascript file contents in memory. Most likely used for poc use only.

### Context Providers

[](#context-providers)

To properly render javascript that displays ads we use template that should be populated with values that set few important variables. There are two ready to use implementations that provide them with nice interface.

#### ElementsContextProvider

[](#elementscontextprovider)

Most important context provider which tells names of HTML containers that are used for rendering ads. Constructor parameters are optional:

- `mainQuestId` Main ad element ID name (eg. `questo-container`)
- `reminderQuestId` Reminder ad element ID (eg. `questo-reminder-container`)
- `isDraft` Should Ad be displayed as a draft (false as default)
- `hasActiveCampaigns` bool or callable that should hold information about existing campaigns for your Service - changes are triggered using webhook and value is in the response along Service status

By default both `mainQuestId` and `reminderQuestId` are generated with random string.

*NOTE*: For all testing purposes, including preview mode in CMS of any kind, `isDraft` should be set to `true`.

#### SubscriptionsContextProvider

[](#subscriptionscontextprovider)

This provides variables that are crucial to enable Subscription feature alowing to identify readers authenticated via OAuth2.

```
$subscriberStorage = new SubscriberSessionStorage;
$subscriber = $subscriberStorage->get();
$daysLeft = $subscriber->valid_to->diff(new \DateTime)->days;

new SubscriptionsContextProvider(array(
    SubscriptionsContextProvider::IS_SUBSCRIPTION_ACTIVE => (int)$subscriber->isSubscriptionValid(),
    SubscriptionsContextProvider::IS_SUBSCRIPTION_RECURRING => (int)$isSubscriptionRecurring,
    SubscriptionsContextProvider::IS_SUBSCRIPTION_DAYS_LEFT => $daysLeft,
    SubscriptionsContextProvider::IS_SUBSCRIPTION_AVAILABLE => true,
    SubscriptionsContextProvider::AUTHORIZATION_ERROR => (string)$authorizationError,
    SubscriptionsContextProvider::IS_LOGGED_IN => $subscriber !== null,
    SubscriptionsContextProvider::AUTHORIZATION_URI => $authorizationUri,
    SubscriptionsContextProvider::LOGOUT_URI => $logoutUri,
    SubscriptionsContextProvider::USER_LOGIN => $subscriber->email,
));
```

### Subscriber support (via Adquesto OAuth2)

[](#subscriber-support-via-adquesto-oauth2)

We provide OAuth2 client that utilizes Adquesto backend to authorize users as subscribers. The steps are:

- Generate authorization link to Adquesto:

```
use Adquesto\SDK\OAuth2Client;
use Adquesto\SDK\CurlHttpClient;

$oauth2Client = new OAuth2Client(
    new CurlHttpClient,
    'client_id_here',
    'http://adquesto.com/subscriber',
    'http://api.adquesto.com/oauth2/token',
    'http://api.adquesto.com/oauth2/me',
    'your_redirect_uri'
);

$authorizationUrl = $oauth2Client->authorizationUrl();
```

- When User is redirected back, issue SubscriberManager method that will handle obtaining Subscriber information (including expire date)

```
$subscriberManager = new SubscriberManager($oauth2Client, new SubscriberSessionStorage);
$subsciber = $subscriberManager->handleRedirect($_GET['code']);
```

- Subscriber is now ready to be used. Thanks to `SubscriberSessionStorage` that information is persisted in session, so each request will have information about current Subscriber.

NOTE: It's important to run `$subscriber->isSubscriptionValid()` before anything that is related to ad-free experience.

### Webhooks

[](#webhooks)

We will send POST request to you Service webhook URL with `form-data` with one of the following actions. Each action represent changes that need to be undertaken on your end for coherent experience.

You should respond with JSON `{"status": "OK"}`. If not, we will retry using exponential back-off strategy for 10 times.

#### Service status update

[](#service-status-update)

Action: `questo_update_service_status_option`

Once received you should ask API back for current status. Example:

```
$serviceApiUrl = new \Adquesto\SDK\ServiceAPIUrl(
    'https://api.adquesto.com/v1/publishers/services/',
    'Paste Service UUID here'
);
$service = new \Adquesto\SDK\Service(
    $serviceApiUrl,
    new CurlHttpClient
);
$serviceStatusResponse = $service->fetchStatus();
```

In response there is an array with following keys:

- `status` tells if Service is accepted (`bool`)

Use this one to turn on and off any ad displaying related activity.

- `subscription` has subscriptions enabled (`bool`)

This one should be used when fetching Javascript plugin, as it tells whether to turn Subscriptions feature on or off.

- `hasActiveCampaigns` are there any campaigns and quests that are eligible to display by your Service.

#### Subscription status update

[](#subscription-status-update)

Action: `questo_update_subscription_option`

This one is fired when Subscription feature is toggled either on or off. Now to fetch the actual value please use same method as described for `Service status update`.

#### Forced Javascript update

[](#forced-javascript-update)

Action: `questo_force_update_javascript`

From time to time we might call your endpoint to tell that there is new Javascript file available so that you can update it in your Storage.

[![Image](https://camo.githubusercontent.com/23f07ae5a53fad803c6687c561f430eecee6984916b966fb6c114318f9efc297/68747470733a2f2f7777772e77656273657175656e63656469616772616d732e636f6d2f6367692d62696e2f63647261773f6c7a3d64476c3062475567536d463259584e6a636d6c776443426d62334a6a5a534231634752686447556763484a765932566b64584a6c436770425a4846315a584e306279302d535735305a576479595852706232343649464250553151674c336c7664584974414334474c5756755a48427661573530494864706447676741433847587742524256384155415a666167426b436d466a64476c7662676f6a4947357664475567636d6c6e6148516762325967516d466a613256755a446f67556d56685a475679494656565355516761584d675a3256755a584a686447566b43674169446743424267314a626e5a6862476b416754734655335276636d466e5a516f416753674c4c543441675549494f69424852565167626d5633414946304377434254786c4f41426b4f41475162553246325a53427064434270626742324351426f47464a6c63334276626d514167695147536c4e505469427a6447463064584d6754307341675673476247566d4149494c425143424b51704a5a694275623351734948646c4948647062477767636d5630636e6b4b43694e43636d3933633256794c543441416763364945356c654851675a32563049484941676a3447636d5541677a774643694d41676c77504143674956584e6c49475270633273675932466a61475541526730416777594952325630494646315a584d4167315548414351465a4143444741774b26733d706174656e74)](https://camo.githubusercontent.com/23f07ae5a53fad803c6687c561f430eecee6984916b966fb6c114318f9efc297/68747470733a2f2f7777772e77656273657175656e63656469616772616d732e636f6d2f6367692d62696e2f63647261773f6c7a3d64476c3062475567536d463259584e6a636d6c776443426d62334a6a5a534231634752686447556763484a765932566b64584a6c436770425a4846315a584e306279302d535735305a576479595852706232343649464250553151674c336c7664584974414334474c5756755a48427661573530494864706447676741433847587742524256384155415a666167426b436d466a64476c7662676f6a4947357664475567636d6c6e6148516762325967516d466a613256755a446f67556d56685a475679494656565355516761584d675a3256755a584a686447566b43674169446743424267314a626e5a6862476b416754734655335276636d466e5a516f416753674c4c543441675549494f69424852565167626d5633414946304377434254786c4f41426b4f41475162553246325a53427064434270626742324351426f47464a6c63334276626d514167695147536c4e505469427a6447463064584d6754307341675673476247566d4149494c425143424b51704a5a694275623351734948646c4948647062477767636d5630636e6b4b43694e43636d3933633256794c543441416763364945356c654851675a32563049484941676a3447636d5541677a774643694d41676c77504143674956584e6c49475270633273675932466a61475541526730416777594952325630494646315a584d4167315548414351465a4143444741774b26733d706174656e74)

Example below shows details of how javascript could be replaced with new one:

```
$javascript = $adquesto->requestJavascript();
if ($javascript) {
    $content->getStorage()->set($javascript);
}
```

### JavaScript Events

[](#javascript-events)

Click [here](JSPLUGIN.md#Events) to read about JavaScript events.

### Examples

[](#examples)

- [Auto prepare](examples/example_autoprepare.php)
- [Manual prepare](examples/example_manualprepare.php)
- [Webhook](examples/example_webhook.php)

###  Health Score

30

—

LowBetter than 64% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity19

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 53.8% 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 ~64 days

Recently: every ~273 days

Total

20

Last Release

1586d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/dd2d410dcebaaf53580df372af99e9e58d07764be1082f8d85ce8e50716f7901?d=identicon)[Kub-AT](/maintainers/Kub-AT)

![](https://www.gravatar.com/avatar/2de2302becd3039134ae998dd65afa26f6f7c95c8ffbfc57dad2273ae0053802?d=identicon)[georgios-apostolidis](/maintainers/georgios-apostolidis)

---

Top Contributors

[![michalsoczynski](https://avatars.githubusercontent.com/u/1793024?v=4)](https://github.com/michalsoczynski "michalsoczynski (14 commits)")[![Kub-AT](https://avatars.githubusercontent.com/u/345461?v=4)](https://github.com/Kub-AT "Kub-AT (11 commits)")[![ljanecki](https://avatars.githubusercontent.com/u/48034006?v=4)](https://github.com/ljanecki "ljanecki (1 commits)")

---

Tags

php

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/adquesto-adquesto-php-sdk/health.svg)

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

###  Alternatives

[kontent-ai/delivery-sdk-php

Kontent.ai Delivery SDK for PHP

4628.8k](/packages/kontent-ai-delivery-sdk-php)[quinninteractive/silverstripe-seo

An all-in-one SEO module for SilverStripe

3328.2k](/packages/quinninteractive-silverstripe-seo)[rosell-dk/dom-util-for-webp

Replace image URLs found in HTML

2316.7k4](/packages/rosell-dk-dom-util-for-webp)

PHPackages © 2026

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