From e6f6384f6f9bf4cf6b40fefe3262bcefccbed2a3 Mon Sep 17 00:00:00 2001 From: Michael Wallner Date: Tue, 30 Sep 2014 14:35:31 +0200 Subject: [PATCH] finished! --- pq.md | 18 +++++- pq/COPY.md | 21 ++++++ pq/COPY/__construct.md | 14 ++++ pq/COPY/end.md | 14 ++++ pq/COPY/get.md | 18 ++++++ pq/COPY/put.md | 14 ++++ pq/Cancel.md | 8 +++ pq/Cancel/__construct.md | 14 ++++ pq/Cancel/cancel.md | 49 ++++++++++++++ pq/Converter.md | 103 ++++++++++++++++++++++++++++++ pq/Converter/convertFromString.md | 26 ++++++++ pq/Converter/convertToString.md | 26 ++++++++ pq/Converter/convertTypes.md | 23 +++++++ pq/DateTime.md | 23 +++++++ pq/DateTime/__toString.md | 11 ++++ pq/DateTime/jsonSerialize.md | 12 ++++ 16 files changed, 392 insertions(+), 2 deletions(-) create mode 100644 pq/COPY.md create mode 100644 pq/COPY/__construct.md create mode 100644 pq/COPY/end.md create mode 100644 pq/COPY/get.md create mode 100644 pq/COPY/put.md create mode 100644 pq/Cancel.md create mode 100644 pq/Cancel/__construct.md create mode 100644 pq/Cancel/cancel.md create mode 100644 pq/Converter.md create mode 100644 pq/Converter/convertFromString.md create mode 100644 pq/Converter/convertToString.md create mode 100644 pq/Converter/convertTypes.md create mode 100644 pq/DateTime.md create mode 100644 pq/DateTime/__toString.md create mode 100644 pq/DateTime/jsonSerialize.md diff --git a/pq.md b/pq.md index 485daee..9e920d4 100644 --- a/pq.md +++ b/pq.md @@ -11,5 +11,19 @@ This is a modern binding to the mature [libpq](http://www.postgresql.org/docs/cu * Fetching simple [multi-dimensional array maps](pq/Result/map). * Working [Gateway implementation](https://bitbucket.org/m6w6/pq-gateway). -> ***NOTE:*** - This documentation is work in progress. +## Installation: + +This extension is hosted at PECL and can be installed with PEAR’s pecl command: + + # pecl install pq + +## Dependencies: + +This extension unconditionally depends on the pre-loaded presence of the following PHP extensions: + +* raphf +* spl + +It optionally depends on the following extensions: + +* json diff --git a/pq/COPY.md b/pq/COPY.md new file mode 100644 index 0000000..6a2031d --- /dev/null +++ b/pq/COPY.md @@ -0,0 +1,21 @@ +# class pq\COPY + +Fast import/export using COPY. + +## Constants: + +* FROM_STDIN + Start a COPY operation from STDIN to the PostgreSQL server. +* TO_STDOUT + Start a COPY operation from the server to STDOUT. + +## Properties: + +* public (readonly) pq\Connection $connection + The connection to the PostgreSQL server. +* public (readonly) string $expression + The expression of the COPY statement used to start the operation. +* public (readonly) int $direction + The drection of the COPY operation (pq\COPY::FROM_STDIN or pq\COPY::TO_STDOUT). +* public (readonly) string $options + Any additional options used to start the COPY operation. diff --git a/pq/COPY/__construct.md b/pq/COPY/__construct.md new file mode 100644 index 0000000..356dd6e --- /dev/null +++ b/pq/COPY/__construct.md @@ -0,0 +1,14 @@ +# void pq\COPY::__construct(pq\Connection $conn, string $expression, int $direction[, string $options = NULL]) + +Start a COPY operation. + +## Params: + +* pq\Connection $conn + The connection to use for the COPY operation. +* string $expression + The expression generating the data to copy. +* int $direction + Data direction (pq\COPY::FROM_STDIN or pq\COPY::TO_STDOUT). +* Optional string $options = NULL + Any COPY options (see the [official PostgreSQL documentaion](http://www.postgresql.org/docs/current/static/sql-copy.html) for details. diff --git a/pq/COPY/end.md b/pq/COPY/end.md new file mode 100644 index 0000000..7f4c06c --- /dev/null +++ b/pq/COPY/end.md @@ -0,0 +1,14 @@ +# void pq\COPY::end([string $error = NULL]) + +End the COPY operation to the server during pq\Result::COPY_IN state. + +## Params: + +* Optional string $error = NULL + If set, the COPY operation will abort with provided message. + +## Throws: + +* pq\Exception\InvalidArgumentException +* pq\Exception\BadMethodCallException +* pq\Exception\RuntimeException diff --git a/pq/COPY/get.md b/pq/COPY/get.md new file mode 100644 index 0000000..3852039 --- /dev/null +++ b/pq/COPY/get.md @@ -0,0 +1,18 @@ +# bool pq\COPY::get(string &$data) + +Receive data from the server during pq\Result::COPY_OUT state. + +## Params: + +* string &$data + Data read from the server. + +## Returns: + +* bool, success. + +## Throws: + +* pq\Exception\InvalidArgumentException +* pq\Exception\BadMethodCallExceptin +* pq\Exception\RuntimeException diff --git a/pq/COPY/put.md b/pq/COPY/put.md new file mode 100644 index 0000000..b5e0547 --- /dev/null +++ b/pq/COPY/put.md @@ -0,0 +1,14 @@ +# void pq\COPY::put(string $data) + +Send data to the server during pq\Result::COPY_IN state. + +## Params: + +* string $data + Data to send to the server. + +## Throws: + +* pq\Exception\InvalidArgumentException +* pq\Exception\BadMethodCallException +* pq\Exception\RuntimeException diff --git a/pq/Cancel.md b/pq/Cancel.md new file mode 100644 index 0000000..1e49d5f --- /dev/null +++ b/pq/Cancel.md @@ -0,0 +1,8 @@ +# class pq\Cancel + +Request cancellation of an asynchronous query. + +## Properties: + +* public (readonly) pq\Connection $connection + The connection to cancel the query on. diff --git a/pq/Cancel/__construct.md b/pq/Cancel/__construct.md new file mode 100644 index 0000000..24fc524 --- /dev/null +++ b/pq/Cancel/__construct.md @@ -0,0 +1,14 @@ +# void pq\Cancel::__construct(pq\Connection $conn) + +Create a new cancellation request for an [asynchronous](pq/Connection/: Asynchronous Usage) query. + +## Params: + +* pq\Connection $conn + The connection to request cancellation on. + +## Throws: + +* pq\Exception\InvalidArgumentException +* pq\Exception\BadMethodCallException +* pq\Exception\RuntimeException diff --git a/pq/Cancel/cancel.md b/pq/Cancel/cancel.md new file mode 100644 index 0000000..11cbf70 --- /dev/null +++ b/pq/Cancel/cancel.md @@ -0,0 +1,49 @@ +# void pq\Cancel::cancel() + +Perform the cancellation request. + +## Params: + +None. + +## Throws: + +* pq\Exception\InvalidArgumentException +* pq\Exception\BadMethodCallException +* pq\Exception\RuntimeException + + +## Example: + + execAsync("SELECT pg_sleep(1)"); + $cancel->cancel(); + + var_dump($conn->getResult()); + + ?> + +Yields: + + object(pq\Result)#4 (8) { + ["status"]=> + int(7) + ["statusMessage"]=> + string(11) "FATAL_ERROR" + ["errorMessage"]=> + string(47) "ERROR: canceling statement due to user request" + ["numRows"]=> + int(0) + ["numCols"]=> + int(0) + ["affectedRows"]=> + int(0) + ["fetchType"]=> + int(0) + ["autoConvert"]=> + int(65535) + } diff --git a/pq/Converter.md b/pq/Converter.md new file mode 100644 index 0000000..dee32c4 --- /dev/null +++ b/pq/Converter.md @@ -0,0 +1,103 @@ +# interface pq\Converter + +Interface for type conversions. + +## Example: + + x = $x; + $this->y = $y; + } + } + + /** + * A simple Box + */ + class Box { + public $p1; + public $p2; + function __construct(Point $p1, Point $p2) { + $this->p1 = $p1; + $this->p2 = $p2; + } + } + + /** + * Our converter handles only objects of type box + */ + class BoxConverter implements pq\Converter { + private $oid; + function __construct(pq\Types $types) { + $this->oid = $types["box"]->oid; + } + + /** + * @return array + * @see pq\Converter::convertTypes() + */ + function convertTypes() { + return [$this->oid]; + } + + /** + * @return string + * @param $box Box + * @see pq\Converter::convertToString() + */ + function convertToString($box, $type = NULL) { + return sprintf("(%F,%F),(%F,%F)", + $box->p1->x, $box->p1->y, + $box->p2->x, $box->p2->y + ); + } + + /** + * @return Box + * @param string $data + * @see pq\Converter::convertFromString() + */ + function convertFromString($data, $type = NULL) { + list($p1x, $p1y, $p2x, $p2y) = sscanf($data, "(%f,%f),(%f,%f)"); + return new Box(new Point($p1x, $p1y), new Point($p2x, $p2y)); + } + } + + $conn = new pq\Connection; + $types = new pq\Types($conn); + $conv = new BoxConverter($types); + $inbox = new Box(new Point(1.1, 2.2), new Point(3.3, 4.4)); + + $conn->setConverter($conv); + $result = $conn->execParams("SELECT \$1", [$inbox], [$types["box"]->oid]); + $result->fetchCol($outbox); + + var_dump($outbox); + + ?> + +Yields: + + object(Box)#163 (2) { + ["p1"]=> + object(Point)#164 (2) { + ["x"]=> + float(3.3) + ["y"]=> + float(4.4) + } + ["p2"]=> + object(Point)#165 (2) { + ["x"]=> + float(1.1) + ["y"]=> + float(2.2) + } + } diff --git a/pq/Converter/convertFromString.md b/pq/Converter/convertFromString.md new file mode 100644 index 0000000..e7bc701 --- /dev/null +++ b/pq/Converter/convertFromString.md @@ -0,0 +1,26 @@ +# mixed pq\Converter::convertFromString(string $data[, int $type = NULL) + +Convert a string received from the PostgreSQL server back to a PHP type. + +## Params: + +* string $data + String data received from the server. +* Optional in $type = NULL + The type of the data. Irrelevant for single-type converters. + +## Returns: + +* mixed, the value converted to a PHP type. + +## Example: + + diff --git a/pq/Converter/convertToString.md b/pq/Converter/convertToString.md new file mode 100644 index 0000000..5328a2e --- /dev/null +++ b/pq/Converter/convertToString.md @@ -0,0 +1,26 @@ +# string pq\Converter::convertToString(mixed $value[, int $type = NULL]) + +Convert a value to a string for use in a query. + +## Params: + +* mixed $value + The PHP value which should be converted to a string. +* Optional int $type = NULL + The type the converter should handle. Irrelevant for singly-type converters. + +## Returns: + +* string, a textual represenation of the value accepted by the PostgreSQL server. + +## Example: + + diff --git a/pq/Converter/convertTypes.md b/pq/Converter/convertTypes.md new file mode 100644 index 0000000..89c6344 --- /dev/null +++ b/pq/Converter/convertTypes.md @@ -0,0 +1,23 @@ +# array pq\Converter::convertTypes() + +Announce which types the implementing converter can handle. + +## Params: + +None. + +## Returns: + +* array, OIDs of handled types. + +## Example: + + diff --git a/pq/DateTime.md b/pq/DateTime.md new file mode 100644 index 0000000..2350644 --- /dev/null +++ b/pq/DateTime.md @@ -0,0 +1,23 @@ +# class pq\DateTime extends DateTime implements JsonSerializable + +A simple DateTime wrapper with predefined formats which supports stringification and JSON. + +## Formats: + +Type | Format +-----|------- +pq\Types::DATE | "Y-m-d" +pq\Types::ABSTIME | "Y-m-d H:i:s" +pq\Types::TIMESTAMP | "Y-m-d H:i:s.u" +pq\Types::TIMESTAMPTZ | "Y-m-d H:i:s.uO" + +> ***NOTE:*** + Date/time values will conly be converted to pq\DateTime and from DateTime if the pq\Result::CONV_DATETIME bit is set in pq\Result::$autoConvert. + +## Properties: + +* public string $format = "Y-m-d H:i:s.uO" + The default format of any date/time type automatically converted by pq\Result (depends on the actual type of the column). + + + diff --git a/pq/DateTime/__toString.md b/pq/DateTime/__toString.md new file mode 100644 index 0000000..a8f1e64 --- /dev/null +++ b/pq/DateTime/__toString.md @@ -0,0 +1,11 @@ +# string pq\DateTime::__toString() + +Stringify the DateTime instance according to pq\DateTime::$format. + +## Params: + +None. + +## Returns: + +* string, the DateTime as string. diff --git a/pq/DateTime/jsonSerialize.md b/pq/DateTime/jsonSerialize.md new file mode 100644 index 0000000..8187658 --- /dev/null +++ b/pq/DateTime/jsonSerialize.md @@ -0,0 +1,12 @@ +# string pq\DateTime::jsonSerialize() + +Serialize to JSON. +Alias of pq\DateTime::__toString(). + +## Params: + +None. + +## Returns: + +* string, the DateTime stringified according to pq\DateTime::$format. -- 2.30.2