jeffersongoncalves / laravel-google-ads

v1.0.0 2026-09-07 14:44 UTC

Requires

• php: ^8.2
• illuminate/support: ^11.0|^12.0|^13.0
• spatie/laravel-package-tools: ^1.14.0

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.21
• orchestra/testbench: ^9.0|^10.0|^11.0
• pestphp/pest: ^3.0|^4.0
• pestphp/pest-plugin-laravel: ^3.0|^4.0

MIT

• Jefferson Gonçalves

• adwords
• laravel
• Advertising
• google-ads
• google-ads-api
• gaql

Published on Packagist.org on 2026-09-07 14:44 UTC

README

Laravel Google Ads

A lightweight Google Ads API client for Laravel. It wraps GAQL search (googleAds:searchStream), campaign and budget mutate calls behind a small static client, threads your OAuth bearer token and developer token, and returns null/[] sentinels on ordinary HTTP failures instead of throwing.

Features

• search() — run a raw GAQL query, flattened from the streamed response chunks into a single list of rows
• accountInfo() — fetch the customer id and descriptive name
• campaigns() — list campaigns with id, name, status, and budget
• campaignsPerformance() — impressions, clicks, cost, and conversions per campaign over a date range
• pauseCampaign() / enableCampaign() — toggle a campaign's status
• adGroupsPerformance() — impressions, clicks, and conversions per ad group
• keywordsPerformance() — impressions, clicks, and average CPC per keyword, ranked by clicks
• updateBudget() — update a campaign budget, converting dollars to micros

Installation

composer require jeffersongoncalves/laravel-google-ads

Optionally publish the config file:

php artisan vendor:publish --tag="google-ads-config"

Configuration

Add to your .env:

GOOGLE_ADS_ACCESS_TOKEN=ya29.xxxxxxxxxxxxxxxxxxxx
GOOGLE_ADS_DEVELOPER_TOKEN=xxxxxxxxxxxxxxxxxxxxxx
GOOGLE_ADS_CUSTOMER_ID=1234567890
GOOGLE_ADS_LOGIN_CUSTOMER_ID=
GOOGLE_ADS_API_VERSION=v19
GOOGLE_ADS_TIMEOUT=8

GOOGLE_ADS_ACCESS_TOKEN is the OAuth bearer token — see the OAuth guide. GOOGLE_ADS_DEVELOPER_TOKEN identifies your application — see the developer token guide. GOOGLE_ADS_CUSTOMER_ID is the default account requests target when no id is passed explicitly. GOOGLE_ADS_LOGIN_CUSTOMER_ID is only needed when authenticating through a manager (MCC) account. GOOGLE_ADS_API_VERSION should track a currently supported version — Google sunsets old ones on a rolling schedule.

Config Options

// config/google-ads.php
return [
    'access_token' => env('GOOGLE_ADS_ACCESS_TOKEN'),
    'developer_token' => env('GOOGLE_ADS_DEVELOPER_TOKEN'),
    'customer_id' => env('GOOGLE_ADS_CUSTOMER_ID'),
    'login_customer_id' => env('GOOGLE_ADS_LOGIN_CUSTOMER_ID'),
    'version' => env('GOOGLE_ADS_API_VERSION', 'v19'),
    'timeout' => (int) env('GOOGLE_ADS_TIMEOUT', 8),
];

Usage

use JeffersonGoncalves\GoogleAds\GoogleAdsClient;

// Run any GAQL query — customer id defaults to config('google-ads.customer_id')
$rows = GoogleAdsClient::search('SELECT campaign.id, campaign.name FROM campaign');

// Account info
$account = GoogleAdsClient::accountInfo();

// Campaigns
$campaigns = GoogleAdsClient::campaigns();
$performance = GoogleAdsClient::campaignsPerformance(days: 7);

// Toggle a campaign
GoogleAdsClient::pauseCampaign('111');
GoogleAdsClient::enableCampaign('111');

// Ad groups and keywords
$adGroups = GoogleAdsClient::adGroupsPerformance(days: 30, limit: 10);
$keywords = GoogleAdsClient::keywordsPerformance(days: 30, limit: 50);

// Update a budget (amount in dollars, converted to micros)
GoogleAdsClient::updateBudget('222', 25.00);

// Target a different account than the configured default
$rows = GoogleAdsClient::campaigns(customerId: '987-654-3210');

Testing

composer test

Static Analysis

composer analyse

Code Formatting

composer format

Changelog

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

License

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