UX: Add Crate\PDO\PDOCrateDB as a better export symbol

CHANGES.rst

@@ -10,6 +10,12 @@ Unreleased
 
 - Added deprecation notice about PHP7.
 
+- Documentation: Added two standalone example programs about inserts
+
+- Added ``Crate\PDO\PDOCrateDB`` as a better export symbol, because importing
+  ``Crate\PDO\PDO`` without alias into the main namespace collides with
+  PHP's native ``PDO`` class.
+
 .. _CrateDB bulk operations: https://crate.io/docs/crate/reference/en/latest/interfaces/http.html#bulk-operations
 
 2022/11/29 2.1.4

docs/connect.rst

@@ -78,13 +78,13 @@ You can get a PDO connection like this:
 
 .. code-block:: php
 
-   use Crate\PDO\PDO as PDO;
+   use Crate\PDO\PDOCrateDB;
 
    $dsn = '<DATA_SOURCE_NAME>';
    $user = 'crate';
    $password = null;
    $options = null;
-   $connection = new PDO($dsn, $user, $password, $options);
+   $connection = new PDOCrateDB($dsn, $user, $password, $options);
 
 .. NOTE::
 

examples/insert_basic.php

@@ -0,0 +1,43 @@
+<?php
+/*
+ * Basic example demonstrating how to connect to CrateDB using PHP PDO.
+ *
+ * Prerequisites:
+ *
+ *  docker run --rm -it --publish=4200:4200 crate
+ *
+ * Synopsis:
+ *
+ *  php examples/insert_basic.php
+ */
+
+declare(strict_types=1);
+
+include("./vendor/autoload.php");
+
+error_reporting(E_ALL ^ E_DEPRECATED);
+
+// Connect to CrateDB.
+use Crate\PDO\PDOCrateDB;
+
+$connection = new PDOCrateDB("crate:localhost:4200", "crate");
+
+// Create database table.
+$connection->exec("DROP TABLE IF EXISTS test_table;");
+$connection->exec("CREATE TABLE test_table (id INTEGER, name STRING, int_type INTEGER);");
+
+// Run insert operation.
+$statement = $connection->prepare('INSERT INTO test_table (id, name, int_type) VALUES (?, ?, ?)');
+$statement->execute([5, 'foo', 1]);
+$statement->execute([6, 'bar', 2]);
+
+// Evaluate response.
+print("Total count: {$statement->rowCount()}\n");
+$response = $statement->fetchAll(PDO::FETCH_NUM);
+print_r($response);
+
+// Disconnect from database.
+// https://www.php.net/manual/en/pdo.connections.php
+// https://stackoverflow.com/questions/18277233/pdo-closing-connection
+$statement = null;
+$connection = null;

examples/insert_bulk.php

@@ -0,0 +1,47 @@
+<?php
+/*
+ * Example demonstrating how to use CrateDB's bulk operations interface for
+ * inserting large amounts of data efficiently, using PHP PDO.
+ *
+ * Prerequisites:
+ *
+ *  docker run --rm -it --publish=4200:4200 crate
+ *
+ * Synopsis:
+ *
+ *  php examples/insert_bulk.php
+ */
+
+declare(strict_types=1);
+
+include("./vendor/autoload.php");
+
+error_reporting(E_ALL ^ E_DEPRECATED);
+
+// Connect to CrateDB.
+use Crate\PDO\PDOCrateDB;
+
+$connection = new PDOCrateDB("crate:localhost:4200", "crate");
+
+// Create database table.
+$connection->exec("DROP TABLE IF EXISTS test_table;");
+$connection->exec("CREATE TABLE test_table (id INTEGER, name STRING, int_type INTEGER);");
+
+// Run insert operation.
+$parameters = [[5, 'foo', 1], [6, 'bar', 2], [7, 'foo', 3], [8, 'bar', 4]];
+$statement = $connection->prepare(
+    'INSERT INTO test_table (id, name, int_type) VALUES (?, ?, ?)',
+    array("bulkMode" => true));
+$statement->execute($parameters);
+
+// Evaluate response.
+// MUST use `PDO::FETCH_NUM` for returning bulk operation responses.
+print("Total count: {$statement->rowCount()}\n");
+$response = $statement->fetchAll(PDO::FETCH_NUM);
+print_r($response);
+
+// Disconnect from database.
+// https://www.php.net/manual/en/pdo.connections.php
+// https://stackoverflow.com/questions/18277233/pdo-closing-connection
+$statement = null;
+$connection = null;

src/Crate/PDO/PDOCrateDB.php

@@ -0,0 +1,30 @@
+<?php
+/**
+ * Licensed to CRATE Technology GmbH("Crate") under one or more contributor
+ * license agreements.  See the NOTICE file distributed with this work for
+ * additional information regarding copyright ownership.  Crate licenses
+ * this file to you 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.
+ *
+ * However, if you have executed another commercial license agreement
+ * with Crate these terms will supersede the license and you may use the
+ * software solely pursuant to the terms of the relevant commercial agreement.
+ */
+
+declare(strict_types=1);
+
+namespace Crate\PDO;
+
+class PDOCrateDB extends PDO implements PDOInterface
+{
+    use PDOImplementation;
+}

test/CrateTest/CratePDOTest.php

@@ -0,0 +1,49 @@
+<?php
+/**
+ * Licensed to CRATE Technology GmbH("Crate") under one or more contributor
+ * license agreements.  See the NOTICE file distributed with this work for
+ * additional information regarding copyright ownership.  Crate licenses
+ * this file to you 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.
+ *
+ * However, if you have executed another commercial license agreement
+ * with Crate these terms will supersede the license and you may use the
+ * software solely pursuant to the terms of the relevant commercial agreement.
+ */
+
+namespace CrateTest;
+
+use Crate\PDO\PDOCrateDB;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Tests for {@see \Crate\PDO\PDOCrateDB}
+ *
+ * @coversDefaultClass \Crate\PDO\PDOCrateDB
+ * @covers ::<!public>
+ *
+ * @group unit
+ */
+class CratePDOTest extends TestCase
+{
+    /**
+     * @covers ::__construct
+     */
+    public function testInstantiation()
+    {
+        $pdo = new PDOCrateDB('crate:localhost:1234', null, null, []);
+
+        $this->assertInstanceOf(PDOCrateDB::class, $pdo);
+        $this->assertInstanceOf('PDO', $pdo);
+    }
+
+}