Skip to content

Commit

Permalink
Update the README.md and AUTHENTICATION.md to add a quickstart section
Browse files Browse the repository at this point in the history 
Update to the AUTHENTICATION.md

Add a description for the var_dump

Change the output documentation to match the expected output from var_dump

Fix used method for the response

Update the code example

Wrap markdown to 100 columns

Add a note referring to the installation of the translation library

Move the new documentation for a quickstart to the main README file

Removed reduntant example from the AUTHENTICATION.md file and update the README.md file

Update the README and AUTHENTICATION

Update the READM.md file

Update README.md
  • Loading branch information
@Hectorhammett
Hectorhammett committed Nov 15, 2024
1 parent fd0f8aa commit dc14928
Show file tree
Hide file tree
Showing 2 changed files with 143 additions and 125 deletions.
146 changes: 40 additions & 106 deletions AUTHENTICATION.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,75 +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.

## Quickstart

Here is a quick an opinionated quickstart guide that serves as a mean to get started as quick as possible. There are different ways to authenticate
a client that we will go over this guide, but we wanted to offer a quick way to get started. We will go over the steps of what needs to be done in
order to authenticate a client first and then we will explain said steps in detail for a quickstart.

### Steps:
* 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
```

### Instantiating the client
Once we have the `application_default_credentials.json` that we created on the previous step now we can instantiate a client which internally using the Google Auth library
will take that file and use it to authenticate your requests:
```php
use Google\Cloud\Translate\V3\Client\TranslationServiceClient;
use Google\Cloud\Translate\V3\TranslateTextRequest;

// Instantiating the client gathers the credentials from the `application_default_credentials.json`
$client = new TranslationServiceClient();

$request = new TranslateTextRequest();
$request->setParent('<YOUR_PROJECT_ID>');
$request->setTargetLanguageCode('en-US');
$request->setContents('こんにちは');

// The request will contain the authentication token based on the default credentials file
$response = $client->translateText($request);
var_dump($response);
```

This quickstart guide is meant to be used as a quick and easy way to start development and get started on how you can authenticate your requests. There are diferent ways to authenticate your
requests which are explained in this document.
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).
Specific instructions and environment variables for each individual service are linked from the README documents listed below for each service.

## Credential Lookup

The Google Cloud PHP library provides several mechanisms to configure your system without
providing **Service Account Credentials** directly in code.
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:

Expand All @@ -82,27 +22,24 @@ providing **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:

Expand All @@ -117,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=<YOUR_PROJECT_ID>");
```
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.
Expand All @@ -139,38 +95,11 @@ $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:

Expand All @@ -183,11 +112,16 @@ 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).
122 changes: 103 additions & 19 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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/<YOUR_PROJECT_ID>');
$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';
Expand All @@ -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).

Expand Down

0 comments on commit dc14928

Please sign in to comment.