docs: add PHP snippets

.github/workflows/snippets.yaml

@@ -80,3 +80,18 @@ jobs:
       - name: Run dotnet snippets
         working-directory: ./samples/snippets/dotnet-snippets
         run: dotnet test
+  php-snippets:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.3'
+          tools: composer
+      - run: php --version
+      - name: Install dependencies
+        working-directory: ./samples/snippets/php-snippets
+        run: composer install
+      - name: Run PHP snippets
+        working-directory: ./samples/snippets/php-snippets/test
+        run: ../vendor/bin/phpunit SamplesTest.php

samples/snippets/php-snippets/composer.json

@@ -0,0 +1,10 @@
+{
+  "require": {
+    "ext-pgsql": "*",
+    "ext-pdo": "*",
+    "testcontainers/testcontainers": "^0.2.0"
+  },
+  "require-dev": {
+    "phpunit/phpunit": "^11.5"
+  }
+}

samples/snippets/php-snippets/samples/add_column.php

@@ -0,0 +1,28 @@
+<?php
+
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// [START spanner_add_column]
+function add_column(string $host, string $port, string $database): void
+{
+    $dsn = sprintf("pgsql:host=%s;port=%s;dbname=%s", $host, $port, $database);
+    $connection = new PDO($dsn);
+
+    $connection->exec("ALTER TABLE albums ADD COLUMN marketing_budget bigint");
+    print("Added marketing_budget column\n");
+
+    $connection = null;
+}
+// [END spanner_add_column]

samples/snippets/php-snippets/samples/albums_data.txt

@@ -0,0 +1,5 @@
+1	1	Total Junk
+1	2	Go, Go, Go
+2	1	Green
+2	2	Forever Hold Your Peace
+2	3	Terrified

samples/snippets/php-snippets/samples/create_connection.php

@@ -0,0 +1,35 @@
+<?php
+
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// [START spanner_create_connection]
+function create_connection(string $host, string $port, string $database): void
+{
+    // Connect to Spanner through PGAdapter using the PostgreSQL PDO driver.
+    $dsn = sprintf("pgsql:host=%s;port=%s;dbname=%s", $host, $port, $database);
+    $connection = new PDO($dsn);
+
+    // Execute a query on Spanner through PGAdapter.
+    $statement = $connection->query("select 'Hello world!' as hello");
+    $rows = $statement->fetchAll();
+
+    printf("Greeting from Cloud Spanner PostgreSQL: %s\n", $rows[0][0]);
+
+    // Cleanup resources.
+    $rows = null;
+    $statement = null;
+    $connection = null;
+}
+// [END spanner_create_connection]

samples/snippets/php-snippets/samples/create_tables.php

@@ -0,0 +1,45 @@
+<?php
+
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// [START spanner_create_database]
+function create_tables(string $host, string $port, string $database): void
+{
+    // Connect to Spanner through PGAdapter using the PostgreSQL PDO driver.
+    $dsn = sprintf("pgsql:host=%s;port=%s;dbname=%s", $host, $port, $database);
+    $connection = new PDO($dsn);
+
+    // Create two tables in one batch.
+    $connection->exec("start batch ddl");
+    $connection->exec("create table singers ("
+        ."  singer_id   bigint primary key not null,"
+        ."  first_name  character varying(1024),"
+        ."  last_name   character varying(1024),"
+        ."  singer_info bytea,"
+        ."  full_name   character varying(2048) generated "
+        ."  always as (first_name || ' ' || last_name) stored"
+        .")");
+    $connection->exec("create table albums ("
+        ."  singer_id     bigint not null,"
+        ."  album_id      bigint not null,"
+        ."  album_title   character varying(1024),"
+        ."  primary key (singer_id, album_id)"
+        .") interleave in parent singers on delete cascade");
+    $connection->exec("run batch");
+    print("Created Singers & Albums tables in database: [{$database}]\n");
+
+    $connection = null;
+}
+// [END spanner_create_database]

samples/snippets/php-snippets/samples/ddl_batch.php

@@ -0,0 +1,48 @@
+<?php
+
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// [START spanner_ddl_batch]
+function ddl_batch(string $host, string $port, string $database): void
+{
+    $dsn = sprintf("pgsql:host=%s;port=%s;dbname=%s", $host, $port, $database);
+    $connection = new PDO($dsn);
+
+    // Executing multiple DDL statements as one batch is
+    // more efficient than executing each statement
+    // individually.
+    $connection->exec("start batch ddl");
+    $connection->exec("CREATE TABLE venues ("
+        ."  venue_id    bigint not null primary key,"
+        ."  name        varchar(1024),"
+        ."  description jsonb"
+        .")");
+    $connection->exec("CREATE TABLE concerts ("
+        ."  concert_id bigint not null primary key ,"
+        ."  venue_id   bigint not null,"
+        ."  singer_id  bigint not null,"
+        ."  start_time timestamptz,"
+        ."  end_time   timestamptz,"
+        ."  constraint fk_concerts_venues foreign key"
+        ."    (venue_id) references venues (venue_id),"
+        ."  constraint fk_concerts_singers foreign key"
+        ."    (singer_id) references singers (singer_id)"
+        .")");
+    $connection->exec("run batch");
+    print("Added venues and concerts tables\n");
+
+    $connection = null;
+}
+// [END spanner_ddl_batch]

samples/snippets/php-snippets/samples/query_data.php

@@ -0,0 +1,37 @@
+<?php
+
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// [START spanner_query_data]
+function query_data(string $host, string $port, string $database): void
+{
+    $dsn = sprintf("pgsql:host=%s;port=%s;dbname=%s", $host, $port, $database);
+    $connection = new PDO($dsn);
+
+    $statement = $connection->query("SELECT singer_id, album_id, album_title "
+        ."FROM albums "
+        ."ORDER BY singer_id, album_id"
+    );
+    $rows = $statement->fetchAll();
+    foreach ($rows as $album)
+    {
+        printf("%s\t%s\t%s\n", $album["singer_id"], $album["album_id"], $album["album_title"]);
+    }
+
+    $rows = null;
+    $statement = null;
+    $connection = null;
+}
+// [END spanner_query_data]

samples/snippets/php-snippets/samples/query_data_with_new_column.php

@@ -0,0 +1,38 @@
+<?php
+
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// [START spanner_query_data_with_new_column]
+function query_data_with_new_column(string $host, string $port, string $database): void
+{
+    $dsn = sprintf("pgsql:host=%s;port=%s;dbname=%s", $host, $port, $database);
+    $connection = new PDO($dsn);
+
+    $statement = $connection->query(
+        "SELECT singer_id, album_id, marketing_budget "
+        ."FROM albums "
+        ."ORDER BY singer_id, album_id"
+    );
+    $rows = $statement->fetchAll();
+    foreach ($rows as $album)
+    {
+        printf("%s\t%s\t%s\n", $album["singer_id"], $album["album_id"], $album["marketing_budget"]);
+    }
+
+    $rows = null;
+    $statement = null;
+    $connection = null;
+}
+// [END spanner_query_data_with_new_column]

samples/snippets/php-snippets/samples/query_data_with_parameter.php

@@ -0,0 +1,38 @@
+<?php
+
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// [START spanner_query_with_parameter]
+function query_data_with_parameter(string $host, string $port, string $database): void
+{
+    $dsn = sprintf("pgsql:host=%s;port=%s;dbname=%s", $host, $port, $database);
+    $connection = new PDO($dsn);
+
+    $statement = $connection->prepare("SELECT singer_id, first_name, last_name "
+                        ."FROM singers "
+                        ."WHERE last_name = ?"
+    );
+    $statement->execute(["Garcia"]);
+    $rows = $statement->fetchAll();
+    foreach ($rows as $singer)
+    {
+        printf("%s\t%s\t%s\n", $singer["singer_id"], $singer["first_name"], $singer["last_name"]);
+    }
+
+    $rows = null;
+    $statement = null;
+    $connection = null;
+}
+// [END spanner_query_with_parameter]

samples/snippets/php-snippets/samples/sample_runner.php

@@ -0,0 +1,25 @@
+<?php
+
+require 'create_tables.php';
+
+/**
+ * @throws Exception if the number of command line arguments is not equal to 4
+ */
+function parse_arguments(): array {
+    global $argc, $argv;
+
+    if (!$argc == 4) {
+        throw new Exception(sprintf("Invalid number of arguments: %d\nExpected: 4", $argc));
+    }
+    $host = $argv[1];
+    $port = $argv[2];
+    $database = $argv[3];
+    return [$host, $port, $database];
+}
+
+try {
+    [$host, $port, $database] = parse_arguments();
+    create_tables($host, $port, $database);
+} catch (Exception $e) {
+    printf("Failed to run sample: %s\n", $e);
+}

samples/snippets/php-snippets/samples/singers_data.txt

@@ -0,0 +1,5 @@
+1	Marc	Richards
+2	Catalina	Smith
+3	Alice	Trentor
+4	Lea	Martin
+5	David	Lomond

samples/snippets/php-snippets/samples/statement_timeout.php

@@ -0,0 +1,50 @@
+<?php
+
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// [START spanner_statement_timeout]
+function query_with_timeout(string $host, string $port, string $database): void
+{
+    $dsn = sprintf("pgsql:host=%s;port=%s;dbname=%s", $host, $port, $database);
+    $connection = new PDO($dsn);
+
+    // Set the statement timeout that should be used for all statements
+    // on this connection to 5 seconds.
+    // Supported time units are 's' (seconds), 'ms' (milliseconds),
+    // 'us' (microseconds), and 'ns' (nanoseconds).
+    $connection->exec("set statement_timeout='5s'");
+
+    try {
+        $statement = $connection->query("SELECT singer_id, album_id, album_title "
+            . "FROM albums "
+            . "WHERE album_title in ("
+            . "  SELECT first_name "
+            . "  FROM singers "
+            . "  WHERE last_name LIKE '%a%'"
+            . "     OR last_name LIKE '%m%'"
+            . ")");
+        $rows = $statement->fetchAll();
+        foreach ($rows as $album) {
+            printf("%s\t%s\t%s\n", $album["singer_id"], $album["album_id"], $album["album_title"]);
+        }
+    } catch (Exception $exception) {
+        printf("Error occurred during query execution: %s", $exception->getMessage());
+    }
+
+    $rows = null;
+    $statement = null;
+    $connection = null;
+}
+// [END spanner_statement_timeout]