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 2026-01-01 18:06 UTC

Requires

• php: ^8.3
• ext-json: *
• villaflor/connection: ^5.0

Requires (Dev)

• laravel/pint: ^1.26
• mockery/mockery: ^1.6
• pestphp/pest: ^3.8
• phpstan/phpstan: ^2.1

MIT

• Mark Anthony Villaflor

• api
• sdk
• villaflor
• taboola
• taboola-sdk

README

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

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

Authentication

• Get access token (OAuth 2.0)

Account Management

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

Campaigns

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

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

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

Images

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

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

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

Conversion Tracking

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

Dictionary/Reference

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

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

You can install the package via composer:

composer require villaflor/taboola-sdk

Quick Start

Check out the examples/ directory for production-ready code samples:

1. Authentication - OAuth 2.0 token flow
2. Campaign Management - Complete CRUD operations
3. Bulk Operations - High-performance batch updates
4. Reporting - Analytics and data export
5. Targeting Setup - Advanced targeting configuration
6. Image Upload - Media library management
7. Audience Creation - Custom audience targeting

See the Examples README for detailed documentation on running and using these examples.

Usage

Authentication

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

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

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

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

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

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

Run Tests

composer test

Generate Coverage Report

composer test-coverage

Run Static Analysis

composer analyse

Format Code

composer format

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 for complete documentation.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Mark Anthony Villaflor
• All Contributors

License

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