From: Michael Wallner <mike@php.net>
Date: Tue, 30 Sep 2014 12:35:31 +0000 (+0200)
Subject: finished!
X-Git-Url: https://git.m6w6.name/?a=commitdiff_plain;h=e6f6384f6f9bf4cf6b40fefe3262bcefccbed2a3;p=mdref%2Fmdref-pq

finished!
---

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:
+
+	<?php
+	
+	$conn = new pq\Connection;
+	$cancel = new pq\Cancel($conn);
+	
+	$conn->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:
+
+	<?php
+	
+	/**
+	 * Naive geometric point
+	 */
+	class Point {
+		public $x;
+		public $y;
+		function __construct($x, $y) {
+			$this->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:
+
+	<?php
+	
+	abstract class Example implements pq\Converter {
+		function convertFromString($data, $type = NULL) {
+			return uuid_parse($data);
+		}
+	}
+	
+	?>
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:
+
+	<?php
+	
+	abstract class Example implements pq\Converter {
+		function convertToString($uuid, $type = NULL)  {
+			return uuid_unparse($uuid);
+		}
+	}
+	
+	?>
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:
+
+	<?php
+	
+	abstract class Example implements pq\Converter {
+		function convertTypes() {
+			return [pq\Types::UUID];
+		}
+	}
+	
+	?>
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.