?  search:
summary | log | graphiclog1 | graphiclog2 | commit | commitdiff | tree | refs | edit | fork
blame | history | raw | HEAD
The real release 0.46 :-)
[awl.git] / docs / api / awl / PgQuery / _PgQuery.php.html
blobebe0e7766ba7aef6a7e2560e98052c167849adc0
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml">
4 <head>
5 <!-- template designed by Marco Von Ballmoos -->
6 <title>Docs for page PgQuery.php</title>
7 <link rel="stylesheet" href="../../media/stylesheet.css" />
8 <script src="../../media/lib/classTree.js"></script>
9 <script language="javascript" type="text/javascript">
10 var imgPlus = new Image();
11 var imgMinus = new Image();
12 imgPlus.src = "../../media/images/plus.png";
13 imgMinus.src = "../../media/images/minus.png";
14
15 function showNode(Node){
16 switch(navigator.family){
17 case 'nn4':
18 // Nav 4.x code fork...
19 var oTable = document.layers["span" + Node];
20 var oImg = document.layers["img" + Node];
21 break;
22 case 'ie4':
23 // IE 4/5 code fork...
24 var oTable = document.all["span" + Node];
25 var oImg = document.all["img" + Node];
26 break;
27 case 'gecko':
28 // Standards Compliant code fork...
29 var oTable = document.getElementById("span" + Node);
30 var oImg = document.getElementById("img" + Node);
31 break;
32 }
33 oImg.src = imgMinus.src;
34 oTable.style.display = "block";
35 }
36
37 function hideNode(Node){
38 switch(navigator.family){
39 case 'nn4':
40 // Nav 4.x code fork...
41 var oTable = document.layers["span" + Node];
42 var oImg = document.layers["img" + Node];
43 break;
44 case 'ie4':
45 // IE 4/5 code fork...
46 var oTable = document.all["span" + Node];
47 var oImg = document.all["img" + Node];
48 break;
49 case 'gecko':
50 // Standards Compliant code fork...
51 var oTable = document.getElementById("span" + Node);
52 var oImg = document.getElementById("img" + Node);
53 break;
54 }
55 oImg.src = imgPlus.src;
56 oTable.style.display = "none";
57 }
58
59 function nodeIsVisible(Node){
60 switch(navigator.family){
61 case 'nn4':
62 // Nav 4.x code fork...
63 var oTable = document.layers["span" + Node];
64 break;
65 case 'ie4':
66 // IE 4/5 code fork...
67 var oTable = document.all["span" + Node];
68 break;
69 case 'gecko':
70 // Standards Compliant code fork...
71 var oTable = document.getElementById("span" + Node);
72 break;
73 }
74 return (oTable && oTable.style.display == "block");
75 }
76
77 function toggleNodeVisibility(Node){
78 if (nodeIsVisible(Node)){
79 hideNode(Node);
80 }else{
81 showNode(Node);
82 }
83 }
84 </script>
85 </head>
86 <body>
87 <div class="page-body">
88 <h2 class="file-name"><img src="../../media/images/Page_logo.png" alt="File" style="vertical-align: middle">/PgQuery.php</h2>
89
90 <a name="sec-description"></a>
91 <div class="info-box">
92 <div class="info-box-title">Description</div>
93 <div class="nav-bar">
94 <span class="disabled">Description</span> |
95 <a href="#sec-classes">Classes</a>
96 | <a href="#sec-includes">Includes</a>
97 | <a href="#sec-variables">Variables</a>
98 | <a href="#sec-functions">Functions</a>
99 </div>
100 <div class="info-box-body">
101 <!-- ========== Info from phpDoc block ========= -->
102 <p class="short-description">PostgreSQL query class and associated functions</p>
103 <p class="description"><p>This subpackage provides some functions that are useful around database activity and a PgQuery class to simplify handling of database queries.</p><p>The class is intended to be a very lightweight wrapper with no pretentions towards database independence, but it does include some features that have proved useful in developing and debugging web-based applications: <ul><li>All queries are timed, and an expected time can be provided.</li><li>Parameters replaced into the SQL will be escaped correctly in order to
104 minimise the chances of SQL injection errors.</li><li>Queries which fail, or which exceed their expected execution time, will
105 be logged for potential further analysis.</li><li>Debug logging of queries may be enabled globally, or restricted to
106 particular sets of queries.</li><li>Simple syntax for iterating through a result set.</li></ul> The database should be connected in a variable $dbconn before PgQuery.php is included. If not already connected, PgQuery will attempt to connect to the database, successively applying connection parameters from the array in $c-&gt;pg_connect.</p><p>We will die if the database is not currently connected and we fail to find a working connection.</p></p>
107 <ul class="tags">
108 <li><span class="field">author:</span> Andrew McMillan &lt;<a href="mailto:andrew@mcmillan.net.nz">andrew@mcmillan.net.nz</a>&gt;</li>
109 <li><span class="field">copyright:</span> Catalyst IT Ltd, Morphoss Ltd &lt;http://www.morphoss.com/&gt;</li>
110 <li><span class="field">license:</span> <a href="http://gnu.org/copyleft/gpl.html">GNU GPL v2 or later</a></li>
111 </ul>
112
113 </div>
114 </div>
115
116 <a name="sec-classes"></a>
117 <div class="info-box">
118 <div class="info-box-title">Classes</div>
119 <div class="nav-bar">
120 <a href="#sec-description">Description</a> |
121 <span class="disabled">Classes</span>
122 | <a href="#sec-includes">Includes</a>
123 | <a href="#sec-variables">Variables</a>
124 | <a href="#sec-functions">Functions</a>
125 </div>
126 <div class="info-box-body">
127 <table cellpadding="2" cellspacing="0" class="class-table">
128 <tr>
129 <th class="class-table-header">Class</th>
130 <th class="class-table-header">Description</th>
131 </tr>
132 <tr>
133 <td style="padding-right: 2em; vertical-align: top; white-space: nowrap">
134 <img src="../../media/images/Class.png"
135 alt=" class"
136 title=" class"/>
137 <a href="../../awl/PgQuery/PgQuery.html">PgQuery</a>
138 </td>
139 <td>
140 The PgQuery Class.
141 </td>
142 </tr>
143 </table>
144 </div>
145 </div>
146
147 <a name="sec-includes"></a>
148 <div class="info-box">
149 <div class="info-box-title">Includes</div>
150 <div class="nav-bar">
151 <a href="#sec-description">Description</a> |
152 <a href="#sec-classes">Classes</a>
153 | <span class="disabled">Includes</span>
154 | <a href="#sec-variables">Variables</a>
155 | <a href="#sec-functions">Functions</a>
156 </div>
157 <div class="info-box-body">
158 <a name="_AWLUtilities_php"><!-- --></a>
159 <div class="evenrow">
160
161 <div>
162 <img src="../../media/images/Page.png" alt=" " />
163 <span class="include-title">
164 <span class="include-type">require_once</span>
165 (<span class="include-name"><a href="../../awl/Utilities/_AWLUtilities.php.html">"AWLUtilities.php"</a></span>)
166 (line <span class="line-number">56</span>)
167 </span>
168 </div>
169
170 <!-- ========== Info from phpDoc block ========= -->
171
172 </div>
173 </div>
174 </div>
175
176
177 <a name="sec-variables"></a>
178 <div class="info-box">
179 <div class="info-box-title">Variables</div>
180 <div class="nav-bar">
181 <a href="#sec-description">Description</a> |
182 <a href="#sec-classes">Classes</a>
183 | <a href="#sec-includes">Includes</a>
184 | <span class="disabled">Variables</span>
185 | <a href="#sec-functions">Functions</a>
186 </div>
187 <div class="info-box-body">
188 <a name="global$dbconn
189 The database connection." id="global$dbconn
190 The database connection."><!-- --></a>
191 <div class="oddrow">
192
193 <div>
194 <img src="../../media/images/Global.png" />
195 <span class="var-title">
196 <span class="var-type">resource</span>
197 <span class="var-name">$dbconn
198 The database connection.</span>
199 (line <span class="line-number">107</span>)
200 </span>
201 </div>
202
203 <!-- ========== Info from phpDoc block ========= -->
204 <ul class="tags">
205 <li><span class="field">name:</span> $dbconn
206 The database connection.</li>
207 </ul>
208
209
210 </div>
211 </div>
212 </div>
213
214 <a name="sec-functions"></a>
215 <div class="info-box">
216 <div class="info-box-title">Functions</div>
217 <div class="nav-bar">
218 <a href="#sec-description">Description</a> |
219 <a href="#sec-classes">Classes</a>
220 | <a href="#sec-includes">Includes</a>
221 | <a href="#sec-variables">Variables</a>
222 | <span class="disabled">Functions</span>
223 </div>
224 <div class="info-box-body">
225 <a name="functionawl_replace_sql_args" id="functionawl_replace_sql_args"><!-- --></a>
226 <div class="evenrow">
227
228 <div>
229 <img src="../../media/images/Function.png" />
230 <span class="method-title">awl_replace_sql_args</span> (line <span class="line-number">219</span>)
231 </div>
232
233 <!-- ========== Info from phpDoc block ========= -->
234 <p class="short-description">Replaces PostgreSQL query with escaped parameters in preparation for execution.</p>
235 <p class="description"><p>The function takes a variable number of arguments, the first is the SQL string, with replaceable '?' characters (a la DBI). The subsequent parameters being the values to replace into the SQL string.</p><p>The values passed to the routine are analyzed for type, and quoted if they appear to need quoting. This can go wrong for (e.g.) NULL or other special SQL values which are not straightforwardly identifiable as needing quoting (or not). In such cases the parameter can be forced to be inserted unquoted by passing it as &quot;array( 'plain' =&gt; $param )&quot;.</p><p>This function is outside the PgQuery class because it is sometimes desirable to build SQL command strings in circumstances where there is no benefit to using the class.</p></p>
236 <ul class="tags">
237 <li><span class="field">return:</span> built query string</li>
238 </ul>
239 <div class="method-signature">
240 <span class="method-result">The</span>
241 <span class="method-name">
242 awl_replace_sql_args
243 </span>
244 (<span class="var-type">string</span>&nbsp;<span class="var-name">0</span>, <span class="var-type">mixed</span>&nbsp;<span class="var-name">1</span>)
245 </div>
246
247 <ul class="parameters">
248 <li>
249 <span class="var-type">string</span>
250 <span class="var-name">0</span><span class="var-description">: The query string with replacable '?' characters.</span> </li>
251 <li>
252 <span class="var-type">mixed</span>
253 <span class="var-name">1</span><span class="var-description">: The values to replace into the SQL string.</span> </li>
254 </ul>
255
256
257 </div>
258 <a name="functionclean_string" id="functionclean_string"><!-- --></a>
259 <div class="oddrow">
260
261 <div>
262 <img src="../../media/images/Function.png" />
263 <span class="method-title">clean_string</span> (line <span class="line-number">182</span>)
264 </div>
265
266 <!-- ========== Info from phpDoc block ========= -->
267 <p class="short-description">Clean a string of many suspicious characters</p>
268 <p class="description"><p>While this is a fairly aggressive approach, it applies in many circumstances where various strings should not contain things that might screw up (e.g.) filesystem semantics. Although not strictly a PgQuery function it's here for the time being until I invent a new &quot;generally useful functions&quot; include.</p></p>
269 <ul class="tags">
270 <li><span class="field">return:</span> The pristine uncontaminated string we can safely use for Just About Anything(tm).</li>
271 </ul>
272 <div class="method-signature">
273 <span class="method-result">string</span>
274 <span class="method-name">
275 clean_string
276 </span>
277 (<span class="var-type">string</span>&nbsp;<span class="var-name">$unclean</span>, [<span class="var-type"></span>&nbsp;<span class="var-name">$type</span> = <span class="var-default">&#039;full&#039;</span>])
278 </div>
279
280 <ul class="parameters">
281 <li>
282 <span class="var-type">string</span>
283 <span class="var-name">$unclean</span><span class="var-description">: The dirty filthy string needing washing.</span> </li>
284 <li>
285 <span class="var-type"></span>
286 <span class="var-name">$type</span> </li>
287 </ul>
288
289
290 </div>
291 <a name="functionconnect_configured_database" id="functionconnect_configured_database"><!-- --></a>
292 <div class="evenrow">
293
294 <div>
295 <img src="../../media/images/Function.png" />
296 <span class="method-title">connect_configured_database</span> (line <span class="line-number">61</span>)
297 </div>
298
299 <!-- ========== Info from phpDoc block ========= -->
300 <p class="short-description">Connect to the database defined in the $c-&gt;dbconn[] array</p>
301 <div class="method-signature">
302 <span class="method-result">void</span>
303 <span class="method-name">
304 connect_configured_database
305 </span>
306 ()
307 </div>
308
309
310
311 </div>
312 <a name="functionduration" id="functionduration"><!-- --></a>
313 <div class="oddrow">
314
315 <div>
316 <img src="../../media/images/Function.png" />
317 <span class="method-title">duration</span> (line <span class="line-number">121</span>)
318 </div>
319
320 <!-- ========== Info from phpDoc block ========= -->
321 <p class="short-description">A duration (in decimal seconds) between two times which are the result of calls to microtime()</p>
322 <p class="description"><p>This simple function is used by the PgQuery class because the microtime function doesn't return a decimal time, so a simple subtraction is not sufficient.</p></p>
323 <ul class="tags">
324 <li><span class="field">return:</span> difference</li>
325 </ul>
326 <div class="method-signature">
327 <span class="method-result">double</span>
328 <span class="method-name">
329 duration
330 </span>
331 (<span class="var-type">microtime</span>&nbsp;<span class="var-name">$t1</span>, <span class="var-type">microtime</span>&nbsp;<span class="var-name">$t2</span>)
332 </div>
333
334 <ul class="parameters">
335 <li>
336 <span class="var-type">microtime</span>
337 <span class="var-name">$t1</span><span class="var-description">: start time</span> </li>
338 <li>
339 <span class="var-type">microtime</span>
340 <span class="var-name">$t2</span><span class="var-description">: end time</span> </li>
341 </ul>
342
343
344 </div>
345 <a name="functionqpg" id="functionqpg"><!-- --></a>
346 <div class="evenrow">
347
348 <div>
349 <img src="../../media/images/Function.png" />
350 <span class="method-title">qpg</span> (line <span class="line-number">147</span>)
351 </div>
352
353 <!-- ========== Info from phpDoc block ========= -->
354 <p class="short-description">Quote the given string (depending on its type) so that it can be used safely in a PostgreSQL query without fear of SQL injection errors.</p>
355 <p class="description"><p>Although this function effectively achieves a similar goal to the pg_escape_string() function, it is needed for older versions of PHP (&lt; 4.2.0) and older versions of PostgreSQL (&lt; 7.2.0), however. PgQuery does not attempt to use the newer pg_escape_string() function at this stage.</p><p>This function is outside the PgQuery class because it is sometimes desirable to quote values for SQL command strings in circumstances where there is no benefit to using the class.</p></p>
356 <ul class="tags">
357 <li><span class="field">return:</span> NULL, TRUE, FALSE, a plain number, or the original string quoted and with ' and \ characters escaped</li>
358 </ul>
359 <div class="method-signature">
360 <span class="method-result">string</span>
361 <span class="method-name">
362 qpg
363 </span>
364 ([<span class="var-type">mixed</span>&nbsp;<span class="var-name">$str</span> = <span class="var-default">null</span>])
365 </div>
366
367 <ul class="parameters">
368 <li>
369 <span class="var-type">mixed</span>
370 <span class="var-name">$str</span><span class="var-description">: Data to be converted to a string suitable for including as a value in SQL.</span> </li>
371 </ul>
372
373
374 </div>
375 </div>
376 </div>
377
378 <p class="notes" id="credit">
379 Documentation generated on Tue, 28 Dec 2010 02:01:36 +1300 by <a href="http://www.phpdoc.org" target="_blank">phpDocumentor 1.4.3</a>
380 </p>
381 </div></body>
382 </html>
Andrew's Web Libraries