From a4f89a001b307fb84575b08bb7bc1e9811777c44 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Wed, 15 Oct 2025 23:24:53 +0200 Subject: [PATCH 1/2] Connect/PHP: Add AMPHP and PDO_PGSQL --- docs/connect/php.md | 105 ++++++++++++++++++++++++++++++++++---------- 1 file changed, 82 insertions(+), 23 deletions(-) diff --git a/docs/connect/php.md b/docs/connect/php.md index f86b9597..88512019 100644 --- a/docs/connect/php.md +++ b/docs/connect/php.md @@ -3,45 +3,99 @@ # PHP :::{div} sd-text-muted -Available PHP extensions for CrateDB and CrateDB Cloud. +Available PHP drivers and adapters for CrateDB and CrateDB Cloud. ::: -## PDO +## AMPHP PostgreSQL driver + +The [AMPHP PostgreSQL driver], `amphp/postgres`, is an asynchronous +PostgreSQL client based on Amp. + +:::{rubric} Synopsis +::: +```php +prepare("SELECT * FROM sys.summits ORDER BY height DESC LIMIT 3"); + $result = $statement->execute(); + foreach ($result as $row) { + print_r($row); + } +})); +?> +``` +:::{rubric} Example +::: +- [Connect to CrateDB and CrateDB Cloud using AMPHP/PostgreSQL]   [![PHP AMPHP](https://github.com/crate/cratedb-examples/actions/workflows/lang-php-amphp.yml/badge.svg)](https://github.com/crate/cratedb-examples/actions/workflows/lang-php-amphp.yml) + +## PostgreSQL PDO driver + +[PDO_PGSQL] is a PHP-native driver that implements the PHP Data Objects (PDO) +interface to enable access from PHP to PostgreSQL databases. + +:::{rubric} Synopsis +::: +```php +query("SELECT * FROM sys.summits ORDER BY height DESC LIMIT 3"); +print_r($cursor->fetchAll(PDO::FETCH_ASSOC)); +?> +``` + +:::{rubric} Example +::: +- [Use the PDO_PGSQL driver with CrateDB]   [![PHP PDO](https://github.com/crate/cratedb-examples/actions/workflows/lang-php-pdo.yml/badge.svg)](https://github.com/crate/cratedb-examples/actions/workflows/lang-php-pdo.yml) + +## CrateDB PDO driver The PHP Data Objects (PDO) is a standard PHP extension that defines a common interface for accessing databases in PHP. +The {ref}`crate-pdo:index` implements this specification, wrapping access to +CrateDB's HTTP interface. -Example implementation will look like this: - +:::{rubric} Synopsis +::: ```php .cratedb.net:4200', - 'admin', - '' -); - -$stm = $pdo->query('SELECT name FROM sys.cluster'); -$name = $stm->fetch(); -print $name[0]; +$dsn = ''; +$user = 'crate'; +$password = null; +$options = null; +$connection = new PDOCrateDB($dsn, $user, $password, $options); +$stm = $connection->query("SELECT * FROM sys.summits ORDER BY height DESC LIMIT 3"); +$result = $stm->fetch(); +print_r($result); ?> ``` -See full documentation {ref}`here `. +[![Tests](https://github.com/crate/crate-pdo/actions/workflows/tests.yml/badge.svg)](https://github.com/crate/crate-pdo/actions/workflows/tests.yml) -## DBAL +## CrateDB DBAL adapter DBAL is a PHP database abstraction layer that comes with database schema introspection, schema management, and PDO support. +The {ref}`crate-dbal:index` implements this specification, wrapping access to +CrateDB's HTTP interface. The adapter currently does not support recent +versions of the Doctrine ORM. -Example implementation will look like this: - +:::{rubric} Synopsis +::: ```php query($sql)->fetch(); - -print $name['name']; +$sql = "SELECT * FROM sys.summits ORDER BY height DESC LIMIT 3"; +$result = $connection->query($sql)->fetch(); +print_r($result); ?> ``` -See full documentation {ref}`here `. +[![Tests](https://github.com/crate/crate-dbal/actions/workflows/tests.yml/badge.svg)](https://github.com/crate/crate-dbal/actions/workflows/tests.yml) + + +[AMPHP PostgreSQL driver]: https://github.com/amphp/postgres +[Connect to CrateDB and CrateDB Cloud using AMPHP/PostgreSQL]: https://github.com/crate/cratedb-examples/tree/main/by-language/php-amphp +[PDO_PGSQL]: https://www.php.net/manual/en/ref.pdo-pgsql.php +[Use the PDO_PGSQL driver with CrateDB]: https://github.com/crate/cratedb-examples/tree/main/by-language/php-pdo From 5e3ba990f077f58f3607af51e81892d11e6be67b Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Thu, 23 Oct 2025 02:26:00 +0200 Subject: [PATCH 2/2] Connect/PHP: Reorganize section. Each item gets a dedicated page. --- docs/connect/drivers.md | 4 +- docs/connect/index.md | 2 +- docs/connect/php.md | 126 --------------------------------- docs/connect/php/amphp.md | 42 +++++++++++ docs/connect/php/crate-dbal.md | 46 ++++++++++++ docs/connect/php/crate-pdo.md | 34 +++++++++ docs/connect/php/index.md | 15 ++++ docs/connect/php/pdo-pgsql.md | 30 ++++++++ 8 files changed, 170 insertions(+), 129 deletions(-) delete mode 100644 docs/connect/php.md create mode 100644 docs/connect/php/amphp.md create mode 100644 docs/connect/php/crate-dbal.md create mode 100644 docs/connect/php/crate-pdo.md create mode 100644 docs/connect/php/index.md create mode 100644 docs/connect/php/pdo-pgsql.md diff --git a/docs/connect/drivers.md b/docs/connect/drivers.md index d21cfbbc..ea83e613 100644 --- a/docs/connect/drivers.md +++ b/docs/connect/drivers.md @@ -279,7 +279,7 @@ For connecting to CrateDB from PHP. ``` ```{sd-item} [![](https://img.shields.io/github/v/tag/crate/crate-pdo?label=latest)](https://github.com/crate/crate-pdo) -[![](https://img.shields.io/badge/example-snippet-darkcyan)](#php) +[![](https://img.shields.io/badge/example-snippet-darkcyan)](#connect-php) ``` ::: @@ -294,7 +294,7 @@ For connecting to CrateDB from PHP, using DBAL and Doctrine. ``` ```{sd-item} [![](https://img.shields.io/github/v/tag/crate/crate-dbal?label=latest)](https://github.com/crate/crate-dbal) -[![](https://img.shields.io/badge/example-snippet-darkcyan)](#php) +[![](https://img.shields.io/badge/example-snippet-darkcyan)](#connect-php) ``` ::: diff --git a/docs/connect/index.md b/docs/connect/index.md index a36f3b4a..fcbbfdf8 100644 --- a/docs/connect/index.md +++ b/docs/connect/index.md @@ -178,7 +178,7 @@ application java javascript -php +php/index python ruby natural diff --git a/docs/connect/php.md b/docs/connect/php.md deleted file mode 100644 index 88512019..00000000 --- a/docs/connect/php.md +++ /dev/null @@ -1,126 +0,0 @@ -(connect-php)= - -# PHP - -:::{div} sd-text-muted -Available PHP drivers and adapters for CrateDB and CrateDB Cloud. -::: - -## AMPHP PostgreSQL driver - -The [AMPHP PostgreSQL driver], `amphp/postgres`, is an asynchronous -PostgreSQL client based on Amp. - -:::{rubric} Synopsis -::: -```php -prepare("SELECT * FROM sys.summits ORDER BY height DESC LIMIT 3"); - $result = $statement->execute(); - foreach ($result as $row) { - print_r($row); - } -})); -?> -``` -:::{rubric} Example -::: -- [Connect to CrateDB and CrateDB Cloud using AMPHP/PostgreSQL]   [![PHP AMPHP](https://github.com/crate/cratedb-examples/actions/workflows/lang-php-amphp.yml/badge.svg)](https://github.com/crate/cratedb-examples/actions/workflows/lang-php-amphp.yml) - -## PostgreSQL PDO driver - -[PDO_PGSQL] is a PHP-native driver that implements the PHP Data Objects (PDO) -interface to enable access from PHP to PostgreSQL databases. - -:::{rubric} Synopsis -::: -```php -query("SELECT * FROM sys.summits ORDER BY height DESC LIMIT 3"); -print_r($cursor->fetchAll(PDO::FETCH_ASSOC)); -?> -``` - -:::{rubric} Example -::: -- [Use the PDO_PGSQL driver with CrateDB]   [![PHP PDO](https://github.com/crate/cratedb-examples/actions/workflows/lang-php-pdo.yml/badge.svg)](https://github.com/crate/cratedb-examples/actions/workflows/lang-php-pdo.yml) - -## CrateDB PDO driver - -The PHP Data Objects (PDO) is a standard PHP extension that defines a common -interface for accessing databases in PHP. -The {ref}`crate-pdo:index` implements this specification, wrapping access to -CrateDB's HTTP interface. - -:::{rubric} Synopsis -::: -```php -'; -$user = 'crate'; -$password = null; -$options = null; -$connection = new PDOCrateDB($dsn, $user, $password, $options); - -$stm = $connection->query("SELECT * FROM sys.summits ORDER BY height DESC LIMIT 3"); -$result = $stm->fetch(); -print_r($result); -?> -``` - -[![Tests](https://github.com/crate/crate-pdo/actions/workflows/tests.yml/badge.svg)](https://github.com/crate/crate-pdo/actions/workflows/tests.yml) - -## CrateDB DBAL adapter - -DBAL is a PHP database abstraction layer that comes with database schema -introspection, schema management, and PDO support. -The {ref}`crate-dbal:index` implements this specification, wrapping access to -CrateDB's HTTP interface. The adapter currently does not support recent -versions of the Doctrine ORM. - -:::{rubric} Synopsis -::: -```php - 'Crate\DBAL\Driver\PDOCrate\Driver', - 'user' => 'admin', - 'password' => '', - 'host' => '.cratedb.net', - 'port' => 4200 -); - -$connection = \Doctrine\DBAL\DriverManager::getConnection($params); -$sql = "SELECT * FROM sys.summits ORDER BY height DESC LIMIT 3"; -$result = $connection->query($sql)->fetch(); - -print_r($result); -?> -``` - -[![Tests](https://github.com/crate/crate-dbal/actions/workflows/tests.yml/badge.svg)](https://github.com/crate/crate-dbal/actions/workflows/tests.yml) - - -[AMPHP PostgreSQL driver]: https://github.com/amphp/postgres -[Connect to CrateDB and CrateDB Cloud using AMPHP/PostgreSQL]: https://github.com/crate/cratedb-examples/tree/main/by-language/php-amphp -[PDO_PGSQL]: https://www.php.net/manual/en/ref.pdo-pgsql.php -[Use the PDO_PGSQL driver with CrateDB]: https://github.com/crate/cratedb-examples/tree/main/by-language/php-pdo diff --git a/docs/connect/php/amphp.md b/docs/connect/php/amphp.md new file mode 100644 index 00000000..a0234f97 --- /dev/null +++ b/docs/connect/php/amphp.md @@ -0,0 +1,42 @@ +(amphp)= + +# AMPHP PostgreSQL + +:::{div} .float-right .text-right +[![PHP AMPHP CI](https://github.com/crate/cratedb-examples/actions/workflows/lang-php-amphp.yml/badge.svg)](https://github.com/crate/cratedb-examples/actions/workflows/lang-php-amphp.yml) +::: +:::{div} .clearfix +::: + +The [AMPHP PostgreSQL driver], `amphp/postgres`, is an asynchronous +PostgreSQL client based on Amp. + +:::{rubric} Synopsis +::: +```php +prepare("SELECT * FROM sys.summits ORDER BY height DESC LIMIT 3"); + $result = $statement->execute(); + foreach ($result as $row) { + print_r($row); + } +})); +?> +``` +:::{rubric} Example +::: +- [Connect to CrateDB and CrateDB Cloud using AMPHP/PostgreSQL] + + +[AMPHP PostgreSQL driver]: https://github.com/amphp/postgres +[Connect to CrateDB and CrateDB Cloud using AMPHP/PostgreSQL]: https://github.com/crate/cratedb-examples/tree/main/by-language/php-amphp diff --git a/docs/connect/php/crate-dbal.md b/docs/connect/php/crate-dbal.md new file mode 100644 index 00000000..41f467dc --- /dev/null +++ b/docs/connect/php/crate-dbal.md @@ -0,0 +1,46 @@ +(crate-dbal)= + +# CrateDB DBAL + +:::{div} .float-right .text-right +[![crate-dbal CI](https://github.com/crate/crate-dbal/actions/workflows/tests.yml/badge.svg)](https://github.com/crate/crate-dbal/actions/workflows/tests.yml) +::: +:::{div} .clearfix +::: + +DBAL is a PHP database abstraction layer that comes with database schema +introspection, schema management, and PDO support. +The {ref}`crate-dbal:index`, `crate/crate-dbal`, implements this specification, +wrapping access to CrateDB's HTTP interface. +:::{warning} +The adapter currently does not support recent versions of the Doctrine ORM, +see [Add support for Doctrine 3] and [Add support for Doctrine 4]. Both +patches currently stalled, so please explicitly let us know if you have +any need for corresponding support. +::: + +:::{rubric} Synopsis +::: +```php + 'Crate\DBAL\Driver\PDOCrate\Driver', + 'user' => 'admin', + 'password' => '', + 'host' => '.cratedb.net', + 'port' => 4200 +); + +$connection = \Doctrine\DBAL\DriverManager::getConnection($params); +$sql = "SELECT * FROM sys.summits ORDER BY height DESC LIMIT 3"; +$result = $connection->query($sql)->fetch(); + +print_r($result); +?> +``` + + +[Add support for Doctrine 3]: https://github.com/crate/crate-dbal/pull/122 +[Add support for Doctrine 4]: https://github.com/crate/crate-dbal/pull/136 diff --git a/docs/connect/php/crate-pdo.md b/docs/connect/php/crate-pdo.md new file mode 100644 index 00000000..a129cbdb --- /dev/null +++ b/docs/connect/php/crate-pdo.md @@ -0,0 +1,34 @@ +(crate-pdo)= + +# CrateDB PDO + +:::{div} .float-right .text-right +[![crate-pdo CI](https://github.com/crate/crate-pdo/actions/workflows/tests.yml/badge.svg)](https://github.com/crate/crate-pdo/actions/workflows/tests.yml) +::: +:::{div} .clearfix +::: + +The PHP Data Objects (PDO) is a standard PHP extension that defines a common +interface for accessing databases in PHP. +The {ref}`crate-pdo:index`, `crate/crate-pdo`, implements this specification, +wrapping access to CrateDB's HTTP interface. + +:::{rubric} Synopsis +::: +```php +'; +$user = 'crate'; +$password = null; +$options = null; +$connection = new PDOCrateDB($dsn, $user, $password, $options); + +$stm = $connection->query("SELECT * FROM sys.summits ORDER BY height DESC LIMIT 3"); +$result = $stm->fetch(); +print_r($result); +?> +``` diff --git a/docs/connect/php/index.md b/docs/connect/php/index.md new file mode 100644 index 00000000..c0325d02 --- /dev/null +++ b/docs/connect/php/index.md @@ -0,0 +1,15 @@ +(connect-php)= + +# PHP + +:::{div} sd-text-muted +Connect to CrateDB and CrateDB Cloud from PHP. +::: + +:::{toctree} +:maxdepth: 1 +amphp +pdo-pgsql +crate-pdo +crate-dbal +::: diff --git a/docs/connect/php/pdo-pgsql.md b/docs/connect/php/pdo-pgsql.md new file mode 100644 index 00000000..dbc2a7bc --- /dev/null +++ b/docs/connect/php/pdo-pgsql.md @@ -0,0 +1,30 @@ +(pdo-pgsql)= + +# PostgreSQL PDO + +:::{div} .float-right .text-right +[![PHP PDO CI](https://github.com/crate/cratedb-examples/actions/workflows/lang-php-pdo.yml/badge.svg)](https://github.com/crate/cratedb-examples/actions/workflows/lang-php-pdo.yml) +::: +:::{div} .clearfix +::: + +[PDO_PGSQL] is a PHP-native driver that implements the PHP Data Objects (PDO) +interface, which enables access from PHP to PostgreSQL databases. + +:::{rubric} Synopsis +::: +```php +query("SELECT * FROM sys.summits ORDER BY height DESC LIMIT 3"); +print_r($cursor->fetchAll(PDO::FETCH_ASSOC)); +?> +``` + +:::{rubric} Example +::: +- [Use the PDO_PGSQL driver with CrateDB] + + +[PDO_PGSQL]: https://www.php.net/manual/en/ref.pdo-pgsql.php +[Use the PDO_PGSQL driver with CrateDB]: https://github.com/crate/cratedb-examples/tree/main/by-language/php-pdo