scripts.carrubbers.org home scripts@carrubbers.org
ExplorerIndex phpBanners PhpiCalLib PhpXDb Php.XPath SCMS
*

PhpPgDb Documentation

Documentation for the pgdb.php file version 2.1

Contents

Introduction

PhpPgDb by J.Jones / N.Swinson.

+======================================================================================================+
| A class for manipulation of Postgres databases.
|
| It is based on the PhpXmlDb class and offers a way in which to use the same
| public interface for larger databases that would be too large to be handled
| efficiently by PhpXmlDb.
|
+-----------------------------------------------------------------------------------------------+
| Copyright:
|
| pgdb.php: An abstraction of an xdb conforming to the PhpXmlDb interface
|
| Copyright (C) 2001-2003 Jeremy Jones, jbjones@users.sourceforge.net
|			   2006 Nigel Swinson nigelswinson@users.sourceforge.net
|
| This program is free software; you can redistribute it and/or
| modify it under the terms of the GNU General Public License
| as published by the Free Software Foundation; either version 2
| of the License, or (at your option) any later version.
|
| This program is distributed in the hope that it will be useful,
| but WITHOUT ANY WARRANTY; without even the implied warranty of
| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	See the
| GNU General Public License for more details.
|
| You should have received a copy of the GNU General Public License
| along with this program; if not, write to the Free Software
| Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA	02111-1307, USA.
|
+======================================================================================================+

Class CPgDb

Public Methods

Private Methods

You really shouldn't be raking about in these functions, as you should only be using the public interface. But if you need more control, then these are the internal functions that you can use if you want to get your hands really dirty.

Public Method Detail

Method Details: SetOptions


public function SetOptions($aOptions)

Sets options that affect behaviour

Possible options are:
		TestSchema (bool) - Run more extensive db checks in Open()

Parameter:

array $aOptions

Array of name = value options to set for the class. If the value is unset then the option will be unset.

Return Value:

bool

FALSE if one of the options couldn't be set. TRUE otherwise.

Line:

Defined on line 287

Method Details: Open


public function Open($DbName, $bCreateDatabase = NULL, $bNeedWriteAccess = NULL)

Opens the database file.

Unlike its siblings, PgDb does not create an empty database if one does not exist
Write access is granted automatically, read only access is not supported
### Support read only access

Similar Functions:

PhpXDb documentation

Line:

Defined on line 307

Method Details: Close


public function Close($DbName = NULL)

Closes the database.

Similar Functions:
PhpXDb documentation
Line:
Defined on line 383

	 Method Details: GetGroupNames

public function GetGroupNames()
Get the group names from the db
In this instance, the group name refers to the schema.
Similar Functions:
PhpXDb documentation
Line:
Defined on line 414

	 Method Details: GetSubGroupNames

public function GetSubGroupNames($GroupTag = NULL)
Get the subgroup names from a group in the db
The SubGroups in PgDb include both tables and views.
Similar Functions:
PhpXDb documentation
Line:
Defined on line 461

	 Method Details: GetFieldNames

public function GetFieldNames($GroupTag = NULL, $SubGroupTag = NULL)
Get the field names from the subgroups of a group in the db
Similar Functions:
PhpXDb documentation
Line:
Defined on line 515

	 Method Details: GetSchema

public function GetSchema($GroupTag, $SubGroupTag)
Get schema information from the db.
Overridden to use SQL calls to efficiently establish column data types an sizes
Line:
Defined on line 596

	 Method Details: AddRecord

public function AddRecord($GroupTag, $SubGroupTag, $aElementData)
Add a Record to the database.
Similar Functions:
PhpXDb documentation
Line:
Defined on line 691

	 Method Details: AddUniqueRecord

public function AddUniqueRecord($GroupTag, $SubGroupTag, $aElementData, $XPathSearch)
Add a subgroup to the database, but only if the Search returns no subgroups for the database.
Similar Functions:
PhpXDb documentation
Line:
Defined on line 730

	 Method Details: ModifyRecord

public function ModifyRecord($GroupTag, $SubGroupTag, $RecordId, $aElementData, $bPreserveContent = FALSE)
Modify a subgroup in the the database.
Similar Functions:
PhpXDb documentation
Line:
Defined on line 794

	 Method Details: RemoveRecord

public function RemoveRecord($GroupTag, $SubGroupTag, $XPathSearch)
Remove a record from the database.
Similar Functions:
PhpXDb documentation
Line:
Defined on line 919

	 Method Details: RemoveRecordId

public function RemoveRecordId($GroupTag, $SubGroupTag, $aRecordIds)
Remove subgroups from the database that are specified by their RecordIds
Similar Functions:
PhpXDb documentation
Line:
Defined on line 1001

public function Search($GroupTag, $SubGroupTag, $XPathSearch)
Search a database and return an array of associative arrays of element=content data
Similar Functions:
PhpXDb documentation
Line:
Defined on line 1091

	 Method Details: SortSearch

public function SortSearch($aArrayForSorting, $SortByKey = 0, $bReverseSortOrder = FALSE)
Sort an array of data which has been generated by the Search() function
This is the same function as in dbasedb and xmldb.
DEPRECIATED: Use SearchAndSort() for a more efficient sort.
Similar Functions:
PhpXDb documentation
Line:
Defined on line 1108

	 Method Details: SearchAndSort

public function SearchAndSort($GroupTag, $SubGroupTag, $XPathSearch, $SortByKey = NULL, $bReverseSortOrder = FALSE)
Search a database and return a sorted array of associative arrays of element=content data
Similar Functions:
PhpXDb documentation
Line:
Defined on line 1203

	 Method Details: Display

public function Display($aSearchResults, $FunctionName, $aFunctionParameters, $bTestFlag = FALSE)
Display search results through a series of Javascript function calls.
Similar Functions:
PhpXDb documentation
Line:
Defined on line 1240

	 Method Details: SearchAndDisplay

public function SearchAndDisplay($GroupTag, $SubGroupTag, $XPathSearch, $FunctionName, $aFunctionParameters)
Search a Database and output javascript blocks containing a list of javacript function calls.
Similar Functions:
PhpXDb documentation
Line:
Defined on line 1352

	 Method Details: SQLQuery

public function SQLQuery($SQL = NULL)
Perform a query on the db.	No extra work is performed - the query is 
executed and the result returned.	If the result is an array, it is
formatted for return.

Note the caller is therefore responsible for making sure it asks to execute a secure query
Return Value:
mixed
Associative array of RecordId => Record of search results where the Record is an associative of name => value pairs
Line:
Defined on line 1379

	 Method Details: TestDatabase

public function TestDatabase()
Function to test whether the database consists of the minimum criteria for pgdb.
There needs to be a schema with a table with fields and a RecordId field.
If one schema passes, there may be other schema with non-pgdb data and other tables without Ids.
Line:
Defined on line 1460

	 Method Details: GetTableNames

public function GetTableNames()
These exist to bridge the gap between xmldb and dbasedb.	In these classes, the methods
GetTableNames() and GetRecordNames() existed.	They have been replaced with GetGroupNames() 
and GetSubGroupNames().
/
Line:
Defined on line 2599

	 Method Details: GetRecordNames

public function GetRecordNames($GroupTag)
These exist to bridge the gap between xmldb and dbasedb.	In these classes, the methods
GetTableNames() and GetRecordNames() existed.	They have been replaced with GetGroupNames() 
and GetSubGroupNames().
/
Line:
Defined on line 2603
Private Method Detail

	 Method Details: _GetFullTableName

private function _GetFullTableName()
The full table name, with appropriate quoting to make them SQL safe
Line:
Defined on line 203

	 Method Details: __construct

public function __construct()
Constructor
Line:
Defined on line 262

	 Method Details: _CheckTestDatabase

private function _CheckTestDatabase()
Check the database and schema are ok and trigger_error if they are not
Return Value:
bool
false if the check fails, else true.
Line:
Defined on line 1498

	 Method Details: _CheckGroup

private function _CheckGroup($GroupTag)
Check the group tag is ok
Parameter:

			
string 
$GroupTag

			
Return Value:
bool
false if the check fails, else true
Line:
Defined on line 1512

	 Method Details: _CheckSubGroup

private function _CheckSubGroup($SubGroupTag)
Check the group and subgroup tag is ok
Parameter:

			
string 
$SubGroupTag

			
Return Value:
bool
false if the check fails, else true
Line:
Defined on line 1528

	 Method Details: _CheckGroupAndSubGroup

private function _CheckGroupAndSubGroup($GroupTag, $SubGroupTag)
Check the group and subgroup tags are ok
Parameter:

			
string 
$GroupTag

			
string 
$SubGroupTag

			
Return Value:
bool
false if the check fails, else true
Line:
Defined on line 1545

	 Method Details: _FunctionPermitted

private function _FunctionPermitted($MethodName)
Determine if we have permissions to execute a method.
The call will look in the $aPermissions array and also if necessary at the bSecureMode
flag to detmine if the user has the permissions to execute the query.	This function will
trigger_error() if the permission is not granted.
Parameter:

			
string $MethodName
The name of the method that the user is calling

			
Return Value:
bool
TRUE if the user has permissions to run the query, FALSE otherwise.
Line:
Defined on line 1561

	 Method Details: _OpenScriptTag

private function _OpenScriptTag()
Simple helper to draw an open <SCRIPT> block
Line:
Defined on line 1591

	 Method Details: _CloseScriptTag

private function _CloseScriptTag()
Simple helper to draw a close </SCRIPT> block
Line:
Defined on line 1602

	 Method Details: _ExecuteSQL

private function _ExecuteSQL($PgQuery, $Column, $bDebugFlag = FALSE)
Helper function for executing an SQL function and returning the data.
Parameter:

			
 
string		$PgQuery		The sql to execute

			
 
string		$Column			The name of the column we are interested in.

			
 
bool		$bDebugFlag		Debug Flag

			
Return Value:
array
Line:
Defined on line 1618

	 Method Details: _CheckRecordId

private function _CheckRecordId($GroupTag, $SubGroupTag)
Check the record id exists
Tests whether the specified schema and table has a RecordId.

A PRIMARY KEY record id is required for a pgdb and its form is clarified in the 
internal member
Return Value:
bool
false if the check fails, else true
Line:
Defined on line 1632

	 Method Details: _GetLastRecordId

private function _GetLastRecordId($GroupTag, $SubGroupTag, $RecordIdTag)
Gets the last RecordId from the sequence that generates the id.
## This will only work when adding to tables, not views.
Line:
Defined on line 1651

	 Method Details: _AddRecord

private function _AddRecord($aElementData, $RecordID = NULL)
Internal method for adding subgroups to the object
Parameter:

			
array $aElementData
Associative array of name => value pairs constituting data

			
int $RecordID
We NEVER specify this in pgdb.

			
Return Value:
int
0 if addition failed, else the RecordId of the new subgroup in the db
Line:
Defined on line 1718

	 Method Details: _Search

private function _Search($XPathSearch, $SortByKey = 0, $bReverseSortOrder = FALSE)
Internal method that will evaluate searches using XPath searches.
Ensure that we give the opportunity to sort the search.
Parameter:

			
string $XPathSearch
Definition of the search as valid XPath predicate.
 					Or starts with WHERE and is a query we pass in untouched.
 					### Warning, there is a risk of SQL injection attack here!!

			
Return Value:
array
Associative array of RecordId => Record of search results where the Record is an associative of name => value pairs
Line:
Defined on line 1826

	 Method Details: _XPath2SQL

protected function _XPath2SQL($XPathSearch)
Internal method that converts XPath to SQL
Because we are migrating from xmldb and dbasedb where we use XPath
to evaluate our searches, we need to have a method that transforms
XPath searches to SQL and then evaluates them.

At present it only copes with 'true()', 'contains()' and '='
Parameter:

			
string $XPathSearch
The XPath Search

			
Return Value:
string
The	equivalent SQL or FALSE if no SQL could be generated.
Line:
Defined on line 1884

	 Method Details: _evaluateExpr

private function _evaluateExpr($xPathQuery)
Convert an Expr XPath token to SQL
http://www.w3.org/TR/xpath#section-Basics

[14]    Expr               ::= OrExpr 
[21]    OrExpr             ::= AndExpr  
                               | OrExpr 'or' AndExpr  
[22]    AndExpr            ::= EqualityExpr  
                               | AndExpr 'and' EqualityExpr  
[23]    EqualityExpr       ::= RelationalExpr  
                               | EqualityExpr '=' RelationalExpr  
                               | EqualityExpr '!=' RelationalExpr  
[24]    RelationalExpr     ::= AdditiveExpr  
                               | RelationalExpr '<' AdditiveExpr  
                               | RelationalExpr '>' AdditiveExpr  
                               | RelationalExpr '<=' AdditiveExpr  
                               | RelationalExpr '>=' AdditiveExpr  
[25]    AdditiveExpr       ::= MultiplicativeExpr  
                               | AdditiveExpr '+' MultiplicativeExpr  
                               | AdditiveExpr '-' MultiplicativeExpr  
[26]    MultiplicativeExpr ::= UnaryExpr  
                               | MultiplicativeExpr MultiplyOperator UnaryExpr  
                               | MultiplicativeExpr 'div' UnaryExpr  
                               | MultiplicativeExpr 'mod' UnaryExpr  
[27]    UnaryExpr          ::= UnionExpr  
                               | '-' UnaryExpr 
[18]    UnionExpr          ::= PathExpr  
                               | UnionExpr '|' PathExpr 

For our purposes, a PathExpr is a PrimaryExpr, and we ommit the PathExpr, as we 
aren't really doing the XPath steps bits

NOTE: The effect of the above grammar is that the order of precedence is 
(lowest precedence first): 
1) or 
2) and 
3) =, != 
4) <=, <, >=, > 
5) +, -
6) *, div, mod
7) - (negate)
8) |
Parameter:

			
string 
$xPathQuery A Expr

			
Return Value:
mixed
false or error, or a string of SQL on success
Line:
Defined on line 1969

	 Method Details: _evaluatePrimaryExpr

private function _evaluatePrimaryExpr($xPathQuery)
Convert a PrimaryExpr XPath token to SQL
http://www.w3.org/TR/xpath#section-Basics

 [15]    PrimaryExpr    ::= VariableReference  
                            | '(' Expr ')'  
                            | Literal  
                            | Number  
                            | FunctionCall 
Parameter:

			
string 
$xPathExpr a PrimaryExpr

			
Return Value:
mixed
false or error, or a string of SQL on success
Line:
Defined on line 2045

	 Method Details: _bracketsCheck

private function _bracketsCheck($term)
This method checks the right amount and match of brackets
Parameter:

			
string $term
String in which is checked.

			
Return Value:
bool
TRUE: OK / FALSE: KO  
Line:
Defined on line 2155

	 Method Details: _evaluateFunction

private function _evaluateFunction($function, $arguments)
Evaluates an XPath function
This method evaluates a given XPath function with its arguments on a
specific node of the document.
Parameter:

			
string $function
Name of the function to be evaluated.

			
string $arguments
String containing the arguments being
                                 passed to the function.

			
array $context
The context from which to evaluate

			
Return Value:
mixed
This method returns the result of the evaluation of the function. Depending on the function the type of the  return value can be different.
Similar Functions:
evaluate()
Line:
Defined on line 2214

	 Method Details: _prestr

private function _prestr(&$string, $delimiter, $offset=0)
Retrieves a substring before a delimiter.
This method retrieves everything from a string before a given delimiter,
not including the delimiter.
Parameter:

			
string $string
String, from which the substring should be extracted.

			
string $delimiter
String containing the delimiter to use.

			
Return Value:
string
Substring from the original string before the delimiter.
Similar Functions:
_afterstr()
Line:
Defined on line 2267

	 Method Details: _afterstr

private function _afterstr($string, $delimiter, $offset=0)
Retrieves a substring after a delimiter.
This method retrieves everything from a string after a given delimiter,
not including the delimiter.
Parameter:

			
string $string
String, from which the substring should be extracted.

			
string $delimiter
String containing the delimiter to use.

			
Return Value:
string
Substring from the original string after the delimiter.
Similar Functions:
_prestr()
Line:
Defined on line 2285

	 Method Details: _handleFunction_contains

private function _handleFunction_contains($arguments)
Handles the XPath function contains.
Parameter:

			
string $arguments
String containing the arguments that were passed to the function.

			
Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 2298

	 Method Details: _SQLSearch

private function _SQLSearch($PgQuery)
Internal method for performing an SQL search.
Return Value:
array
Associative array of RecordId => Record of search results where the Record is an associative of name => value pairs
Line:
Defined on line 2355

	 Method Details: _GetOperator

private function _GetOperator($xPathQuery)
Look for operators in the expression
Parses through the given expression looking for operators.	If found returns
the operands and the operator in the resulting array.
Parameter:

			
string $xPathQuery
XPath query to be evaluated.

			
Return Value:
array
If an operator is found, it returns an array containing information about the operator.	If no operator is found then it returns an empty array.	If an operator is found, but has invalid operands, it returns FALSE. The resulting array has the following entries: 'operator' => The string version of operator that was found, trimmed for whitespace 'left operand' => The left operand, or empty if there was no left operand for this operator. 'right operand' => The right operand, or empty if there was no right operand for this operator.
Line:
Defined on line 2412

	 Method Details: _searchString

private function _searchString($term, $expression)
Looks for a string within another string -- BUT the search-string must be located *outside* of any brackets, and outwith a string
This method looks for a string within another string. Brackets in the
string the method is looking through will be respected, which means that
only if the string the method is looking for is located outside of
brackets, the search will be successful.
Parameter:

			
string $term
String in which the search shall take place.

			
string $expression
String that should be searched.

			
Return Value:
int
This method returns -1 if no string was found,  otherwise the offset at which the string was found.
Line:
Defined on line 2553
Class CPgDbTest
The CPgDbTest class extends the 
		CPgDb
		class.
Public Methods
Public Method Detail

	 Method Details: XPath2SQL

function XPath2SQL($XPathSearch)
These exist to bridge the gap between xmldb and dbasedb.	In these classes, the methods
GetTableNames() and GetRecordNames() existed.	They have been replaced with GetGroupNames() 
and GetSubGroupNames().
/
Line:
Defined on line 2609

		
		

	

		
		
	
		

		
		

			Last updated: 17 April 2008 02:15:13.		

		
			© 2008 Carrubbers Christian Centre | Registered Charity No. SC011455

			Conditions of Use |
			Privacy Policy