Add Crate\PDO\PDOCrateDB as a better export symbol

Reason: Importing `Crate\PDO\PDO` without alias into the main namespace
collides with PHP's native `PDO` class.

Author: amotl

CHANGES.rst

@@ -10,6 +10,10 @@ Unreleased
 
 - 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

@@ -18,8 +18,9 @@
 error_reporting(E_ALL ^ E_DEPRECATED);
 
 // Connect to CrateDB.
-use Crate\PDO\PDO as CratePDO;
-$connection = new CratePDO("crate:localhost:4200", "crate");
+use Crate\PDO\PDOCrateDB;
+
+$connection = new PDOCrateDB("crate:localhost:4200", "crate");
 
 // Create database table.
 $connection->exec("DROP TABLE IF EXISTS test_table;");

examples/insert_bulk.php

@@ -19,8 +19,9 @@
 error_reporting(E_ALL ^ E_DEPRECATED);
 
 // Connect to CrateDB.
-use Crate\PDO\PDO as CratePDO;
-$connection = new CratePDO("crate:localhost:4200", "crate");
+use Crate\PDO\PDOCrateDB;
+
+$connection = new PDOCrateDB("crate:localhost:4200", "crate");
 
 // Create database table.
 $connection->exec("DROP TABLE IF EXISTS test_table;");

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);
+    }
+
+}