feat(storage): upgrade all samples and add new ones (GoogleCloudPlatform#1421)

Author: jdpedrie

storage/README.md

@@ -16,38 +16,80 @@ This simple command-line application demonstrates how to invoke
 
 * See [LICENSE](../../LICENSE)
 
-## Build and Run
-1.  **Enable APIs** - [Enable the Storage API](https://console.cloud.google.com/flows/enableapi?apiid=storage_api)
-    and create a new project or select an existing project.
-2.  **Download The Credentials** - Click "Go to credentials" after enabling the APIs. Click "New Credentials"
-    and select "Service Account Key". Create a new service account, use the JSON key type, and
-    select "Create". Once downloaded, set the environment variable `GOOGLE_APPLICATION_CREDENTIALS`
-    to the path of the JSON key that was downloaded.
-3.  **Clone the repo** and cd into this directory
-
-    ```sh
-    $ git clone https://github.com/GoogleCloudPlatform/php-docs-samples
-    $ cd php-docs-samples/storage
-    ```
-4.  **Install dependencies** via [Composer](http://getcomposer.org/doc/00-intro.md).
+### Authentication
+
+Authentication is typically done through [Application Default Credentials][adc]
+which means you do not have to change the code to authenticate as long as
+your environment has credentials. You have a few options for setting up
+authentication:
+
+1. When running locally, use the [Google Cloud SDK][google-cloud-sdk]
+
+        gcloud auth application-default login
+
+1. When running on App Engine or Compute Engine, credentials are already
+   set-up. However, you may need to configure your Compute Engine instance
+   with [additional scopes][additional_scopes].
+
+1. You can create a [Service Account key file][service_account_key_file]. This file can be used to
+   authenticate to Google Cloud Platform services from any environment. To use
+   the file, set the ``GOOGLE_APPLICATION_CREDENTIALS`` environment variable to
+   the path to the key file, for example:
+
+        export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service_account.json
+
+[adc]: https://cloud.google.com/docs/authentication#getting_credentials_for_server-centric_flow
+[additional_scopes]: https://cloud.google.com/compute/docs/authentication#using
+[service_account_key_file]: https://developers.google.com/identity/protocols/OAuth2ServiceAccount#creatinganaccount
+
+## Install Dependencies
+
+1. [Enable the Cloud Storage API](https://console.cloud.google.com/flows/enableapi?apiid=storage.googleapis.com).
+
+1. **Install dependencies** via [Composer](http://getcomposer.org/doc/00-intro.md).
     Run `php composer.phar install` (if composer is installed locally) or `composer install`
     (if composer is installed globally).
-5.  Run `php storage.php` to see a list of commands:
-
-    ```sh
-    bucket-lock                      Manage Cloud Storage retention policies and holds
-    object-acl                       Manage the ACL for Cloud Storage objects
-    objects                          Manage Cloud Storage objects
-    requester-pays                   Manage Cloud Storage requester pays buckets and objects
-    uniform-bucket-level-access      Manage Cloud Storage uniform bucket-level access buckets
-    get-object-v2-signed-url         Generate a v2 signed URL for downloading an object.
-    get-object-v4-signed-url         Generate a v4 signed URL for downloading an object.
-    get-object-v4-upload-signed-url  Generate a v4 signed URL for uploading an object.
-    hmac-sa-manage                   Manage HMAC Service Account keys.
-    hmac-sa-list                     List HMAC Service Account keys.
-    hmac-sa-create                   Create an HMAC Service Account key.
-    ```
-6. Run `php storage.php COMMAND --help` to print information about the usage of each command.
+
+1. Create a service account at the
+[Service account section in the Cloud Console](https://console.cloud.google.com/iam-admin/serviceaccounts/)
+
+1. Download the json key file of the service account.
+
+1. Set `GOOGLE_APPLICATION_CREDENTIALS` environment variable pointing to that file.
+
+## Samples
+
+To run the Storage Samples, run any of the files in `src/` on the CLI:
+
+```
+$ php src/create_bucket.php
+
+Usage: create_bucket.php $bucketName
+
+  @param string $projectId The Project ID
+  @param string $bucketName The Storage bucket name
+```
+
+## Troubleshooting
+
+If you get the following error, set the environment variable `GCLOUD_PROJECT` to your project ID:
+
+```
+[Google\Cloud\Core\Exception\GoogleException]
+No project ID was provided, and we were unable to detect a default project ID.
+```
+
+## The client library
+
+This sample uses the [Google Cloud Client Library for PHP][google-cloud-php].
+You can read the documentation for more details on API usage and use GitHub
+to [browse the source][google-cloud-php-source] and  [report issues][google-cloud-php-issues].
+
+[google-cloud-php]: https://googlecloudplatform.github.io/google-cloud-php
+[google-cloud-php-source]: https://github.com/GoogleCloudPlatform/google-cloud-php
+[google-cloud-php-issues]: https://github.com/GoogleCloudPlatform/google-cloud-php/issues
+[google-cloud-sdk]: https://cloud.google.com/sdk/
+
 
 ## Contributing changes
 

storage/composer.json

@@ -1,60 +1,7 @@
 {
     "require": {
         "google/cloud-storage": "^1.20.1",
-        "paragonie/random_compat": "^9.0.0",
-        "symfony/console": " ^5.0"
-    },
-    "autoload": {
-        "files": [
-            "src/add_bucket_conditional_iam_binding.php",
-            "src/add_bucket_iam_member.php",
-            "src/add_object_acl.php",
-            "src/copy_object.php",
-            "src/create_hmac_key.php",
-            "src/delete_object.php",
-            "src/delete_object_acl.php",
-            "src/delete_hmac_key.php",
-            "src/disable_bucket_lifecycle_management.php",
-            "src/disable_uniform_bucket_level_access.php",
-            "src/disable_default_event_based_hold.php",
-            "src/disable_requester_pays.php",
-            "src/deactivate_hmac_key.php",
-            "src/download_file_requester_pays.php",
-            "src/download_object.php",
-            "src/enable_bucket_lifecycle_management.php",
-            "src/enable_uniform_bucket_level_access.php",
-            "src/enable_default_event_based_hold.php",
-            "src/enable_requester_pays.php",
-            "src/activate_hmac_key.php",
-            "src/generate_v4_post_policy.php",
-            "src/get_uniform_bucket_level_access.php",
-            "src/get_object_acl.php",
-            "src/get_object_acl_for_entity.php",
-            "src/get_object_v2_signed_url.php",
-            "src/get_object_v4_signed_url.php",
-            "src/upload_object_v4_signed_url.php",
-            "src/get_requester_pays_status.php",
-            "src/get_retention_policy.php",
-            "src/get_default_event_based_hold.php",
-            "src/get_hmac_key.php",
-            "src/list_objects.php",
-            "src/list_objects_with_prefix.php",
-            "src/list_hmac_keys.php",
-            "src/lock_retention_policy.php",
-            "src/make_public.php",
-            "src/move_object.php",
-            "src/object_metadata.php",
-            "src/release_event_based_hold.php",
-            "src/release_temporary_hold.php",
-            "src/remove_bucket_iam_member.php",
-            "src/remove_bucket_conditional_iam_binding.php",
-            "src/remove_retention_policy.php",
-            "src/set_event_based_hold.php",
-            "src/set_retention_policy.php",
-            "src/set_temporary_hold.php",
-            "src/upload_object.php",
-            "src/view_bucket_iam_members.php"
-        ]
+        "paragonie/random_compat": "^9.0.0"
     },
     "require-dev": {
         "guzzlehttp/guzzle": "^7.0"

storage/src/activate_hmac_key.php

@@ -29,12 +29,14 @@
 /**
  * Activate an HMAC key.
  *
+ * @param string $projectId The ID of your Google Cloud Platform project.
  * @param string $accessId Access ID for an inactive HMAC key.
- * @param string $projectId Google Cloud Project ID.
- *
  */
-function activate_hmac_key($accessId, $projectId)
+function activate_hmac_key($projectId, $accessId)
 {
+    // $projectId = 'my-project-id';
+    // $accessId = 'GOOG0234230X00';
+
     $storage = new StorageClient();
     // By default hmacKey will use the projectId used by StorageClient().
     $hmacKey = $storage->hmacKey($accessId, $projectId);
@@ -45,3 +47,7 @@ function activate_hmac_key($accessId, $projectId)
     printf('HMAC key Metadata: %s' . PHP_EOL, print_r($hmacKey->info(), true));
 }
 # [END storage_activate_hmac_key]
+
+// The following 2 lines are only needed to run the samples
+require_once __DIR__ . '/../../testing/sample_helpers.php';
+\Google\Cloud\Samples\execute_sample(__FILE__, __NAMESPACE__, $argv);

storage/src/add_bucket_acl.php

@@ -29,20 +29,20 @@
 /**
  * Add an entity and role to a bucket's ACL.
  *
- * @param string $bucketName the name of your Cloud Storage bucket.
- * @param string $entity The entity to update access controls for.
- * @param string $role The permissions to add for the specified entity. May
- *        be one of 'OWNER', 'READER', or 'WRITER'.
- * @param array $options
- *
- * @return void
+ * @param string $bucketName The name of your Cloud Storage bucket.
+ * @param string $entity The entity for which to update access controls.
+ * @param string $role The permissions to add for the specified entity.
  */
-function add_bucket_acl($bucketName, $entity, $role, $options = [])
+function add_bucket_acl($bucketName, $entity, $role)
 {
+    // $bucketName = 'my-bucket';
+    // $entity = '[email protected]';
+    // $role = 'OWNER';
+
     $storage = new StorageClient();
     $bucket = $storage->bucket($bucketName);
     $acl = $bucket->acl();
-    $acl->add($entity, $role, $options);
+    $acl->add($entity, $role);
     printf('Added %s (%s) to gs://%s ACL' . PHP_EOL, $entity, $role, $bucketName);
 }
 # [END storage_add_bucket_owner]

storage/src/add_bucket_conditional_iam_binding.php

@@ -29,20 +29,25 @@
 /**
  * Adds a conditional IAM binding to a bucket's IAM policy.
  *
- * @param string $bucketName the name of your Cloud Storage bucket.
- * @param string $role the role that will be given to members in this binding.
- * @param string[] $members the member(s) that is associated to this binding.
- * @param string $title condition's title
- * @param string $description condition's description
- * @param string $expression the condition specified in CEL expression language.
+ * @param string $bucketName The name of your Cloud Storage bucket.
+ * @param string $role The role that will be given to members in this binding.
+ * @param string[] $members The member(s) associated with this binding.
+ * @param string $title The title of the condition.
+ * @param string $description The description of the condition.
+ * @param string $expression The condition specified in CEL expression language.
  *
  * To see how to express a condition in CEL, visit:
  * @see https://cloud.google.com/storage/docs/access-control/iam#conditions.
- *
- * @return void
  */
-function add_bucket_conditional_iam_binding($bucketName, $role, $members, $title, $description, $expression)
+function add_bucket_conditional_iam_binding($bucketName, $role, array $members, $title, $description, $expression)
 {
+    // $bucketName = 'my-bucket';
+    // $role = 'roles/storage.objectViewer';
+    // $members = ['group:[email protected]'];
+    // $title = 'Title';
+    // $description = 'Condition Description';
+    // $expression = 'resource.name.startsWith("projects/_/buckets/bucket-name/objects/prefix-a-")';
+
     $storage = new StorageClient();
     $bucket = $storage->bucket($bucketName);
 
@@ -72,3 +77,7 @@ function add_bucket_conditional_iam_binding($bucketName, $role, $members, $title
     printf('    Expression: %s' . PHP_EOL, $expression);
 }
 # [END storage_add_bucket_conditional_iam_binding]
+
+// The following 2 lines are only needed to run the samples
+require_once __DIR__ . '/../../testing/sample_helpers.php';
+\Google\Cloud\Samples\execute_sample(__FILE__, __NAMESPACE__, $argv);

storage/src/add_bucket_default_acl.php

@@ -29,20 +29,20 @@
 /**
  * Add an entity and role to a bucket's default ACL.
  *
- * @param string $bucketName the name of your Cloud Storage bucket.
- * @param string $entity The entity to update access controls for.
- * @param string $role The permissions to add for the specified entity. May
- *        be one of 'OWNER', 'READER', or 'WRITER'.
- * @param array $options
- *
- * @return void
+ * @param string $bucketName The name of your Cloud Storage bucket.
+ * @param string $entity The entity for which to update access controls.
+ * @param string $role The permissions to add for the specified entity.
  */
-function add_bucket_default_acl($bucketName, $entity, $role, $options = [])
+function add_bucket_default_acl($bucketName, $entity, $role)
 {
+    // $bucketName = 'my-bucket';
+    // $entity = '[email protected]';
+    // $role = 'OWNER';
+
     $storage = new StorageClient();
     $bucket = $storage->bucket($bucketName);
     $acl = $bucket->defaultAcl();
-    $acl->add($entity, $role, $options);
+    $acl->add($entity, $role);
     printf('Added %s (%s) to gs://%s default ACL' . PHP_EOL, $entity, $role, $bucketName);
 }
 # [END storage_add_bucket_default_owner]

storage/src/add_bucket_iam_member.php

@@ -29,15 +29,16 @@
 /**
  * Adds a new member / role IAM pair to a given Cloud Storage bucket.
  *
- * @param string $bucketName the name of your Cloud Storage bucket.
- * @param string $role the role you want to add a given member to.
- * @param string[] $members the member(s) you want to give the new role for the Cloud
- * Storage bucket.
- *
- * @return void
+ * @param string $bucketName The name of your Cloud Storage bucket.
+ * @param string $role The role to which the given member should be added.
+ * @param string[] $members The member(s) to be added to the role.
  */
-function add_bucket_iam_member($bucketName, $role, $members)
+function add_bucket_iam_member($bucketName, $role, array $members)
 {
+    // $bucketName = 'my-bucket';
+    // $role = 'roles/storage.objectViewer';
+    // $members = ['group:[email protected]'];
+
     $storage = new StorageClient();
     $bucket = $storage->bucket($bucketName);
 
@@ -57,3 +58,7 @@ function add_bucket_iam_member($bucketName, $role, $members)
     }
 }
 # [END storage_add_bucket_iam_member]
+
+// The following 2 lines are only needed to run the samples
+require_once __DIR__ . '/../../testing/sample_helpers.php';
+\Google\Cloud\Samples\execute_sample(__FILE__, __NAMESPACE__, $argv);

storage/src/add_bucket_label.php

@@ -29,12 +29,16 @@
 /**
  * Adds or updates a bucket label.
  *
- * @param string $bucketName the name of your Cloud Storage bucket.
- * @param string $labelName the name of the label to add.
- * @param string $labelValue the value of the label to add.
+ * @param string $bucketName The name of your Cloud Storage bucket.
+ * @param string $labelName The name of the label to add.
+ * @param string $labelValue The value of the label to add.
  */
 function add_bucket_label($bucketName, $labelName, $labelValue)
 {
+    // $bucketName = 'my-bucket';
+    // $labelName = 'label-key-to-add';
+    // $labelValue = 'label-value-to-add';
+
     $storage = new StorageClient();
     $bucket = $storage->bucket($bucketName);
     $newLabels = [$labelName => $labelValue];

storage/src/add_object_acl.php

@@ -29,22 +29,27 @@
 /**
  * Add an entity and role to an object's ACL.
  *
- * @param string $bucketName the name of your Cloud Storage bucket.
- * @param string $objectName the name of your Cloud Storage object.
- * @param string $entity The entity to update access controls for.
- * @param string $role The permissions to add for the specified entity. May
- *        be one of 'OWNER', 'READER', or 'WRITER'.
- * @param array $options
- *
- * @return void
+ * @param string $bucketName The name of your Cloud Storage bucket.
+ * @param string $objectName The name of your Cloud Storage object.
+ * @param string $entity The entity for which to update access controls.
+ * @param string $role The permissions to add for the specified entity.
  */
-function add_object_acl($bucketName, $objectName, $entity, $role, $options = [])
+function add_object_acl($bucketName, $objectName, $entity, $role)
 {
+    // $bucketName = 'my-bucket';
+    // $objectName = 'my-object';
+    // $entity = '[email protected]';
+    // $role = 'OWNER';
+
     $storage = new StorageClient();
     $bucket = $storage->bucket($bucketName);
     $object = $bucket->object($objectName);
     $acl = $object->acl();
-    $acl->add($entity, $role, $options);
+    $acl->add($entity, $role);
     printf('Added %s (%s) to gs://%s/%s ACL' . PHP_EOL, $entity, $role, $bucketName, $objectName);
 }
 # [END storage_add_file_owner]
+
+// The following 2 lines are only needed to run the samples
+require_once __DIR__ . '/../../testing/sample_helpers.php';
+\Google\Cloud\Samples\execute_sample(__FILE__, __NAMESPACE__, $argv);