googleads / google-ads-php
Google Ads API client for PHP
Installs: 4 123 268
Dependents: 11
Suggesters: 0
Security: 0
Stars: 291
Watchers: 33
Forks: 260
Open Issues: 14
Requires
- php: >=8.1
- google/gax: ^1.19.1
- google/protobuf: ^3.21.5 || ^4.26
- grpc/grpc: ^1.36.0
- monolog/monolog: ^1.26 || ^2.0 || ^3.0
Requires (Dev)
- ext-bcmath: *
- ext-grpc: *
- ext-protobuf: *
- composer/composer: ^2.0
- phpunit/phpunit: ^9.5
- react/http: ^1.2.0
- squizlabs/php_codesniffer: ^3.5
- ulrichsg/getopt-php: ^3.4
Suggests
- ext-grpc: To be able to use the gRPC transport, use the C implementation of gRPC
- ext-protobuf: For better performance, use the C implementation of Protobuf
- google/protobuf: In case the C implementation of Protobuf is not suitable, use the PHP one
- grpc/grpc: In case the C implementation of gRPC is not suitable, use the PHP one to enable other transports
- react/http: To run the AuthenticateInWebApplication.php example
- dev-main
- v24.0.0
- v23.1.0
- v23.0.1
- v23.0.0
- v22.1.1
- v22.1.0
- v22.0.0
- v21.1.0
- v21.0.1
- v21.0.0
- v20.1.0
- v20.0.0
- v19.2.0
- v19.1.0
- v19.0.0
- v18.0.0
- v17.1.0
- v17.0.0
- v16.0.0
- v15.1.0
- v15.0.0
- v14.0.0
- v13.0.0
- v12.1.0
- v12.0.0
- v11.0.0
- v10.1.0
- v10.0.0
- v9.0.0
- v8.1.0
- v8.0.0
- v7.0.0
- v6.1.0
- v6.0.0
- v5.0.0
- v4.0.0
- v3.2.0
- v3.1.0
- v3.0.0
- v2.2.0
- v2.1.0
- v2.0.0
- v1.4.1
- v1.4.0
- v1.3.0
- v1.2.0
- v1.1.0
- v1.0.0
- v0.7.0
- v0.6.0
- v0.5.0
- v0.4.0
- 0.3.0
- v0.2.0
- 0.1.0
- dev-clean-up-gapic-v2
- dev-clean-up-gapic-v2-2
- dev-fix-laravel-v17
- dev-legacy-v24.0.0
- dev-legacy-v23.1.0
- dev-patch-22.1.0
- dev-legacy-v23.0.0
- dev-legacy-v22.1.0
- dev-remove-v12
- dev-fix-getchangedetails
- dev-update-fieldmasks-github
- dev-update-fieldmasks
- dev-fix-monologcalls-googleadscalllogger
- dev-PierrickVoulet-patch-32
- dev-PierrickVoulet-patch-31
- dev-PierrickVoulet-patch-30
- dev-PierrickVoulet-patch-29
- dev-PierrickVoulet-patch-28
- dev-PierrickVoulet-patch-27
- dev-PierrickVoulet-patch-26-1
- dev-PierrickVoulet-patch-26
- dev-release-v7-2cd2dac95ffbf1550c4d
- dev-PierrickVoulet-patch-22
- dev-release-v6_1-9dfd35d17aaeadb3ccf8
- dev-release-v6_1-b7c53d37cfcfa22368ab
- dev-PierrickVoulet-patch-25
- dev-PierrickVoulet-fix-ad-violation-comment
- dev-PierrickVoulet-patch-24
- dev-fix-getadgroupbidmodifier
- dev-upstream/PierrickVoulet-patch-22
- dev-update-php-badge
- dev-PierrickVoulet-patch-23
- dev-sunset-v7_2-travis
- dev-release-v6_1-6000fdeacb1917c14433
- dev-fix-getfieldvalue-fieldmasks
- dev-PierrickVoulet-patch-21
- dev-PierrickVoulet-patch-20
- dev-release-v6_0-38d7baa325d92bab1d6d
- dev-change-param-names-shopping
- dev-support-logging-stream
- dev-PierrickVoulet-patch-19
- dev-PierrickVoulet-patch-18
- dev-PierrickVoulet-patch-17
- dev-fix-updatesitelinks
- dev-PierrickVoulet-patch-16
- dev-release-v6_0-d184adf1859ae5e71eff
- dev-PierrickVoulet-patch-15
- dev-PierrickVoulet-patch-14
- dev-add-fieldmasks-presence-test
- dev-PierrickVoulet-patch-13
- dev-release-v5_0-12b103c351ef5530c53f
- dev-PierrickVoulet-patch-12
- dev-PierrickVoulet-patch-11
- dev-fix-addgeotarget-typo
- dev-PierrickVoulet-patch-10
- dev-PierrickVoulet-patch-8
- dev-PierrickVoulet-patch-9
- dev-release-v4_0-b2abe2b2fa4b514a7d94
- dev-update-readme-for-better-visibility
- dev-update-readme-for-visibility
- dev-add-displayuploadad
- dev-revert-googleadsexceptiontest
- dev-increase-coverage-statusmetadataextractor
- dev-increase-coverage-3
- dev-increase-coverage-serviceclientfactorytrait
- dev-increase-coverage-2
- dev-increase-coverage-1
- dev-add-sitelinks-using-feeds
- dev-PierrickVoulet-patch-7
- dev-PierrickVoulet-patch-6
- dev-PierrickVoulet-patch-5
- dev-release-v3_2-0e1f01e5149d9b707307
- dev-add-support-resouce-name-request
- dev-update-get-account-budgets
- dev-rename-acceptservicelinks
- dev-PierrickVoulet-patch-4
- dev-add-acceptservicelink
- dev-add-upload-call-conversion
- dev-update-getaccounthierarchy-1
- dev-PierrickVoulet-patch-3
- dev-add-targeting-removing-extensions-ex
- dev-PierrickVoulet-patch-2
- dev-update-comments-stringattributeexamples
- dev-remove-page-size-getgeotargetconstants
- dev-rename-getgeotargetconstant
- dev-updateandremovefeeditem
- dev-fix-fieldmasks
- dev-update-eta
- dev-add-addhotelcalloutextension
- dev-PierrickVoulet-patch-1
- dev-add-responsivesearchad-example
- dev-release-v3_1-0ea9f55bdbc1a9951247
- dev-PierrickVoulet-add_app_campaign-image_asset
- dev-PierrickVoulet-add_app_campaign-image_resource_names-1
- dev-PierrickVoulet-add_app_campaign-image_resource_names
- dev-update-contributing.md
- dev-PierrickVoulet_validate-text-ad_add-comment-1
- dev-PierrickVoulet_validate-text-ad_add-comment
- dev-create-github-templates
- dev-fix-style-psr12
- dev-add-addlistingscope-2
- dev-add-updatecampaigncriterionbidmodifier
- dev-add-addlistingscope
- dev-add-addprices
- dev-fix-getartifactmetadata
- dev-release-v2_2-a20147f798a1ccda3538
- dev-add-getsitelinks
- dev-update-getaccounthierarchy
- dev-addaudiences
- dev-adddemographictargetingcriteria
- dev-fix-phpdoc-etas
- dev-min-php-version
- dev-add-updateflightfeeditemattributevalue
- dev-release-v2_2-3cab26ad25f7669cdf90
- dev-add-addflightsfeed-ex
- dev-add-getaccounthierarchy
- dev-fix-typehint-getkeyword
- dev-logger-use-fopen-instead
- dev-add-addGoogleMyBusinessLocationExtensions
- dev-fix-listaccessiblecustomers-example
- dev-support-mutate-operations-in-errors
- dev-release-v2_1-ff02e280dc6ba2d87c01
- dev-add-serviceaccount
- dev-add-experiments-examples
- dev-add-codecov
- dev-test-travis2
- dev-make-customerid-int
- dev-fix_filter_var_php73
- dev-revert-fix-logmessageformattertest
- dev-fix-phpunit-cover
- dev-test-travis
- dev-add-travis
- dev-test-githubhook
- dev-fix-phpcs-problems
- dev-add-responsivedisplayad
- dev-add-eta-handlepolicyviolation
- dev-add-handlepolicyviolation
- dev-fix-googleadsmetadatatrait
- dev-release-v2-4f786170048c9154205a
- dev-prevent-risky-tests
- dev-add-instantiate-classes-test
- dev-small-fix-getaccountinfo
- dev-temp-fix-logmessageformattertest
- dev-update-changelog-v1.4.1
- dev-update-readme-devsite
- dev-specify-metadata-size
- dev-logging-default
- dev-fix-phpcs-ruleset
- dev-fix-phpcs-issues
- dev-proxy-support
- dev-refactor-mjs-example
- dev-update-changelog-v1.4.0
- dev-gen-src-adjust-timeout
- dev-refactor-mutatejobservice-example
- dev-add-completecampaigns-usingmutatejobservice
- dev-remove_unnecessary_dependencies
- dev-release-V1_2-803d12cc5be885b2c4ce
- dev-release-V1_2-a4c81da9d57f7d4b2db2
- dev-release-V1_2-d3ec18e46ec5cc39750b
- dev-release-v1_2-81fce7266cf132a19d9c
- dev-update-handlepartialfailure
- dev-docker-container
- dev-update-gitattributes
- dev-create-migration-examples
- dev-move-partial-failure-example
- dev-type-hint-with-login-customer-id
- dev-release-v1_1-542f8fa0a9645565530c
- dev-handle-partial-failures
- dev-hide-googleadsfailure
- dev-ignore-vscode-config
- dev-upgrade-phpunit-7
- dev-updating-composerjson
- dev-fix-adwords-googleads
- dev-update-readme-v1
- dev-release-V1_0-149baa4222fdd504ac03
- dev-release-v0_7-2bb0a4fb907b4624f750
- dev-add-gethoteladsperformance-example
- dev-add-listaccessible-customers
- dev-generatekeywordideas-ex
- dev-create-customer-ex
- dev-update-readme-grpc
- dev-dismiss-recommendation-ex
- dev-release-v0_6-66e389139035e5390f57
- dev-release-v0_5-5631a06d4c91b8157e60
- dev-release-v0_4-37b78dd1b2a5c5ef827f
- dev-release-v0_3-e139d2fc3b06d9026a67
- dev-release-stage
This package is auto-updated.
Last update: 2024-09-27 05:00:20 UTC
README
This project hosts the PHP client library for the Google Ads API. It adheres to the PHP sunset schedule and updates the composer.json file four to five months after the minimum required PHP version reaches its end-of-life. Based on the existing supported PHP versions, the update occurs about once a year.
IMPORTANT The Google Ads API client library for PHP has been updated to require PHP version 8 as the minimum version, as announced in #880. This means that the final version of the library that supports PHP 7 is v19.2.0, which supports Google Ads API v12 to v14.
Google Ads API v14 is scheduled to be sunset by the end of May 2024. Therefore, PHP 7 users have about 11 months to migrate to PHP 8 in order to continue using the library without disruption.
Features
- Distributed via Composer and Packagist.
- Easy management of credentials.
- Easy creation of Google Ads API service clients.
Requirements
- Both 32-bit and 64-bit PHP systems are supported but we highly recommend to use 64-bit if you can. This is because many fields of the Google Ads API are typed as 64-bit integers and casting their values to
int
instead offloat
from 32-bit systems can lead to issues. The largest integer value supported in 32-bit PHP systems is usually 2147483647, see the predefined constant PHP_INT_MAX for more details. - This library depends on Composer. If you don't
have it installed on your computer yet, follow the installation guide for
Linux/Unix/OS
X or
installation guide for
Windows. For
the rest of this guide, we're assuming that you're using Linux/Unix/OS X and
have Composer installed
globally, thus, your
installed Composer is available on the command line as
composer
. - System requirements and dependencies can be found in
composer.json of this library.
- PHP: You can find the required minimum PHP version in
"php"
under therequire
key ofcomposer.json
. We usually set it to the minimum PHP version for which the PHP development team still provide security fixes. Whenever such a version is sunset, we'll update the composer file accordingly. Currently, the update frequency is around once a year based on the official schedule. Visit this page for introduction to PHP. - gRPC: To install the gRPC PHP extension, make sure to meet any additional requirements listed in the project's documentation. You can learn more about how gRPC is used by this library by reading our Transport guide. It usually take minutes to install using
PECL
:- Install the extension using the command
sudo pecl install grpc
. - Add a line
extension=grpc.so
to thephp.ini
file. - Run
php -i | grep grpc
in a terminal: it is well installed and configured if it returns something
- Install the extension using the command
- Protobuf: To install the Protobuf PHP extension, make sure to meet any additional requirements listed in the project's documentation. If you encounter any error during the installation, you can skip this step and the PHP implementation will be used instead. You can learn more about how Protobuf is used by this library by reading our Protobuf implementations guide. It usually take minutes to install using
PECL
:- Install the extension using the command
sudo pecl install protobuf
. - Add a line
extension=protobuf.so
to thephp.ini
file. - Run
php -i | grep protobuf
in a terminal: it is well installed and configured if it returns something
- Install the extension using the command
- PHP: You can find the required minimum PHP version in
- You need a developer token to connect to the Google Ads API.
- One version of the library typically supports multiple versions of the Google Ads API. You can check the CHANGELOG.md file to identify what versions of the library added or removed the support for a specific version of the Google Ads API. For example, the version
V7
of the Google Ads API was added in the versionv9.0.0
of the library as described here.
Getting started
Running code examples
Follow the below steps if you want to try our code examples.
-
Clone this project in the directory of your choice via:
git clone https://github.com/googleads/google-ads-php.git
-
Change into the
google-ads-php
directory.cd google-ads-php
You'll see some files and subdirectories:
composer.json
: the composer file, which holds the requirements of this library.src
: source code of the library.tests
: tests of the library code.examples
: many examples that demonstrate how to use the library to execute common use cases via the Google Ads API.metadata
: some metadata files used internally by the source code. They're automatically generated files, so you shouldn't modify them.
-
Run
composer install
at the command prompt. This will install all dependencies needed for using the library and running examples. -
Set up your OAuth2 credentials.
The Google Ads API uses OAuth2 as the authentication mechanism. Choose the appropriate option below based on your use case, and read and follow the instructions that the example prints to the console.
-
Copy the sample
google_ads_php.ini
to your home directory. This library determines the home directory of your computer by usingEnvironmentalVariables::getHome()
. -
Follow the instructions at https://developers.google.com/google-ads/api/docs/oauth/cloud-project to create an OAuth2 client ID and secret for the installed application OAuth2 flow.
-
Run the GenerateUserCredentials example, which will prompt you for your OAuth2 client ID and secret.
-
Copy the output from the last step of the example into the
google_ads_php.ini
file in your home directory. Don't forget to fill in your developer token too.
-
-
Run the GetCampaigns example to test if your credentials are valid. You also need to pass your Google Ads account's customer ID without dashes as a command-line parameter:
php examples/BasicOperations/GetCampaigns.php --customerId <YOUR_CUSTOMER_ID>
NOTE: Code examples are meant to be run from command prompt, not via the web browsers.
-
Explore other examples.
The examples directory contains several useful examples. Most of the examples require parameters. You can see what are required by running code examples with
--help
as a command-line parameter.Note: You will find comments with the formats
[START...]
and[END...]
in the source code of these examples. These are only used for technical purposes, you can completely disregard them.
Installing the library as your project's dependency
- Change into the root directory of your project.
- Run
composer require googleads/google-ads-php
at the command prompt. This will install this library and all its dependencies in thevendor/
directory of your project's root directory. - Set up your OAuth2 credentials like described in the previous section.
- You can now use this library by importing its classes like shown in the code examples.
Basic usage
Instantiate a client
To issue requests via the Google Ads API, you first need to create a GoogleAdsClient.
For more information on how to configure a client when instantiating it, see the configuration guide.
Get a service client
Once you have an instance of GoogleAdsClient
, you can obtain a service client
for a particular service using one of the get...ServiceClient()
methods.
Client configuration
See the Configuration guide.
Transport
There are different types of transport that can be used. See the Transport guide for more information.
Protobuf
Protobuf is used regardless of the transport used to request the Google Ads API.
See the Protobuf guide for more information.
Running in a Docker container
See the Running in a Docker container guide.
Logging
See the Logging guide.
Proxy configuration
See the Proxy guide.
Performance
See the Performance guide.