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

xmldb.php Documentation

Documentation for the xmldb.php file version 2.1

Contents

Introduction

xmldb.php by Nigel Swinson / Jeremy Jones.

+================================================================================================+
| A class for the manipulation of xml databases.
|
| An xml database is a file that contains a root tag, containing a number of "table" elements.
| Each "table" element contains a series of "records" and then each record contains one or more
| "elements" which are the values for this record.  A small xml database might look something like
| this:
|
|<-?xml version="1.0"?->
|<DB>
|	<Table1 created="01 Jul 2001 01:25:48">
|		<RecordName created="01 Jul 2001 01:25:48" RecordId="1">
|			<Element1>Property1</Element1>
|			<Element2>Property2</Element2>
|		</RecordName>
|		<RecordName created="01 Jul 2001 01:25:49" RecordId="2">
|			<Element1>Property1</Element1>
|			<Element2>Property2</Element2>
|		</RecordName>
|	</Table1>
|	<Table2 created="02 Jul 2001 01:26:48">
|		<OtherRecordName created="02 Jul 2001 01:26:48" RecordId="1">
|			<ElementA>Property1</ElementA>
|			<ElementB>Property2</ElementB>
|		</OtherRecordName>
|	</Table2>
|</DB>
+------------------------------------------------------------------------------------------------+
| Copyright:
|
| xmldb.php: A Php.XPath database class that uses xml files.
|
| Copyright (C) 2001-2003 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 CXmlDb

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:
		TimeStampFlag (bool)
						Specifies if there should be a created=time attribute for
						tables and records.  Default is TRUE: timestamp on.
		XmlOptions (array)
						An array of options that is used for sending to the XPath class.
						See the XPath.class.php documentation for more detail.

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 169

Method Details: Open


public function Open($DbFileName, $bCreateDatabase = FALSE, $bNeedWriteAccess = FALSE)

Opens the database file.

Parameter:

			
string $DbFileName
The name of the file that contains the Xml database

			
bool $bCreateDatabase
If the file does not exist, then this flag describes
 									 whether or not the function should create the databse,
 									 or fail The xml database is updated by a Close() call.

			
bool $bNeedWriteAccess
Should we open this file for read/write or read/only
 									 access? Defaults to FALSE - read-only

			
Return Value:
bool
TRUE if the database was opened successfully, FALSE if failure
Line:
Defined on line 193

	 Method Details: Close

public function Close($DbFileName = '')
Closes the database by writing it out to a file.
Parameter:

			
string $DbFileName
The name of the file that the Xml database should be
 								 written to.  If empty, then the name that was supplied on
 								 Open() will be used.

			
Return Value:
bool
TRUE if the database was closed and written to successfully, TRUE if it was not necesary to close the database because no alterations were made FALSE with error if failure,
Line:
Defined on line 367

	 Method Details: GetTableNames

public function GetTableNames()
Get the table names from the db
Example: The following command might return an array as follows:
		GetTableNames();

		Array (
			[0] => TableOne,
			[1] => TableTwo,
			[2] => TableThree,
			[3] => TableFour
		)
Return Value:
array
an array of the table names within the XML file.  FALSE on error.
Line:
Defined on line 487

	 Method Details: GetRecordNames

public function GetRecordNames($TableTag)
Get the record names from a table in the db
Example: The following command might return an array as follows:
		GetRecordNames($TableTag);

		Array (
			[0] => RecordOne,
			[1] => RecordTwo,
			[2] => RecordThree,
			[3] => RecordFour
		)
Parameter:

			
string $TableTag
the second level tag that contains all the XML we are to
 							 search in

			
Return Value:
array
an array of the record names within the $TableTag.  FALSE on error.
Line:
Defined on line 552

	 Method Details: GetFieldNames

public function GetFieldNames($TableTag, $RecordTag)
Get the field names from the records of a table in the db
Parameter:

			
string $TableTag
the second level tag that contains all the XML we are to
 							  search in

			
string $RecordTag
the third level tag that contains all the XML we are to
 							  search in

			
Return Value:
array
an array of the field names within the $TableTag/$RecordTag. FALSE on failure
Line:
Defined on line 623

	 Method Details: GetSchema

public function GetSchema($TableTag, $RecordTag)
Get schema information for a given set of records in a table.
This function assists with the creation of forms for records.  You can query the maximum
length of any one field.  If it is multiline you can consider using a textarea instead
of an input control.

Note that this function may be very slow to call depending on the db implementation.
It should only be called when you need to dynamically discover information about the
schema.  Otherwise you should fix the form sizes.
Parameter:

			
string $TableTag
the second level tag that contains all the XML we are to
 							  search in

			
string $RecordTag
the third level tag that contains all the XML we are to
 							  search in

			
Return Value:
array
An associative array, indexed by field name, with data of length -> Longest data value, in characters multiline -> TRUE if any of the values contain multiple lines FALSE if no data contains a \n character. FALSE on failure.
Line:
Defined on line 707

	 Method Details: AddRecord

public function AddRecord($TableTag, $RecordTag, $aElementData)
Add a record to the database.
Add a new record of type $RecordTag to the $TableTag table with <name>value</name>
entries for each of the entries in the associate array $aElementData.

Example: The following command would open up the database.xml file, and
			add the follwing fragment of xml.
		AddRecord("Users", "User", array("Firstname" => "Nigel", "Surname" => "Swinson"));

	<XmlDataBase>
		<Users>
			<User>
				<Firstname>Nigel</FirstName>
				<Surname>Swinson</Surname>
			</User>
		</Users>
	</XmlDataBase>
Parameter:

			
string $TableTag
The second level tag that contains all the XML that we
 								 consider to represent a table.

			
string $RecordTag
The tag that represents the record within the TableTag

			
array $aElementData
an associative array of name=value pairs which constitue
 								 the data of this record

			
Return Value:
int
The record ID of the new record that was added on success 0 on failure
Line:
Defined on line 789

	 Method Details: AddUniqueRecord

public function AddUniqueRecord($TableTag, $RecordTag, $aElementData, $XPathSearch)
Add a record to the database, but only if the Search returns no records for the database.
This function provides quasi support for primary keys other than the record id.

This function is slower than AddRecord(), so you should only use it where the user will
either be a numpty, or does not have access to RemoveRecord() in order to clean up the
mistake that they have made.
Parameter:

			
string $TableTag
The second level tag that contains all the XML that we
 								 consider to represent a table.

			
string $RecordTag
The tag that represents the record within the TableTag

			
array $aElementData
an associative array of name=value pairs which constitue
 								 the data of this record.  See AddRecord() for more details.

			
string $XPathSearch
The unique search criteria.  If a record exists that
 								 matches this search, then the new record will not be added.
 								 The context will select all the records, and this value
 								 refines the search further. A typical XPathSearch might be
 								 "contains(FieldName,'substring')" or "*".

			
Return Value:
int
The record ID of the new record that was added on success 0 on failure, or if it wasn't added as a record already existed matching the XPathUniqueCriteria
Line:
Defined on line 870

	 Method Details: ModifyRecord

public function ModifyRecord($TableTag, $RecordTag, $RecordId, $aElementData, $bPreserveContent = FALSE)
Modify a record in the the database.
Modify a record by rewriting the contents of the record.  Keeping the original
record XML tags and RecordId means that the record keeps it's place in the file

Example: The following command would open up the database.xml file, and
			add the follwing fragment of xml.
		ModifyRecord("database.xml", "Users", "User", "1",
			array("Firstname" => "Jeremy", "Surname" => "Jones"));

regardless of the record's content previously, it would only have 2 fields after this call

After modification:
	<XmlDataBase>
		<Users>
			<User RecordId="1">
				<Firstname>Jeremy</FirstName>
				<Surname>Jones</Surname>
			</User>
		</Users>
	</XmlDataBase>
Parameter:

			
string $TableTag
The second level tag that contains all the XML that we
 									  consider to represent a table.

			
string $RecordTag
The tag that represents the record within the TableTag

			
string $RecordId
the RecordId of the record

			
array $aElementData
an associative array of name=value pairs which
 									  constitue the data of this record.

			
boolean $bPreserveContent
A flag which specifies whether record data is removed
 									  or not.  If the flag is FALSE (default), all data is
 									  removed from the record and replaced with the
 									  $aElementData. If it is TRUE, the data in the record
 									  is kept and overwritten if needbe.

			
Return Value:
bool
TRUE if the record was modified, FALSE if failure
Line:
Defined on line 986

	 Method Details: RemoveRecord

public function RemoveRecord($TableTag, $RecordTag, $XPathSearch)
Remove a record from the database.
Remove the record(s) which match the XPath expression which is passed to the funciton.
If a node to be deleted has contents or children these are deleted also.

Example: The following command would open up the database.xml file, and
			remove the following node.
		RemoveRecord("Users", "User", "contains(Firstname,'Nigel')");

	<XmlDataBase>
		<Users>
			<User>							// this node and contents would be removed
				<Firstname>Nigel</FirstName>
				<Surname>Swinson</Surname>
			</User>
		</Users>
	</XmlDataBase>
Parameter:

			
string $TableTag
The second level tag that contains all the XML that we
 								 consider to represent a table.

			
string $RecordTag
The tag that represents the record within the TableTag

			
string $XPathSearch
The unique search criteria.  If a record exists that
 								 matches this search, then the new record will not be
 								 added.  The context will select all the records, and this
 								 value refines the search further.  A typical XPathSearch
 								 might be "contains(FieldName,'substring')" or "*".

			
Return Value:
bool
TRUE/FALSE value describing the result of attempted removal
Line:
Defined on line 1097

	 Method Details: RemoveRecordId

public function RemoveRecordId($TableTag, $RecordTag, $aRecordIds)
Remove records from the database that are specified by their RecordIds
Remove the record(s) which are described by an array of RecordIds
If a node to be deleted has contents or children these are deleted also.

Example: The following command would open up the database.xml file, and
			remove the following node.
		RemoveRecord("Users", "User", array ("101", "102"));

	<XmlDataBase>
		<Users>
			<User RecordId="101">			 // this node and contents would be removed
				<Firstname>Nigel</FirstName>
				<Surname>Swinson</Surname>
			</User>
			<User RecordId="102">			 // this node and contents would also be removed
				<Firstname>Nigel</FirstName>
				<Surname>Swinson</Surname>
			</User>
		</Users>
	</XmlDataBase>
Parameter:

			
string $TableTag
The second level tag that contains all the XML that we
 								 consider to represent a table.

			
string $RecordTag
The tag that represents the record within the TableTag

			
array $aRecordIds
an array of RecordIds

			
Return Value:
bool
TRUE/FALSE value describing the result of attempted removal
Line:
Defined on line 1193

public function Search($TableTag, $RecordTag, $XPathSearch)
Search a database and return an array of associative arrays of element=content data
Parameter:

			
string $TableTag
The second level tag that contains all the XML that we
 								 consider to represent a table.

			
string $RecordTag
The tag that represents the record within the TableTag

			
string $XPathSearch
The unique search criteria.  If a record exists that
 								 matches this search, then the new record will not be
 								 added.  The context will select all the records, and this
 								 value refines the search further. A typical XPathSearch
 								 might be "contains(FieldName,'substring')" or "*".

			
Return Value:
array
Associative  array with entries at record ids for each matching record found. Each entry itself will be an associative array of name=value pairs where the key is the element name and the value is the element content.  An empty array if no records are found.  FALSE on error.
Line:
Defined on line 1327

	 Method Details: SortSearch

public function SortSearch($aSearchResults, $SortByKey = 0, $bReverseSortOrder = FALSE)
Sort an array of data which has been generated by the Search() function
Parameter:

			
array $aSearchResults
The array of data to be searched.

			
string $SortByKey
The key by which the search of the array will be driven.
 									 the key must be a second dimention key ie.
 									 $array[first][second] Default is set to 0

			
bool $ReverseSortOrder
Defines the order in which the array is sorted.  The
 									 default value of TRUE sorts the array in ascending
 									 order.  FALSE will cause the array to be sorted in
 									 reverse order.

			
Return Value:
array
Associative array of sorted data where a record key will be it's RecordId and the content will be the record data.  FALSE on error
Line:
Defined on line 1391

	 Method Details: Display

public function Display($aSearchResults, $FunctionName, $aFunctionParameters, $bTestFlag = FALSE)
Display search results through a series of Javascript function calls.
Using a previously generated array of data, output a selection of javascript blocks
containing a list of javacript function calls.
Parameter:

			
array $aSearchResults
an array of search results of which a portion is
 										 to be displayed.  Use the Search function to search
 										 the XML file and produce an array of specific data
 										 and then use the $aFunctionParameters parameter
 										 to define the subset of data that you want to
 										 display.

			
string $FunctionName
the name of the function that we are going to call
 										 for each matching record found

			
array $aFunctionParameters
an array of property names that represent the
 										 argument list for the $FunctionName function.
 										 $FunctionName will be called with exactly this
 										 many arguments, and where an element exists in
 										 the record that matches the name of the parameter,
 										 then it's text value will be used.  Where no
 										 element exists "" will be passed as the parameter
 										 instead.

			
boolean $bTestFlag
a boolean which when set to true, outputs, not
 										 to the standard output, but to a string which can
 										 be used in the test harness to test the integrity
 										 of the function

			
Return Value:
mixed
the number of entries that were displayed. FALSE is no entries exist.  If $bTestFlag is TRUE, then it will contain the string of the displayed text.
Line:
Defined on line 1525

	 Method Details: SearchAndDisplay

public function SearchAndDisplay($TableTag, $RecordTag, $XPathSearch, $FunctionName, $aFunctionParameters)
Search a database and output javascript blocks containing a list of javacript function calls.
Equivalent to calling Search() and passing the results into Display()
Parameter:

			
string $TableTag
The second level tag that contains all the XML that we
 										 consider to represent a table.

			
string $RecordTag
The tag that represents the record within the TableTag

			
string $XPathSearch
The unique search criteria.  If a record exists
 										 that matches this search, then the new record
 										 will not be added.  The context will select all
 										 the records, and this value refines the search
 										 further.  A typical XPathSearch might be
 										 "contains(FieldName,'substring')" or "*".

			
string $FunctionName
the name of the function that we are going to call
 										 for each matching record found

			
array $aFunctionParameters
an array of property names that represent the
 										 argument list for the $FunctionName function.
 										 $FunctionName will be called with exactly this
 										 many arguments, and where an element exists in
 										 the record that matches the name of the parameter,
 										 then it's text value will be used.  Where no element
 										 exists "" will be passed as the parameter instead.

			
Return Value:
int
the number of entries that were displayed.
Line:
Defined on line 1670
Private Method Detail

	 Method Details: __construct

public function __construct()
Constructor
Initialises the Debug Object
Line:
Defined on line 141

	 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 1704

	 Method Details: _OpenScriptTag

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

	 Method Details: _CloseScriptTag

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

	 Method Details: _GetDbTime

private function _GetDbTime()
Returns the date and time for storage as a element or attribute in the xml document.
Line:
Defined on line 1758

	 Method Details: _LockFile

protected function _LockFile($Action = TRUE)
Maintains the lock status of the files
Parameter:

			
bool $Action
TRUE (default) locks the file, FALSE unlocks it

			
Return Value:
bool
FALSE if the operation failed.
Line:
Defined on line 1769

	 Method Details: _FindTable

private function _FindTable($TableTag, $bCreateTable = FALSE)
Finds the table of XmlDb corresponding to TableTag and returns it's complete XPath address.
Parameter:

			
string $TableTag
The name of the table we are trying to locate

			
bool $bCreateTable
If TRUE, the table will be created if it doesn't exist.

			
Return Value:
string
The absolute XPath address to the table
Line:
Defined on line 1846

	 Method Details: _SetRecordIds

private function _SetRecordIds($TablePath)
Set all the record ids in the given table to unique values
Ensure that the record ids increase in value in the order they appear in the xml file.
Parameter:

			
string $TablePath
The absolute XPath address of the table we are querying

			
Return Value:
int
The largest record ID in the file
Line:
Defined on line 1958

	 Method Details: _GetRecordId

private function _GetRecordId($TablePath, $RecordPath)
Obtain the record id for a record specified by it's XPath addresss.
It will regenerate the record ids if necessary.
Parameter:

			
string $TablePath
The absolute XPath address of the table we are querying

			
string $RecordPath
The absolute XPath address of the record whose ID we want

			
Return Value:
int
The record ID
Line:
Defined on line 2016

	 Method Details: _GetNewRecordId

private function _GetNewRecordId($TablePath)
Obtain a new record id for the specified table
Parameter:

			
string $TablePath
The absolute XPath address of the table we are querying

			
Return Value:
int
A new record ID
Line:
Defined on line 2074

	 Method Details: _CheckRecordId

private function _CheckRecordId($TableTag, $RecordTag, $RecordId)
Check to see if a particular recordId is taken.
Parameter:

			
string $TableTag
The name of the table we are interested in

			
string $RecordTag
The name of the records we are interested in

			
int $RecordId
The recordID we would like to use

			
Return Value:
int
A valid record ID for the database, either $RecordID if it isn't already taken, else a new record Id.
Line:
Defined on line 2128

	 Method Details: _IsValidFieldName

private function _IsValidFieldName($Name)
Determine if a given name is suitable for using as a field name
Parameter:

			
string $Name
The name of the field we are querying

			
Return Value:
bool
TRUE if the name was valid.  Else FALSE
Line:
Defined on line 2198

	 Method Details: _CheckFieldNames

private function _CheckFieldNames($aElementData)
Check if all the field names of a proposed element are valid
Parameter:

			
array $Name
The proposed element data

			
Return Value:
bool
TRUE if the names were valid.  Else FALSE
Line:
Defined on line 2208

	 Method Details: _AddRecord

private function _AddRecord($TableTag, $RecordTag, $aElementData)
Internal version of AddRecord.
Parameter:

			
string $TableTag
The name of the table we are adding to

			
string $RecordTag
The name of the records we are adding to

			
array $aElementData
Associative array of element data to set.

			
Return Value:
int
The record ID of the new record that was added on success 0 on failure
Line:
Defined on line 2236

	 Method Details: _ModifyRecord

private function _ModifyRecord($TableTag, $RecordTag, $RecordId, $aElementData, $bPreserveContent)
Internal version of Modify Record.
The contents of the record are removed and replaced with the name => value pairs held in
the $aElementData array.
Parameter:

			
string $TableTag
The name of the table containing our target

			
string $RecordTag
The name of the records containing our target

			
int $RecordId
The ID of the record we are modifying

			
array $aElementData
Associative array of element data to modify to

			
bool $bPreserveContent
If FALSE, all existing data in the record will be
 									 deleted.  If TRUE, existing data will be kept, and any
 									 records overwritten as necessary.

			
Return Value:
bool
TRUE on success, FALSE on failure.
Line:
Defined on line 2378

	 Method Details: _RemoveRecord

private function _RemoveRecord($aXPathAddresses)
Internal version of RemoveRecord.
Locates the XPath address within the file which match those in the array passed to it
and removes them.
Parameter:

			
array $aXPathAddresses
An array of XPath addresses to remove

			
Return Value:
bool
TRUE on success, FALSE on error.
Line:
Defined on line 2500

	 Method Details: _Search

private function _Search($TableTag, $RecordTag, $XPathSearch)
Internal version of Search.
Parameter:

			
string $TableTag
The name of the table to search

			
string $RecordTag
The name of the records to search

			
string $XPathSearch
The search string, an XPath predicate

			
Return Value:
array
An associative array where the key is the record ID, and the value is an associative array of name = value pairs containing the data of the record.
Line:
Defined on line 2579
Class CTestXmlDb
The CTestXmlDb class extends the 
		CXmlDb
		class.
Public Methods
Public Method Detail

	 Method Details: LockFile

public function LockFile($Action = true)
Maintains the lock status of the files.
Testing needs to unlock files without closing.
Parameter:

			
bool $Action
TRUE (default) locks the file, FALSE unlocks it

			
Return Value:
bool
FALSE if the operation failed.
Line:
Defined on line 2701

		
		

	

		
		
	
		

		
		

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

		
			© 2008 Carrubbers Christian Centre | Registered Charity No. SC011455

			Conditions of Use |
			Privacy Policy