Merge branch 'main' into dev-improve-broken-reference-output

.github/workflows/backwards-compatibility-checks.yaml

@@ -68,15 +68,17 @@ jobs:
         continue-on-error: true
         # OwlBot PRs which are not labelled feat should not add new files or methods
         run: |
-          ~/.composer/vendor/bin/roave-backward-compatibility-check --to=origin/main --format=github-actions
+          ~/.composer/vendor/bin/roave-backward-compatibility-check \
+            --from=origin/${{ github.head_ref || github.ref_name }} \
+            --to=origin/main
       - name: "Print the action item"
         run: |
           if [[ "${{ steps.compatibility-checker.outcome }}" == 'failure' ]]; then
-            if [[ "${{ startsWith(github.event.pull_request.title, 'feat') }}" == "true" ]]; then
+            if [[ "${{ startsWith(github.event.pull_request.title, 'feat') }}" == "false" ]]; then
               echo "Action item: Change the conventional commit to use 'feat'"
               exit 1
             fi
-          elif [[ "${{ startsWith(github.event.pull_request.title, 'feat') }}" == "false" ]]; then
+          elif [[ "${{ startsWith(github.event.pull_request.title, 'feat') }}" == "true" ]]; then
             echo "Action item: No features found, do not use 'feat' for the conventional commit"
             exit 1
           fi

.github/workflows/conformance-tests-storage-emulator.yaml

@@ -16,7 +16,7 @@ jobs:
 
     services:
       emulator:
-        image: gcr.io/cloud-devrel-public-resources/storage-testbench:v0.45.0
+        image: gcr.io/cloud-devrel-public-resources/storage-testbench:v0.50.0
         ports:
           - 9000:9000
 

.github/workflows/release.yml

@@ -29,11 +29,17 @@ jobs:
             mkdir libgit2/build && cd libgit2/build
             cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local
             sudo cmake --build . --target install
-        - name: Compile splitsh
+        - name: Clone splitsh/lite
+          uses: actions/checkout@master
+          with:
+            repository: splitsh/lite
+            ref: v2.0.0
+            path: lite
+        - name: Build splitsh-lite
           run: |
-            go env -w GO111MODULE=off
-            go get github.com/splitsh/lite
-            go build -o /usr/local/bin/splitsh-lite github.com/splitsh/lite
+            cd lite
+            go build -o splitsh-lite github.com/splitsh/lite
+            mv splitsh-lite /usr/local/bin/splitsh-lite
         - name: Checkout google/cloud
           uses: actions/checkout@v4
           with:

.github/workflows/system-tests-spanner-emulator.yaml

@@ -18,7 +18,7 @@ jobs:
 
     services:
       emulator:
-        image: gcr.io/cloud-spanner-emulator/emulator:1.5.24
+        image: gcr.io/cloud-spanner-emulator/emulator:1.5.27
         ports:
           - 9010:9010
           - 9020:9020

.kokoro/docs/docker/Dockerfile

@@ -91,17 +91,15 @@ RUN php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" &&
     php -r "if (hash_file('SHA384', 'composer-setup.php') === rtrim(file_get_contents('https://composer.github.io/installer.sig'))) { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;" && \
     php composer-setup.php --filename=composer --install-dir=/usr/local/bin
 
-# Use phpDocumentor from HEAD until they create a new release
-# TODO: Remove once phpDocumentor tags a new release
+# Use phpDocumentor from HEAD (useful for testing changes before a release)
 # @see https://github.com/phpDocumentor/phpDocumentor/issues/3434
-COPY --from=phpdoc/phpdoc:3.5.3 /opt/phpdoc /opt/phpdoc
-RUN ln -s /opt/phpdoc/bin/phpdoc /usr/local/bin/phpdoc
-ENV PHPDOC_ENV=prod
+# COPY --from=phpdoc/phpdoc:3.5.3 /opt/phpdoc /opt/phpdoc
+# RUN ln -s /opt/phpdoc/bin/phpdoc /usr/local/bin/phpdoc
+# ENV PHPDOC_ENV=prod
 
-# Install phpdoc
-# TODO: uncomment once phpDocumentor creates a new release
-# RUN wget -O /usr/local/bin/phpdoc "https://github.com/phpDocumentor/phpDocumentor/releases/download/v3.3.1/phpDocumentor.phar" \
-#   && chmod +x /usr/local/bin/phpdoc
+# Install phpdoc (v3.5.3)
+RUN wget -O /usr/local/bin/phpdoc "https://github.com/phpDocumentor/phpDocumentor/releases/download/v3.5.3/phpDocumentor.phar" \
+  && chmod +x /usr/local/bin/phpdoc
 
 # Install Python3
 RUN wget https://www.python.org/ftp/python/3.9.14/Python-3.9.14.tgz \

.kokoro/docs/docker/requirements.in

@@ -1 +1,2 @@
 gcp-docuploader
+proto-plus

.kokoro/docs/docker/requirements.txt

@@ -1,8 +1,8 @@
 #
-# This file is autogenerated by pip-compile with python 3.9
-# To update, run:
+# This file is autogenerated by pip-compile with Python 3.12
+# by the following command:
 #
-#    pip-compile --generate-hashes /Users/betterbrent/Code/google-cloud-php/.kokoro/docs/docker/requirements.in
+#    pip-compile --generate-hashes requirements.in
 #
 cachetools==5.4.0 \
     --hash=sha256:3ae3b49a3d5e28a77a0be2b37dbcb89005058959cb2323858c2657c4a8cab474 \
@@ -133,6 +133,12 @@ idna==3.7 \
     --hash=sha256:028ff3aadf0609c1fd278d8ea3089299412a7a8b9bd005dd08b9f8285bcb5cfc \
     --hash=sha256:82fee1fc78add43492d3a1898bfa6d8a904cc97d8427f683ed8e798d07761aa0
     # via requests
+proto-plus==1.25.0 \
+    --hash=sha256:c91fc4a65074ade8e458e95ef8bac34d4008daa7cce4a12d6707066fca648961 \
+    --hash=sha256:fbb17f57f7bd05a68b7707e745e26528b0b3c34e378db91eef93912c54982d91
+    # via
+    #   -r requirements.in
+    #   google-api-core
 protobuf==4.25.4 \
     --hash=sha256:051e97ce9fa6067a4546e75cb14f90cf0232dcb3e3d508c448b8d0e4265b61c1 \
     --hash=sha256:0dc4a62cc4052a036ee2204d26fe4d835c62827c855c8a03f29fe6da146b380d \
@@ -149,6 +155,7 @@ protobuf==4.25.4 \
     #   gcp-docuploader
     #   google-api-core
     #   googleapis-common-protos
+    #   proto-plus
 pyasn1==0.6.0 \
     --hash=sha256:3a35ab2c4b5ef98e17dfdec8ab074046fbda76e281c5a706ccd82328cfc8f64c \
     --hash=sha256:cca4bb0f2df5504f02f6f8a775b6e416ff9b0b3b16f7ee80b5a3153d9b804473

.kokoro/docs/publish.sh

@@ -13,41 +13,44 @@ fi
 SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
 PROJECT_DIR=$(dirname $(dirname $SCRIPT_DIR))
 
+phpdoc --version
+
 # Run "composer install" if it hasn't been run yet
 if [ ! -d 'dev/vendor/' ]; then
     composer install -d $PROJECT_DIR/dev
 fi
-
+STAGING_FLAG="";
 if [ "$STAGING_BUCKET" != "" ]; then
     echo "Using staging bucket ${STAGING_BUCKET}..."
+    STAGING_FLAG="--staging-bucket $STAGING_BUCKET"
 fi
-VERBOSITY="";
-if [ "$GCLOUD_DEBUG" -eq 1 ]; then
+VERBOSITY_FLAG="";
+if [ "$GCLOUD_DEBUG" = "1" ]; then
     echo "Setting verbosity to VERBOSE...";
-    VERBOSITY=" -v";
+    VERBOSITY_FLAG=" -v";
 fi
-
 find $PROJECT_DIR/* -mindepth 1 -maxdepth 1 -name 'composer.json' -not -path '*vendor/*' -regex "$PROJECT_DIR/[A-Z].*" -exec dirname {} \; | while read DIR
 do
     COMPONENT=$(basename $DIR)
     VERSION=$(cat $DIR/VERSION)
-    if [ "$STAGING_BUCKET" != "" ]; then
-        $PROJECT_DIR/dev/google-cloud docfx \
-            --component $COMPONENT \
-            --out $DIR/out \
-            --metadata-version $VERSION \
-            --staging-bucket $STAGING_BUCKET \
-            $VERBOSITY
-    else
-        # dry run
-        $PROJECT_DIR/dev/google-cloud docfx \
-            --component $COMPONENT \
-            --out $DIR/out \
-            --metadata-version $VERSION \
-            $VERBOSITY
-    fi
+    $PROJECT_DIR/dev/google-cloud docfx \
+        --component $COMPONENT \
+        --out $DIR/out \
+        --metadata-version $VERSION \
+        --with-cache \
+        $STAGING_FLAG \
+        $VERBOSITY_FLAG
 done
 
+# Add GAX repo
+GAX_DIR=$PROJECT_DIR/dev/vendor/google/gax
+$PROJECT_DIR/dev/google-cloud docfx \
+    --path $GAX_DIR \
+    --out gax-out \
+    --metadata-version $(cat $GAX_DIR/VERSION) \
+    $STAGING_FLAG \
+    $VERBOSITY_FLAG
+
 # If this run after a release, store the released artifacts.
 if [ "$KOKORO_GITHUB_COMMIT" != "" ]; then
     # Move to the project directory
@@ -81,7 +84,7 @@ if [ "$KOKORO_GITHUB_COMMIT" != "" ]; then
 
         # Store composer.lock for SBOM generation
         mkdir "pkg/$module"
-        composer update -d "$module"
+        composer update -d "$module" --ignore-platform-req ext-grpc
         cp "$module/composer.lock" "pkg/$module/composer.lock"
     done
 fi

.repo-metadata-full.json

@@ -15,11 +15,19 @@
         "library_type": "GAPIC_AUTO",
         "api_shortname": "accesscontextmanager"
     },
+    "AdsAdManager": {
+        "language": "php",
+        "distribution_name": "googleads/ad-manager",
+        "release_level": "preview",
+        "client_documentation": "https://cloud.google.com/php/docs/reference/googleads/ad-manager/latest",
+        "library_type": "GAPIC_AUTO",
+        "api_shortname": "admanager"
+    },
     "AdsMarketingPlatformAdmin": {
         "language": "php",
-        "distribution_name": "google/ads-marketingplatform-admin",
+        "distribution_name": "googleads/marketingplatform-admin",
         "release_level": "preview",
-        "client_documentation": "https://cloud.google.com/php/docs/reference/ads-marketingplatform-admin/latest",
+        "client_documentation": "https://cloud.google.com/php/docs/reference/googleads/marketingplatform-admin/latest",
         "library_type": "GAPIC_AUTO",
         "api_shortname": "marketingplatformadmin"
     },

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=<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.
@@ -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).

AccessApproval/VERSION

@@ -1 +1 @@
-2.0.1
+2.0.2