diff --git a/AUTHENTICATION.md b/AUTHENTICATION.md index 4dc6081b1b9..4c018a09256 100644 --- a/AUTHENTICATION.md +++ b/AUTHENTICATION.md @@ -3,21 +3,15 @@ The recommended way to authenticate to the Google Cloud PHP library is to use [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials), which discovers your credentials automatically, based on the environment where your code is running. -To review all of your authentication options, see Project and Credential lookup. +To review all of your authentication options see [Credential Lookup](#credential-lookup). -For more information about authentication at Google, see [the authentication guide](https://cloud.google.com/docs/authentication). +For more information about authentication at Google, see [the authentication guide](https://cloud.google.com/docs/authentication). Specific instructions and environment variables for each individual service are linked from the README documents listed below for each service. -## Project and Credential Lookup +## Credential Lookup -The Google Cloud PHP library provides several mechanisms to configure your system without -providing **Project ID** and **Service Account Credentials** directly in code. - -**Project ID** is discovered in the following order: - -1. Specify project ID in code -2. Discover project ID in environment variables -3. Discover GCE project ID +The Google Cloud PHP library provides several mechanisms to configure your system without providing +**Service Account Credentials** directly in code. **Credentials** are discovered in the following order: @@ -28,27 +22,24 @@ providing **Project ID** and **Service Account Credentials** directly in code. ### Google Cloud Platform environments -While running on Google Cloud Platform environments such as Google Compute Engine, Google App Engine and -Google Kubernetes Engine, no extra work is needed. The **Project ID** and **Credentials** and are -discovered automatically from the attached service account. Code should be written as if already authenticated. +While running on Google Cloud Platform environments such as Google Compute Engine, Google App Engine +and Google Kubernetes Engine, no extra work is needed. The **Credentials** and are discovered +automatically from the attached service account. Code should be written as if already authenticated. For more information, see [Set up ADC for Google Cloud services](https://cloud.google.com/docs/authentication/provide-credentials-adc#attached-sa). ### Environment Variables -**NOTE**: This library uses [`getenv`](https://www.php.net/manual/en/function.getenv.php), so if your environemnt -variables are set in PHP, they must use [`putenv`](https://www.php.net/manual/en/function.putenv.php), +**NOTE**: This library uses [`getenv`](https://www.php.net/manual/en/function.getenv.php), so if +your environemnt variables are set in PHP, they must use +[`putenv`](https://www.php.net/manual/en/function.putenv.php), ```php putenv("GOOGLE_APPLICATION_CREDENTIALS=" . __DIR__ . '/your-credentials-file.json'); ``` -The **Project ID** and **Credentials JSON** can be placed in environment variables instead of declaring them directly in code. - -Here are the environment variables that Google Cloud PHP checks for project ID: - -1. `GOOGLE_CLOUD_PROJECT` -2. `GCLOUD_PROJECT` (deprecated) +The **Credentials JSON** can be placed in environment variables instead of +declaring them directly in code. Here are the environment variables that Google Cloud PHP checks for credentials: @@ -63,6 +54,25 @@ Note: Service account keys are a security risk if not managed correctly. You sho [choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) whenever possible. +### Project ID detection + +Some libraries support setting up the project ID via the `GOOGLE_CLOUD_PROJECT` environment variable. +```php +putenv("GOOGLE_CLOUD_PROJECT="); +``` +The libraries that support this environment variable are: +- Bigtable +- PubSub +- Storage +- Spanner +- BigQuery +- Datastore +- Firestore +- Debugger +- Logging +- Trace +- Translate + ### Client Authentication Each Google Cloud PHP client may be authenticated in code when creating a client library instance. @@ -85,55 +95,33 @@ $video = new VideoIntelligenceServiceClient([ ]); ``` -However, some clients use the `keyFile` or `keyFilePath` option: - -```php -require 'vendor/autoload.php'; - -use Google\Cloud\Storage\StorageClient; - -// Authenticating with keyfile data. -$storage = new StorageClient([ - 'keyFile' => json_decode(file_get_contents('/path/to/keyfile.json'), true) -]); - -// Authenticating with a keyfile path. -$storage = new StorageClient([ - 'keyFilePath' => '/path/to/keyfile.json' -]); - -// Providing the Google Cloud project ID. -$storage = new StorageClient([ - 'projectId' => 'myProject' -]); -``` - -Check the [client documentation][php-ref-docs] for the client library you're using. - -[php-ref-docs]: https://cloud.google.com/php/docs/reference - ### Local ADC file -This option allows for an easy way to authenticate in a local environment during development. -If credentials are not provided in code or in environment variables, then your user credentials can be discovered -from your local ADC file. +This option allows for an easy way to authenticate in a local environment during development. If +credentials are not provided in code or in environment variables, then your user credentials can be +discovered from your local ADC file. To set up a local ADC file: 1. [Download, install, and initialize the Cloud SDK](https://cloud.google.com/sdk) 2. Create your local ADC file: - + ```sh gcloud auth application-default login ``` 3. Write code as if already authenticated. -**NOTE:** Because this method relies on your user credentials, it is _not_ recommended for running in production. +**NOTE:** Because this method relies on your user credentials, it is _not_ recommended for running +in production. For more information about setting up authentication for a local development environment, see [Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev). ## Troubleshooting -If you're having trouble authenticating open a [Github Issue](https://github.com/googleapis/google-cloud-php/issues/new?title=Authentication+question) to get help. Also consider searching or asking [questions](http://stackoverflow.com/questions/tagged/google-cloud-platform+php) on [StackOverflow](http://stackoverflow.com). +If you're having trouble authenticating open a +[Github Issue](https://github.com/googleapis/google-cloud-php/issues/new?title=Authentication+question) +to get help. Also consider searching or asking +[questions](http://stackoverflow.com/questions/tagged/google-cloud-platform+php) on +[StackOverflow](http://stackoverflow.com). diff --git a/README.md b/README.md index 4761521f719..09402859dc2 100644 --- a/README.md +++ b/README.md @@ -11,46 +11,115 @@ PHP Version | Status View the [list of supported APIs and Services](https://cloud.google.com/php/docs/reference). -If you need support for other Google APIs, please check out the [Google APIs Client Library for PHP](https://github.com/google/google-api-php-client). +If you need support for other Google APIs, please check out the +[Google APIs Client Library for PHP](https://github.com/google/google-api-php-client). -## Quick Start - -We recommend installing individual component packages. A list of available packages can be found on [Packagist](https://packagist.org/search/?q=google%2Fcloud-). +We recommend installing individual component packages. A list of available packages can be found on +[Packagist](https://packagist.org/search/?q=google%2Fcloud-). For example: - ```sh $ composer require google/cloud-storage $ composer require google/cloud-bigquery $ composer require google/cloud-datastore ``` -You can then include the autoloader and create your client: +## Quickstart + +In this guide we'll focus on how to configure your client for local development using the Google +Cloud CLI (`gcloud`). + +### For local development: +* Install the Google Cloud CLI. +* Authenticate with `gcloud` to generate the credentials file. +* Instantiate a client. + +### Installing the Google Cloud CLI +In order to generate our needed credentials file we need to authenticate to gcloud first. +Installation is handled differently depending on your platform. Here is a link to help you setup +the Google Cloud CLI: + +https://cloud.google.com/sdk/docs/install + +### Authenticate via the `gcloud` command +Once the Google Cloud CLI tools are installed it is required that we authenticate via the `gcloud`: +```shell +$ gcloud init +$ gcloud auth application-default login +``` + +This will create a local file in your system that the authentication library for our client will +read in order to make requests to the apis with those credentials. This file is located in different +place depending on your system. + +Windows: +``` +%APPDATA%\gcloud\application_default_credentials.json +``` + +Linux and MacOS: +``` +$HOME/.config/gcloud/application_default_credentials.json +``` + +To read more about Authentication, see [AUTHENTICATION.md](AUTHENTICATION.md) + +### Installing a client +Install the Google Translate client library with composer +```sh +composer install google/cloud-translate +``` +**Note**: For this example, we are using the Google Translate client library. Check the +[the complete list of packages](https://cloud.google.com/php/docs/reference/) to find your required +library. + +### Instantiating the client +Now that we've authenticated and installed the client library, we can instantiate a client which will +detect the JSON file created by the gcloud CLI and use it to authenticate your requests: ```php -require 'vendor/autoload.php'; +require_once 'vendor/autoload.php'; -use Google\Cloud\Storage\StorageClient; +use Google\Cloud\Translate\V3\Client\TranslationServiceClient; +use Google\Cloud\Translate\V3\TranslateTextRequest; -$storage = new StorageClient(); +// Instantiating the client gathers the credentials from the `application_default_credentials.json` +$client = new TranslationServiceClient([]); -$bucket = $storage->bucket('my_bucket'); +$request = new TranslateTextRequest(); +$request->setParent('projects/'); +$request->setTargetLanguageCode('en-US'); +$request->setContents(['こんにちは']); -// Upload a file to the bucket. -$bucket->upload( - fopen('/data/file.txt', 'r') -); +// The request will contain the authentication token based on the default credentials file +$response = $client->translateText($request); + +var_dump($response->getTranslations()[0]); +// { +// ["translatedText"]=> +// string(5) "Hello" +// ["detectedLanguageCode"]=> +// string(2) "ja" +// } -// Download and store an object from the bucket locally. -$object = $bucket->object('file_backup.txt'); -$object->downloadToFile('/data/file_backup.txt'); ``` ### Authentication -Authentication is handled by the client library automatically. You just need to provide the authentication details when creating a client. Generally, authentication is accomplished using a Service Account. For more information on obtaining Service Account credentials, see our [Authentication Guide](https://cloud.google.com/docs/authentication/production#manually). +#### Note +This quickstart is built with local development in mind. The steps for deploying your project are +different depending on the environment you use. Here we provide some basic instruction in how to get +started with deployment of your project: + + * For applications running elsewhere, authentication is usually accomplished using a Service + Account. + +For more information on obtaining Service Account credentials see our +[Authentication Guide](https://cloud.google.com/docs/authentication/production#manually). Set the +`GOOGLE_APPLICATION_CREDENTIALS` environment variable pointing to your credentials file. -Once you've obtained your credentials file, it may be used to create an authenticated client. +#### Note: +Some clients accept the `keyFilePath` and `keyFile` configuration options pointing to the credentials file: ```php require 'vendor/autoload.php'; @@ -67,6 +136,21 @@ $cloud = new StorageClient([ 'keyFile' => json_decode(file_get_contents('/path/to/keyfile.json'), true) ]); ``` +A list of clients that accept these parameters are: +- [Bigtable](https://github.com/googleapis/google-cloud-php-bigtable) +- [Spanner](https://github.com/googleapis/google-cloud-php-spanner) +- [Firestore](https://github.com/googleapis/google-cloud-php-firestore) +- [Datastore](https://github.com/googleapis/google-cloud-php-datastore) +- [Pubsub](https://github.com/googleapis/google-cloud-php-pubsub) +- [Debugger](https://github.com/googleapis/google-cloud-php-debugger) +- [Logging](https://github.com/googleapis/google-cloud-php-logging) +- [Translate](https://github.com/googleapis/google-cloud-php-translate) +- [Bigquery](https://github.com/googleapis/google-cloud-php-bigquery) +- [Storage](https://github.com/googleapis/google-cloud-php-storage) + +We recommend to visit the Check the [client documentation][php-ref-docs] for the client library you're using for more in depth information. + +[php-ref-docs]: https://cloud.google.com/php/docs/reference If you do not wish to embed your authentication information in your application code, you may also make use of [Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials).