{"id":28495201,"url":"https://github.com/net-tools/google-api","last_synced_at":"2025-07-18T10:09:54.989Z","repository":{"id":56953934,"uuid":"83820368","full_name":"net-tools/google-api","owner":"net-tools","description":"PHP Interface to Google APIs","archived":false,"fork":false,"pushed_at":"2024-04-29T19:01:23.000Z","size":338,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-18T02:41:50.602Z","etag":null,"topics":["cloud-print","contacts","google-api-client","php"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/net-tools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-03-03T16:48:28.000Z","updated_at":"2024-04-29T16:15:45.000Z","dependencies_parsed_at":"2024-04-29T17:45:04.868Z","dependency_job_id":null,"html_url":"https://github.com/net-tools/google-api","commit_stats":{"total_commits":156,"total_committers":3,"mean_commits":52.0,"dds":"0.39743589743589747","last_synced_commit":"99e6ae4141990d1f959b2f7992d82a0bc1da734f"},"previous_names":[],"tags_count":134,"template":false,"template_full_name":null,"purl":"pkg:github/net-tools/google-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/net-tools%2Fgoogle-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/net-tools%2Fgoogle-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/net-tools%2Fgoogle-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/net-tools%2Fgoogle-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/net-tools","download_url":"https://codeload.github.com/net-tools/google-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/net-tools%2Fgoogle-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265702102,"owners_count":23813769,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloud-print","contacts","google-api-client","php"],"created_at":"2025-06-08T11:08:21.680Z","updated_at":"2025-07-18T10:09:54.979Z","avatar_url":"https://github.com/net-tools.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# net-tools/google-api\n\n## PHP Interface to Google APIs\n\nThis packages contains :\n\n- some service helpers to main Google products, such as Calendar, Drive, or Gmail, \n\n\n\n\n## Setup instructions ##\n\nTo install net-tools/google-api package, just require it through composer : require net-tools/google-api:^1.0.0.\n\nIn order to use the classes contained in this library, **please read CAREFULLY this document**, as **you have to setup your Google dev account first**. Basic knowledge about Google APIs is also required.\n\n\n\n\n## Overview of Google app credentials and authorization process\n\n### Note\n\nThe Google API can be a bit confusing at first, especially the initial setup for application credentials (**to do only once**) and authorization process (**to do for each API request**). \n\nI strongly advise you to read any reference about those topics from Google Developper reference (for example, https://developers.google.com/identity/protocols/OAuth2WebServer or https://developers.google.com/google-apps/calendar/auth for a Calendar service auth) before reading further topics here.\n\n\n\n### Identifying your application (app credentials)\n\nMaking requests to Google APIs through PHP requires your application to be \"identified\" (so that Google may apply quotas). This way, users granting your application access to their personnal Google data can clearly identify your application before allowing access.\n\nBefore running any of the samples here or coding your application, you **MUST** setup your Google dev account (see below 'Setting up your Google dev account'). This is mandatory. Then, when dealing with the API, you will identify your application with credentials obtained during the Google dev account setup.\n\n\n\n### Getting access to user data (authorization process)\n\nMaking requests to Google APIs through PHP requires your application to be allowed to create/read/update/delete data in the user's account. That's called the authorization process. Depending on the grants (called scopes in the API) you ask for, your application may be only allowed to read data, but not update stuff.\n\nFrom your application, the user is redirected to Google login page and asked to allow access to it's personnal data for a service (Calendar, Gmail, etc.). If he accepts, he is redirected back to your application, which gets an access token, allowing free access for 1 hour (after that delay, the user should identify again). You may store the token in database or session to reuse it during that delay. Refresh tokens also exist, with no 1 hour limit (off-topic here).\n\n\n\n\n## Setting up your Google dev account \n\nThe setup is done by registering a new application in Google Developper Console :\n\n1. open the link to Google Dev Console : https://console.developers.google.com/\n1. on the left, click on `Credentials`\n1. create a new project and type a name (a project may contain several products, so be general, for example type your name or company) ; confirm\n1. on the left, click on `Library`, then choose the API to enable. On the API page resume, click on `Enable`\n1. repeat previous step for any other required API\n1. on the left, click on `Credentials`\n1. don't click on `Create credentials` button yet, as we have to setup the OAuth consent screen first ; open the `OAuth consent screen` tab\n1. type in a product name so that the users can identify your application (they are going to give your application access to their personnal data, so this is very important to clearly identify your app), and hit `Save`\n1. now, you can click on `Create credentials`\n1. select `Web application` ; enter a name for your web app ; enter the `Authorized redirect URIs` ; this is the URL that Google will redirect your users to when they have passed the Google authorization process. If you are running one of the samples here, type the full path to the sample file, including your domain.\n1. click on `Create`\n\n\nAt this point, take note of the credentials displayed on screen :\n\n- your client ID,\n- your client secret.\n\n\n\n\n## Running the samples\n\nIf you have not setup your Google dev account yet, please do it now (see chapter above).\n\nTo run the samples, modify the lines of `Credentials.php` by typing the client ID and secret available after the Google dev account setup on the developper console. Depending on which sample you are running, more config data may be required, and this will be mentionned in the sample file top comments.\n\nSome steps must be taken for some samples to run successfuly (such as creating test events, contacts, emails), please refer to the according Readme file in the samples subdirectory.\n\n\n\n\n## Using Google APIs\n\nHere are some links to Google APIs reference ; you should read them before reading further here, since this package is only a frontend to Google APIs. You still have to manage with Google APIs :\n\n- Calendar : https://developers.google.com/google-apps/calendar/v3/reference/\n- Drive : https://developers.google.com/drive/v3/reference/\n- Gmail : https://developers.google.com/gmail/api/v1/reference/\n- Contacts : https://developers.google.com/people/api/rest\n\nFor each API, don't forget to read the `Guides` section on the top navigation bar.\n\n\n\n\n## Using this packages classes\n\nAll calls to Google API require at least one object, called the *Client* ; many Google API also require a second object, called the *Service*. You may see the *Client* as the link or interface to the API ('link' is to understand as the communication medium), whereas the *Service* contains business methods (creating, deleting things).\n\n\n### Creating a Client object\n\nCreating the *Client* object is rather straightforward :\n\n```php\n$gclient = new Nettools\\GoogleAPI\\Clients\\Serverside_InlineCredentials(\n        CLIENT_ID, \n        CLIENT_SECRET, \n        array(\\Google\\Service\\Calendar::CALENDAR_READONLY)\n    );\n``` \n\nWe create an object of `Serverside_InlineCredentials` class, identifying the application with credentials from developper console, and requesting a readonly access to the user Calendar data. It creates a `\\Google\\Client` object behind the scenes (underlying object, the object we create is only a frontend). Some API mandatory parameters are set with default values (for example, *redirectUri* points to the script URL).\n\nIf you prefer identifying with Json credentials and not strings in code, use `Serverside_JsonCredentials`. If you are using a service account, use `ServiceAccount`. *Serverside* or *ServiceAccount* prefix in class names tell us the kind of application we are dealing with (please refer to Google API for further explanations about server-side or service accounts).\n\nIf you have an access token previously obtained, you can pass it to the constructor : \n\n```php\n$gclient = new Nettools\\GoogleAPI\\Clients\\Serverside_InlineCredentials(\n        CLIENT_ID, \n        CLIENT_SECRET, \n        array(\\Google\\Service\\Calendar::CALENDAR_READONLY),\n        array(\n            'accessToken' =\u003e $token\n        )\n    );\n``` \n\nor call later `setAccessToken()` through the `client` accessor property to the underlying `\\Google\\Client` object :\n\n```php\n$gclient-\u003eclient-\u003esetAccessToken($token);\n```\n\n\n### Creating a Service object\n\nNow that we have a *Client* object, we can use it to get a *Service* object for a particular API :\n\n```php\n$cal = $gclient-\u003egetService('Calendar');\n$response = $cal-\u003eevents-\u003elistEvents('primary');\n```\n\nThe `getService()` method is inherited from `Clients\\GoogleClient` ; it creates a *Service* object making it possible to issue API calls to Google services. The kind of object created depends on several parameters, explained in the following chapter.\n\n\n\n### Service wrappers, services API implemented here and Google_Service\n\nDepending on whether our library has a service wrapper for the target service or not (such as Gmail or Calendar), whether our library implements a service API or not, `getService()` returns either a service wrapper (inheriting from `ServiceWrappers\\ServiceWrapper`) or a service object from our library (inheriting from `Services\\Service`) or a `\\Google\\Service` object directly created from Google API library.\n\nThe rule is that if the service asked is defined in the Google API library, and we have a service wrapper for it in our library, the service wrapper will be used (Gmail, Calendar, PeopleService, Drive). If no service wrapper available, the `\\Google\\Service` object is created from the Google API library. If the service asked is not implemented in the Google API library, we try to create the service object from our library. \n\nThe service wrappers of our library provide some useful functionnalities and act as frontends (facade pattern) to the underlying Google APIs. This is clearly visible for the Gmail service wrapper (it implements methods to decode body parts and attachments).\n\nIf you are asking for a service for which we have a `ServiceWrappers\\ServiceWrapper` object, the object returned by `getService()` is an instance of `ServiceWrappers\\ServiceWrapper`. However, our wrappers implement a forward mechanism for properties and method calls : method calls for methods not defined in a wrapper are forwarded to the underlying `\\Google\\Service` object. Same thing for the properties. You may write : \n\n```php\n$response = $cal-\u003eevents-\u003elistEvents('primary');\n// or explicitely invoke the underlying service object : \n$response = $cal-\u003eservice-\u003eevents-\u003elistEvents('primary');\n```\n\n\n\n## Handling errors\n\nIf the error comes from the Google API, a \\Google\\Exception or \\Google\\Service\\Exception will be thrown. \n\nYou have to intercept the exception with a try/catch block. The `message` property of the \\Google\\Exception object contains the error as a Json string. For example, here is the exception message for a request with no valid credentials :\n\n```json\n\n{\n \"error\": {\n  \"errors\": [\n   {\n    \"domain\": \"usageLimits\",\n    \"reason\": \"dailyLimitExceededUnreg\",\n    \"message\": \"Daily Limit for Unauthenticated Use Exceeded. Continued use requires signup.\",\n    \"extendedHelp\": \"https://code.google.com/apis/console\"\n   }\n  ],\n  \"code\": 403,\n  \"message\": \"Daily Limit for Unauthenticated Use Exceeded. Continued use requires signup.\"\n }\n}\n```\n\nYou may extract the message and error code :\n\n```php\ntry\n{\n   ...\n}\ncatch( Google\\Service\\Exception $e )\n{\n    $json = json_decode($e-\u003egetMessage());\n    if ( $json )\n        echo \"Error code $json-\u003eerror-\u003ecode with message $json-\u003eerror-\u003emessage\";\n}\n```\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnet-tools%2Fgoogle-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnet-tools%2Fgoogle-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnet-tools%2Fgoogle-api/lists"}