From: Michael Wallner <mike@php.net>
Date: Wed, 15 Oct 2014 05:40:56 +0000 (+0200)
Subject: partial QueryWriter
X-Git-Url: https://git.m6w6.name/?a=commitdiff_plain;h=8e466600d2aff5f9a4e3deb1ba72ac1047f29fcf;p=mdref%2Fmdref-pq-gateway

partial QueryWriter
---

diff --git a/pq-gateway/pq/Query.md b/pq-gateway/pq/Query.md
new file mode 100644
index 0000000..e2fd8e0
--- /dev/null
+++ b/pq-gateway/pq/Query.md
@@ -0,0 +1,3 @@
+# namespace pq\Query
+
+The pq\Query namespace holds implementations and interfaces related to assembling, expressing and executing queries on behalf of the gateway.
diff --git a/pq-gateway/pq/Query/Writer.md b/pq-gateway/pq/Query/Writer.md
new file mode 100644
index 0000000..2203f61
--- /dev/null
+++ b/pq-gateway/pq/Query/Writer.md
@@ -0,0 +1,13 @@
+# class pq\Query\Writer implements pq\Query\WriterInterface
+
+A query writer implementation.
+
+## Properties:
+
+* protected string $query  
+  The assembled query.
+* protected array $params  
+  The query parameters.
+* protected array $types  
+  The query parameters' types.
+
diff --git a/pq-gateway/pq/Query/Writer/__toString.md b/pq-gateway/pq/Query/Writer/__toString.md
new file mode 100644
index 0000000..ae0f1df
--- /dev/null
+++ b/pq-gateway/pq/Query/Writer/__toString.md
@@ -0,0 +1,11 @@
+# string pq\Query\Writer::__toString()
+
+Retrieve the assembled query.
+
+## Params:
+
+None.
+
+## Returns:
+
+* string, the plainy query string.
diff --git a/pq-gateway/pq/Query/Writer/criteria.md b/pq-gateway/pq/Query/Writer/criteria.md
new file mode 100644
index 0000000..0f27ae5
--- /dev/null
+++ b/pq-gateway/pq/Query/Writer/criteria.md
@@ -0,0 +1,41 @@
+# pq\Query\Writer pq\Query\Writer::criteria(array $criteria)
+
+Write nested AND/OR criteria to the query string.
+
+## Params:
+
+* array $criteria  
+  Nested AND/OR criteria.
+
+## Returns:
+
+* pq\Query\Writer, self.
+
+## Example:
+
+	<?php
+	
+	use pq\Query;
+	
+	$q = new Query\Writer;
+	$q->write("select * from account where")
+	  ->criteria([
+	    ["id >" => 1, "id <" => 5],
+	    ["name =" => "mike"]
+	  ]);
+	
+	var_dump((string) $q, $q->getParams());
+	
+	?>
+
+Yields:
+
+	string(84) "select * from account where ( ( ( id > $1 ) AND ( id < $2 ) ) OR ( ( name = $3 ) ) )"
+	array(3) {
+	  [0]=>
+	  int(1)
+	  [1]=>
+	  int(5)
+	  [2]=>
+	  string(4) "mike"
+	}
diff --git a/pq-gateway/pq/Query/Writer/getParams.md b/pq-gateway/pq/Query/Writer/getParams.md
new file mode 100644
index 0000000..719eb95
--- /dev/null
+++ b/pq-gateway/pq/Query/Writer/getParams.md
@@ -0,0 +1,11 @@
+# array pq\Query\Writer::getParams()
+
+Retrieve the query parameters.
+
+## Params:
+
+None.
+
+## Returns:
+
+* array, list of query parameters.
diff --git a/pq-gateway/pq/Query/Writer/getTypes.md b/pq-gateway/pq/Query/Writer/getTypes.md
new file mode 100644
index 0000000..277f0c9
--- /dev/null
+++ b/pq-gateway/pq/Query/Writer/getTypes.md
@@ -0,0 +1,11 @@
+# array pq\Query\Writer::getTypes()
+
+Get the query parameters' types.
+
+## Params:
+
+None.
+
+## Returns:
+
+* array, list of type OIDs.
diff --git a/pq-gateway/pq/Query/Writer/param.md b/pq-gateway/pq/Query/Writer/param.md
new file mode 100644
index 0000000..9a7e9a7
--- /dev/null
+++ b/pq-gateway/pq/Query/Writer/param.md
@@ -0,0 +1,35 @@
+# string pq\Query\Writer::param(mixed $param[, int $type = NULL])
+
+Remember the parameter with any associated type and return $N to be written to the query string.
+
+## Params:
+
+* mixed $param  
+  Query parameter value.
+* Optional int $type = NULL  
+  The type OID of the parameter.
+
+## Returns:
+
+* string, '$N', to be used with pq\Query\Writer::write(), where N is tne number of this parameter.
+
+## Example:
+
+	<?php
+	
+	use pq\Query;
+	
+	$writer = new Query\Writer;
+	$writer->write("SELECT", $writer->param(1));
+	
+	var_dump((string) $writer, $writer->getParams());
+	
+	?>
+
+Yields:
+
+	string(9) "SELECT $1"
+	array(1) {
+	  [0]=>
+	  int(1)
+	}
diff --git a/pq-gateway/pq/Query/Writer/reset.md b/pq-gateway/pq/Query/Writer/reset.md
new file mode 100644
index 0000000..c29d5cb
--- /dev/null
+++ b/pq-gateway/pq/Query/Writer/reset.md
@@ -0,0 +1,11 @@
+# pq\Query\Writer pq\Query\Writer::reset()
+
+Reset the query writer to initial state.
+
+## Params:
+
+None.
+
+## Returns:
+
+* pq\Query\Writer, self.
diff --git a/pq-gateway/pq/Query/Writer/write.md b/pq-gateway/pq/Query/Writer/write.md
new file mode 100644
index 0000000..ba03b7b
--- /dev/null
+++ b/pq-gateway/pq/Query/Writer/write.md
@@ -0,0 +1,11 @@
+# pq\Query\Writer pq\Query\Writer::write()
+
+Write a part of the query string.
+
+## Params:
+
+* Variable list of query parts.
+
+## Returns:
+
+* pq\Query\Writer, self.
diff --git a/pq-gateway/pq/Query/WriterInterface.md b/pq-gateway/pq/Query/WriterInterface.md
new file mode 100644
index 0000000..3d3718f
--- /dev/null
+++ b/pq-gateway/pq/Query/WriterInterface.md
@@ -0,0 +1,4 @@
+# interface pq\Query\WriterInterface
+
+API for assembling unnamed statements with safe parameter substitution.
+See pq\Gateway\Table::setQueryWriter().
diff --git a/pq-gateway/pq/Query/WriterInterface/__toString.md b/pq-gateway/pq/Query/WriterInterface/__toString.md
new file mode 100644
index 0000000..46fa92b
--- /dev/null
+++ b/pq-gateway/pq/Query/WriterInterface/__toString.md
@@ -0,0 +1,11 @@
+# string pq\Query\WriterInterface::__toString()
+
+Retrieve the assembled query.
+
+## Params:
+
+None.
+
+## Returns:
+
+* string, the plainy query string.
diff --git a/pq-gateway/pq/Query/WriterInterface/criteria.md b/pq-gateway/pq/Query/WriterInterface/criteria.md
new file mode 100644
index 0000000..374e1d1
--- /dev/null
+++ b/pq-gateway/pq/Query/WriterInterface/criteria.md
@@ -0,0 +1,41 @@
+# pq\Query\WriterInterface pq\Query\WriterInterface::criteria(array $criteria)
+
+Write nested AND/OR criteria to the query string.
+
+## Params:
+
+* array $criteria  
+  Nested AND/OR criteria.
+
+## Returns:
+
+* pq\Query\WriterInterface, self.
+
+## Example:
+
+	<?php
+	
+	use pq\Query;
+	
+	$q = new Query\Writer;
+	$q->write("select * from account where")
+	  ->criteria([
+	    ["id >" => 1, "id <" => 5],
+	    ["name =" => "mike"]
+	  ]);
+	
+	var_dump((string) $q, $q->getParams());
+	
+	?>
+
+Yields:
+
+	string(84) "select * from account where ( ( ( id > $1 ) AND ( id < $2 ) ) OR ( ( name = $3 ) ) )"
+	array(3) {
+	  [0]=>
+	  int(1)
+	  [1]=>
+	  int(5)
+	  [2]=>
+	  string(4) "mike"
+	}
diff --git a/pq-gateway/pq/Query/WriterInterface/getParams.md b/pq-gateway/pq/Query/WriterInterface/getParams.md
new file mode 100644
index 0000000..7839a60
--- /dev/null
+++ b/pq-gateway/pq/Query/WriterInterface/getParams.md
@@ -0,0 +1,11 @@
+# array pq\Query\WriterInterface::getParams()
+
+Retrieve the query parameters.
+
+## Params:
+
+None.
+
+## Returns:
+
+* array, list of query parameters.
diff --git a/pq-gateway/pq/Query/WriterInterface/getTypes.md b/pq-gateway/pq/Query/WriterInterface/getTypes.md
new file mode 100644
index 0000000..f518c52
--- /dev/null
+++ b/pq-gateway/pq/Query/WriterInterface/getTypes.md
@@ -0,0 +1,11 @@
+# array pq\Query\WriterInterface::getTypes()
+
+Get the query parameters' types.
+
+## Params:
+
+None.
+
+## Returns:
+
+* array, list of type OIDs.
diff --git a/pq-gateway/pq/Query/WriterInterface/param.md b/pq-gateway/pq/Query/WriterInterface/param.md
new file mode 100644
index 0000000..f674fba
--- /dev/null
+++ b/pq-gateway/pq/Query/WriterInterface/param.md
@@ -0,0 +1,35 @@
+# string pq\Query\WriterInterface::param(mixed $param[, int $type = NULL])
+
+Remember the parameter with any associated type and return $N to be written to the query string.
+
+## Params:
+
+* mixed $param  
+  Query parameter value.
+* Optional int $type = NULL  
+  The type OID of the parameter.
+
+## Returns:
+
+* string, '$N', to be used with pq\Query\WriterInterface::write(), where N is tne number of this parameter.
+
+## Example:
+
+	<?php
+	
+	use pq\Query;
+	
+	$writer = new Query\Writer;
+	$writer->write("SELECT", $writer->param(1));
+	
+	var_dump((string) $writer, $writer->getParams());
+	
+	?>
+
+Yields:
+
+	string(9) "SELECT $1"
+	array(1) {
+	  [0]=>
+	  int(1)
+	}
diff --git a/pq-gateway/pq/Query/WriterInterface/reset.md b/pq-gateway/pq/Query/WriterInterface/reset.md
new file mode 100644
index 0000000..31f9005
--- /dev/null
+++ b/pq-gateway/pq/Query/WriterInterface/reset.md
@@ -0,0 +1,11 @@
+# pq\Query\WriterInterface pq\Query\WriterInterface::reset()
+
+Reset the query writer to initial state.
+
+## Params:
+
+None.
+
+## Returns:
+
+* pq\Query\WriterInterface, self.
diff --git a/pq-gateway/pq/Query/WriterInterface/write.md b/pq-gateway/pq/Query/WriterInterface/write.md
new file mode 100644
index 0000000..18f44a5
--- /dev/null
+++ b/pq-gateway/pq/Query/WriterInterface/write.md
@@ -0,0 +1,11 @@
+# pq\Query\WriterInterface pq\Query\WriterInterface::write()
+
+Write a part of the query string.
+
+## Params:
+
+* Variable list of query parts.
+
+## Returns:
+
+* pq\Query\WriterInterface, self.