PHPackages                             villaflor/taboola-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. [API Development](/categories/api)
4. /
5. villaflor/taboola-sdk

ActiveLibrary[API Development](/categories/api)

villaflor/taboola-sdk
=====================

This package contains the open source PHP SDK that allows you to access the Taboola Platform from your PHP application.

2.0.0(2mo ago)069↓100%MITPHPPHP ^8.3CI passing

Since Aug 15Pushed 2mo ago1 watchersCompare

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

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

Taboola SDK for PHP
===================

[](#taboola-sdk-for-php)

[![Tests](https://github.com/villaflor/taboola-sdk/actions/workflows/test.yml/badge.svg)](https://github.com/villaflor/taboola-sdk/actions/workflows/test.yml)[![Code Quality](https://github.com/villaflor/taboola-sdk/actions/workflows/lint.yml/badge.svg)](https://github.com/villaflor/taboola-sdk/actions/workflows/lint.yml)[![Latest Version on Packagist](https://camo.githubusercontent.com/8177f65e78a269d5e397f63727b054fa8bd0d558f3850f6176cd6a8822e89216/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f76696c6c61666c6f722f7461626f6f6c612d73646b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/villaflor/taboola-sdk)[![Total Downloads](https://camo.githubusercontent.com/432f7b13b73280890ddcf6d10be84f9cc69e62da48cb9f0c9fce41477445f0e0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f76696c6c61666c6f722f7461626f6f6c612d73646b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/villaflor/taboola-sdk)

This package provides a modern, type-safe PHP SDK for the Taboola Platform API with comprehensive endpoint coverage.

Features
--------

[](#features)

- ✅ **Complete API Coverage**: All major Taboola API endpoints
- ✅ **Type-Safe**: Immutable DTOs with strict types
- ✅ **SOLID Principles**: Clean, maintainable architecture
- ✅ **Modern PHP**: PHP 8.3+ with latest features
- ✅ **Production-Ready Examples**: 7 comprehensive usage examples
- ✅ **Well Documented**: Extensive PHPDoc and guides
- ✅ **Error Handling**: Custom exceptions with context
- ✅ **Testing Ready**: Complete fixture system for testing
- ✅ **100% Test Coverage**: Fully tested with realistic fixtures

Available Endpoints
-------------------

[](#available-endpoints)

### Authentication

[](#authentication)

- Get access token (OAuth 2.0)

### Account Management

[](#account-management)

- Get account details
- Get advertiser accounts in network
- Get allowed accounts

### Campaigns

[](#campaigns)

- Get all campaigns
- Get single campaign
- Create campaign
- Update campaign
- Delete campaign
- Duplicate campaign
- Bulk update campaigns

### Campaign Items (Ads)

[](#campaign-items-ads)

- Get all items
- Get single item
- Create item
- Update item
- Delete item
- Bulk create items
- Bulk update items
- Bulk delete items

### Reporting

[](#reporting)

- Campaign summary report
- Top campaign content report
- Realtime campaign report
- Realtime ads report

### Images

[](#images)

- Upload image to account
- Get media library taxonomies
- Get images from media library
- Upload to media library

### Targeting

[](#targeting)

- Get available publishers
- Get blocked publishers
- Update blocked publishers
- Get postal code targeting
- Update postal code targeting
- Get marketplace audience targeting
- Update marketplace audience targeting
- Get contextual targeting
- Update contextual targeting

### Audiences

[](#audiences)

- Get custom audiences
- Create custom audience
- Get marketplace audiences
- Get lookalike audiences
- Create lookalike audience
- Get contextual segments

### Conversion Tracking

[](#conversion-tracking)

- Get all conversion rules
- Get single conversion rule
- Create conversion rule
- Update conversion rule

### Dictionary/Reference

[](#dictionaryreference)

- Get countries
- Get regions by country
- Get cities by country
- Get postal codes
- Get platforms
- Get operating systems
- Get browsers

Requirements
------------

[](#requirements)

- PHP 8.3 or higher
- Taboola API credentials (Client ID, Client Secret, Account ID)

> **Note:** Request your `client_id` and `client_secret` from your Taboola Account Manager. Your `account_id`, as well as your client credentials, are provided during the API onboarding process.

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require villaflor/taboola-sdk
```

Quick Start
-----------

[](#quick-start)

Check out the [`examples/`](examples) directory for production-ready code samples:

1. **[Authentication](examples/01-authentication.php)** - OAuth 2.0 token flow
2. **[Campaign Management](examples/02-campaign-management.php)** - Complete CRUD operations
3. **[Bulk Operations](examples/03-bulk-operations.php)** - High-performance batch updates
4. **[Reporting](examples/04-reporting.php)** - Analytics and data export
5. **[Targeting Setup](examples/05-targeting-setup.php)** - Advanced targeting configuration
6. **[Image Upload](examples/06-image-upload.php)** - Media library management
7. **[Audience Creation](examples/07-audience-creation.php)** - Custom audience targeting

See the [Examples README](examples/README.md) for detailed documentation on running and using these examples.

Usage
-----

[](#usage)

### Authentication

[](#authentication-1)

First, authenticate with the Taboola API to obtain an access token:

```
use Villaflor\Connection\Auth\APIToken;
use Villaflor\Connection\Auth\None;
use Villaflor\TaboolaSDK\Configurations\AuthenticationConfiguration;
use Villaflor\TaboolaSDK\Endpoints\Authentication;
use Villaflor\TaboolaSDK\TaboolaClient;

$clientId = 'your-client-id';
$clientSecret = 'your-client-secret';
$accountId = 'your-account-id';

// Get access token
$authEndpoint = new Authentication(new TaboolaClient(new None()));
$response = $authEndpoint->getAccessToken(
    new AuthenticationConfiguration($clientId, $clientSecret)
);

// Access token is now type-safe with AuthenticationResponse DTO
$accessToken = $response->accessToken;
$expiresIn = $response->expiresIn;
$tokenType = $response->tokenType;
```

### Working with Accounts

[](#working-with-accounts)

```
use Villaflor\TaboolaSDK\Configurations\Account\AccountDetailsConfiguration;
use Villaflor\TaboolaSDK\Configurations\Account\AdvertiserAccountsInNetworkConfiguration;
use Villaflor\TaboolaSDK\Configurations\Account\AllowedAccountsConfiguration;
use Villaflor\TaboolaSDK\Endpoints\Account;

// Create authenticated client
$client = new TaboolaClient(new APIToken($accessToken));
$account = new Account($client);

// Get account details - Returns AccountResponse DTO
$details = $account->getAccountDetails(new AccountDetailsConfiguration());
$accountData = $details->body;

// Get advertiser accounts in network - Returns CollectionResponse DTO
$advertisers = $account->getAdvertiserAccountsInNetwork(
    new AdvertiserAccountsInNetworkConfiguration($accountId)
);
$results = $advertisers->results;
$metadata = $advertisers->metadata;

// Get allowed accounts - Returns CollectionResponse DTO
$allowed = $account->getAllowedAccounts(new AllowedAccountsConfiguration());
```

### Managing Campaigns

[](#managing-campaigns)

```
use Villaflor\TaboolaSDK\Configurations\Campaigns\AllCampaignsConfiguration;
use Villaflor\TaboolaSDK\Definitions\AllCampaignsFilterDefinition;
use Villaflor\TaboolaSDK\Endpoints\Campaigns;

$campaigns = new Campaigns($client);

// Get all campaigns - Returns CollectionResponse DTO
$response = $campaigns->getAllCampaigns(
    new AllCampaignsConfiguration(
        accountId: $accountId,
        filters: [
            AllCampaignsFilterDefinition::FETCH_LEVEL =>
                AllCampaignsFilterDefinition::FETCH_LEVEL_RECENT_AND_PAUSED_OPTIONS
        ]
    )
);

$campaignList = $response->results;
$metadata = $response->metadata;
```

### Generating Reports

[](#generating-reports)

```
use Villaflor\TaboolaSDK\Configurations\Reporting\CampaignSummaryConfiguration;
use Villaflor\TaboolaSDK\Configurations\Reporting\TopCampaignContentConfiguration;
use Villaflor\TaboolaSDK\Definitions\CampaignSummaryDimensionDefinition;
use Villaflor\TaboolaSDK\Definitions\CampaignSummaryFilterDefinition;
use Villaflor\TaboolaSDK\Definitions\TopCampaignContentDimensionDefinition;
use Villaflor\TaboolaSDK\Definitions\TopCampaignContentFilterDefinition;
use Villaflor\TaboolaSDK\Endpoints\Reporting;

$reporting = new Reporting($client);

// Campaign summary report - Returns ReportResponse DTO
$summary = $reporting->getCampaignSummaryReport(
    new CampaignSummaryConfiguration(
        accountId: $accountId,
        dimension: CampaignSummaryDimensionDefinition::CAMPAIGN_DAY_BREAKDOWN,
        filters: [
            CampaignSummaryFilterDefinition::START_DATE => '2021-08-01',
            CampaignSummaryFilterDefinition::END_DATE => '2021-08-31',
        ]
    )
);

// Access type-safe response properties
$timezone = $summary->timezone;
$results = $summary->results;
$recordCount = $summary->recordCount;
$metadata = $summary->metadata;

// Top campaign content report - Returns ReportResponse DTO
$topContent = $reporting->getTopCampaignContentReport(
    new TopCampaignContentConfiguration(
        accountId: $accountId,
        dimension: TopCampaignContentDimensionDefinition::ITEM_BREAKDOWN,
        filters: [
            TopCampaignContentFilterDefinition::START_DATE => '2021-08-01',
            TopCampaignContentFilterDefinition::END_DATE => '2021-08-31',
        ]
    )
);
```

Error Handling
--------------

[](#error-handling)

The SDK uses type-safe exceptions for better error handling:

```
use Villaflor\TaboolaSDK\Exceptions\JsonDecodeException;
use Villaflor\TaboolaSDK\Exceptions\TaboolaException;

try {
    $response = $authEndpoint->getAccessToken($config);
} catch (JsonDecodeException $e) {
    // Handle JSON decoding errors
    echo "Failed to decode API response: " . $e->getMessage();
} catch (TaboolaException $e) {
    // Handle other Taboola SDK errors
    echo "SDK Error: " . $e->getMessage();
}
```

Testing
-------

[](#testing)

The SDK includes a comprehensive test suite with 100% code coverage and realistic API response fixtures.

### Run Tests

[](#run-tests)

```
composer test
```

### Generate Coverage Report

[](#generate-coverage-report)

```
composer test-coverage
```

### Run Static Analysis

[](#run-static-analysis)

```
composer analyse
```

### Format Code

[](#format-code)

```
composer format
```

### Testing with Fixtures

[](#testing-with-fixtures)

The SDK includes 47 realistic API response fixtures based on official Taboola documentation. You can use these in your own tests:

```
use function Tests\loadFixture;
use function Tests\mockResponseFromFixture;
use function Tests\mockResponse;

// Load fixture data as array
$data = loadFixture('Campaigns/single_campaign.json');

// Create mock response from fixture
$response = mockResponseFromFixture('Campaigns/single_campaign.json');

// Create mock response from array
$response = mockResponse(['status' => 'success']);
```

See the [Fixtures README](tests/Fixtures/README.md) for complete documentation.

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Mark Anthony Villaflor](https://github.com/villaflor)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE) for more information.

###  Health Score

45

—

FairBetter than 93% of packages

Maintenance84

Actively maintained with recent releases

Popularity10

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity67

Established project with proven stability

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

Total

2

Last Release

80d ago

Major Versions

1.0.0 → 2.0.02026-01-01

PHP version history (2 changes)1.0.0PHP ^7.4|^8.0

2.0.0PHP ^8.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/60b659450734f21a7a920500011a61a9996cb5112cf18a05bf8131916167e50a?d=identicon)[villaflor](/maintainers/villaflor)

---

Top Contributors

[![villaflor](https://avatars.githubusercontent.com/u/15763160?v=4)](https://github.com/villaflor "villaflor (29 commits)")

---

Tags

apisdkvillaflortaboolataboola-sdk

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/villaflor-taboola-sdk/health.svg)

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

###  Alternatives

[deepseek-php/deepseek-php-client

deepseek PHP client is a robust and community-driven PHP client library for seamless integration with the Deepseek API, offering efficient access to advanced AI and data processing capabilities.

46554.9k5](/packages/deepseek-php-deepseek-php-client)[jstolpe/instagram-graph-api-php-sdk

Instagram Graph API PHP SDK

13994.9k1](/packages/jstolpe-instagram-graph-api-php-sdk)

PHPackages © 2026

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