C:/usr/local/lib/php/blueshoes-4.2/core/db/Bs_Db.class.phpandrej arnabstract class Bs_Db.class.phpThis object is the abstract layer for Db access. It holds the basicfuctions that are DB-independent.To makes use of this object, you must extend it to a DB-specific objectlike Bs_MySql.class.php.Some collected knowledge:-------------------------o) Watch out when you make queries based on variables from a surfer."SELECT * FROM table where ID=$ID" can easily be hacked to empty your table. Parse allvariables submitted through forms/get if they are to be used in any similar situation.Of course, the hacker would need to know the name of your table.o) In some dbms like MS-ACCESS and mssql (if you call them dbms :) can have field names withspaces. A query would look like this "SELECT [fieldname withspace], anotherField FROM tbl".Please *NEVER* ever use that 'feature'. Many dbms don't support it (like mySQL); it's uglyand screams for probs.dependencies: Bs_System, Bs_Date**********************************************************************4.0.$Revision: 1.1.1.1 $blueshoesandrej arn <andrej at blueshoes dot org>samuel blume <sam at blueshoes dot org>(a hash, see Bs_Form->dbDsn for a description)(instance of a subclassed db class)bs_exceptionnote: this is a function, not a method of a db object.if $dsn is not given or set to null, a reference to the global shared db objectwill be returned. if it does not exist, this function tries to open the connectionfor it.example:$dsn = array('host'=>'localhost', 'port'=>3306, 'user'=>'foo', 'pass'=>'bar', 'syntax'=>'mysql', 'type'=>'mysql');$db = &getDbObject($dsn);^^ important!!!^function to get a db object for a given dsn.blueshoes.orgconstructor.if specified then only the value for the given key will be returned. (&hash return the _dsnInfo-hash or mixed, depending on param $key.)Return the _dsnInfo-hash.whether this DB implementation supports $feature (or NULL if $feature not known).currently, these features are reported (see constructor of subclassing class, like Bs_MySql)'prepare', 'pconnect', 'transactions', 'innerSelects', 'insertId', 'affectedRows','numRows', 'numCols'Tell whether a DB implementation or its backend extension supports a given feature.(opt) Default TRUE. If TRUE, a limit x,y in the given query is ignored.the number of recordsBs_ExceptionExample: You want to display page 5 of your search engine with 10 results (per page).So your query would look like this: "select * from searchEngine limit 40,10".But at the same time, you want to show the user how many records really *were*found. The numRows() for the above query will only show you 10...Caution: Never fire a delete statement to this method. This is for select queries only.If you do and it has a 'limit' clause and $ignoreLimit is set to true, thelimit will be ignored...NOTE: This method is *not* optimized. It should not be used with queries thatreturn a large amound of data. Your query is executed in real, and thenumRows() is returned.Returns the number of records that get selected for a given query.The db-table to search. Can also be 'database.table'.The field to compare.The value to compare.The field name as string of which we want the value, or an array with field names.(opt) if the compare in the db should be made case sensitive or no. default is TRUE.The desired field value, whatever that is. If param $fieldToGet is an array, an array is returned here.bs_exceptionExample I:$birthday = getFieldValue($theTable='employees', $fieldToSearch='username', $valueToSearch='Hugentobler', $fieldToGet='birthday')Example II:list($birthday, $phone) = getFieldValue('employees', 'username', 'Hugentobler', array('birthday', 'phone'))NOTE: Only the first found record is used.Returns 1-n db-field values.countRead()A read only SQL statement.Bs_ExceptionIssue a select query and return a resource (or statement for oci).read()countRead()A read only SQL statement.instance of Bs_ResultSetBs_ExceptionIssue a select query and return an instance of Bs_ResultSet.read()A SQL statement.number of rows matched (0-x)Bs_ExceptionThis method makes use of this->numRows().Issue a select query and return the number of 'affected' rows.countWrite()idWrite()A modifing SQL statement.true on success, otherwise throws an exception.Bs_ExceptionIssue a write query (insert, update, delete, replace, drop, alter, create).(write query like insert, update, delete ...) (the modified or unmodified query)overwrite this method if needed.write()idWrite()affectedRows()A modifing SQL statement.number of rows affectedBs_Exception if the query was unsuccessfulFALSE if the count with affectedRows() failed.this method makes use of this->affectedRows() read the doc of it!Issue a write query (update, delete, replace) and return the number of affected rows.countWrite()write()insertId()A SQL statement that inserts a record. >=1Bs_Exception if the query failedFALSE if the operation was not an insert.this method makes use of this->insertId() read the doc of it!Issue an insert query on a table with an auto_increment field and return the newly inserted id.can be an SQL query as string, or a result set (a resource).the row numberwhich column to return (integer [column number, starting at 0] or string [column name])just one value or NULL if row or col are out of bounds or don't exsist.Bs_Exception on error$source can be either a SQL query string or a result set.IF param $source is a query-string:Execute the query, fetch value and clean up (free the results set).ELSEIF param $source is a result set:Move down $row-rows, fetch value at $col and leave DB curser*after* offset rows. Don't free result set.A row and col offset can be given. Top left cell is row=0 / col=0.The default behavior is to fetch cell [0,0] (top left cell).NOTE: col may be given as col-name (string) instead of offset (int). It will beused as key to identify the right column. So pass the right type!Sample: Given is the table "mytable" containing:\/ID TEXT DATE--------------------------------> 1 'one' 09.05.19602 'two' 25.12.19703 'three' 31.01.1980getOne('SELECT id, teXt, date as birthday FROM mytable'); // would return '1'.getOne($query, 1, 2); // would return '25.12.1970'.getOne($query, 2, 'teXt'); // would return 'two'.Fetch a single value from a data amount given by the param $source.can be an SQL query string, or a resource.IF >=0 will move internal row pointer to abs. position befor fetching the data. Default is -1.(opt) (default BS_DB_FETCHMODE_ASSOC) see above.vector , hash. NULL if row offest is out of bounds OR no data found.Bs_Exception on error$source can be either a SQL query string or a result set.If fetchMode is BS_DB_FETCHMODE_ASSOC (default) returns a hash array that correspondsto the fetched row else if it's BS_DB_FETCHMODE_ORDERED returns a vector starting at offset 0.IF param $source is a query-string:Execute the query, fetch row and clean up (free the results set).ELSEIF param $source is a result set:Move down $row-rows, fetch row and leave DB curser*after* offset rows. Don't free result set.The default behaver is to fetch current row.Sample: Given is the table "mytable" containing:ID TEXT DATE--------------------------------> 1 'one' 09.05.1960 <-2 'two' 25.12.19703 'three' 31.01.1980getRow('SELECT id, teXt, date as birthday FROM mydate'); // would return array('id' => '1','teXt' => 'one','birthday' => '09.05.1960');Fetch a full row of data as vector or hash given by the param $source.can be an SQL query string, or a resource.which column to return (integer [column number, starting at 0] or string [column name])the row number at which we start, *including* that row. default is 0.the row number at which we stop, *including* that row. default is -1 which means loop until the end.Bs_Exception on errorIF param $source is a query-string:Execute the query, fetch col and clean up (free the results set).ELSEIF param $source is a result set:Move down $row-rows, fetch col and leave DB curser*after* last read row. Don't free result set.NOTE: col may be given as col-name (string) instead of offset (int). It will beused as key to identify the right column. So pass the right type!Sample: Given is the table "mytable" containing:\/ID TEXT DATE-------------------------------1 'one' 09.05.19602 'two' 25.12.19703 'three' 31.01.1980/\getCol('SELECT id, teXt, date as birthday FROM mydate', 'teXt'); // would return array('one', 'two', 'three');If you'd only wand to get array('two', 'three') you'd do:getCol($query, 1, 1) or getCol($query, 1, 1, 2) or getCol($query, 'teXt', 1)Fetch a full OR fraction col of data as vector given by the param $source.can be an SQL query string, or a resource.(opt) used only when the query returns exactly two columns. If true, the values of the returned array will be one-element arrays instead of scalars.(default is FALSE. if set to true then the values will be returned in a hash (with field names) instead of a vector. see example 3 above.)Bs_Exception on error$source can be either a SQL query string or a result set.IF param $source is a query-string:Execute the query, fetch entire data and clean up (free the results set).ELSEIF param $source is a result set:Fetch the entire data. Don't free result set.If more than 2 values are involved in the result set or if $forceArray is TRUE,a hash containing a vector is returned e.g. array('1' => array('one', '944679408'));otherwise a simple hash is returned (see sample below).If the result set contains fewer than two columns, a BS_DB_ERROR_TRUNCATED exception is raised.Sample: Given is the table "mytable" containing:ID TEXT DATE-------------------------------1 'one' 09.05.19602 'two' 25.12.19703 'three' 31.01.1980example 1:getAssoc('SELECT id,text FROM mytable'); // would return: array( '1' => 'one','2' => 'two','3' => 'three')example 2:getAssoc('SELECT id,text,date FROM mydate') // would return: array( '1' => array('one', '944679408'),'2' => array('two', '944679408'),'3' => array('three', '944679408'))example 3:getAssoc('SELECT id,text,date FROM mydate', TRUE, TRUE) // would return:array( '1' => array('text'=>'one', 'date'=>'944679408'),'2' => array('text'=>'two', 'date'=>'944679408'),'3' => array('text'=>'three', 'date'=>'944679408'))this option is new, 2002/03/25 --andrejspecial note: you have to use a key that is unique. otherwise only one record will beused, i think the later ones overwrite the previews.Fetch the entire data given by the param $source into a hash using the first column as the key.can be an SQL query string, or a resource.used only when the query returns exactly 1 column. If true, the values of the returned array will be one-element arrays instead of scalars.Bs_Exception on errorThe rest is like getAssoc(). See above.Sample: Given is the table "mytable" containing:ID TEXT DATE-------------------------------1 'one' 09.05.19602 'two' 25.12.19703 'three' 31.01.1980getAssoc2('SELECT id, teXt, date as birthday FROM mytable');would return:array( 'id' => array('1', '2', '3'),'teXt' => array('one', 'two', 'three'),'birthday' => array('09.05.1960', '25.12.1970', '31.01.1980'))hash array COLUMN BY COLUMN not record by record.can be an SQL query string, or a resource.(opt) (default BS_DB_FETCHMODE_ASSOC) see getRow.a nested array. See sample above. may be an empty array if nothing was found.Bs_Exception on error$source can be either a SQL query string or a result set.IF param $source is a query-string:Execute the query, fetch entire data and clean up (free the results set).ELSEIF param $source is a result set:Fetch the entire data. Don't free result set.Sample: Given is the table "mytable" containing:ID TEXT DATE-------------------------------1 'one' 09.05.19602 'two' 25.12.19703 'three' 31.01.1980getAll('SELECT id, teXt, date as birthday FROM mydate', 'teXt', BS_DB_FETCHMODE_ASSOC) returns:would return:array( array('id' => '1', 'teXt' => 'one', 'birthday' => '09.05.1960'),array('id' => '2', 'teXt' => 'two', 'birthday' => '25.12.1970'),array('id' => '3', 'teXt' => 'three', 'birthday' => '31.01.1980'))Fetch the entire data given by the param $source into a hash.true if the extension was already or successfully loaded, false if it could not be loadedLoad a PHP database extension if it is not loaded already.for security reason, no user/pass information is returned here because someone(you?) might log the returned value.Returns a string with information about the current state of this db object.the escaped queryif there is a better/specialized way for your specific rdbms, overwrite this.Escape string for the query.formatDatetimeForDb()formatTimestampForDb()(yyyy-mm-dd) (date formatted for this rdbms implementation)overwrite this if needed.format and return date string in database date format.formatDateForDb()formatTimestampForDb()(yyyy-mm-dd hh:mm:ss) (datetime formatted for this rdbms implementation)overwrite this if needed.format and return datetime string in database datetime format.formatDateForDb()formatDatetimeForDb()(yyyy-mm-dd hh:mm:ss) (timestamp formatted for this rdbms implementation)overwrite this if needed.format and return timestamp string in database timestamp format.an associative array.a delimiter, default is ', ', could be ' AND ' or ' OR ' ...a string to include in an sql query.example 1:$arr = array('name' => 'tom', 'age' => '35', 'sex' => 'm');$sqlQuery = "UPDATE tbl SET " . $db->quoteArgs($arr, ', ') . " WHERE ID = 1";=> "UPDATE tbl SET name = 'tom', age = '35', sex = 'm' WHERE ID = 1";example 2:$arr = array('name' => 'tom', 'age' => '35', 'sex' => 'm');$sqlQuery = "SELECT * FROM tbl WHERE " . $db->quoteArgs($arr, ' AND ');=> "SELECT * FROM tbl WHERE name = 'tom' AND age = '35' AND sex = 'm'";Note I: $this->escapeString() is used on the $value.Note II: boolean values are converted to ints.Takes a hash and returns a string for an sql query.queryTells whether a query is a data manipulation query (insert, update, delete replace, alter, drop, create).a custom error message. if not specified, the var $_lastQuery will be used here.(use __FILE__)(use __LINE__)('fatal')This method is called by DB to generate an error.a bs error code (see constants)error message, or false if the error code was not recognizedReturn a textual error message for a bs DB error codethe SQL queryNOTE: This is so fundemental that we exit with error, if this function is not overloaded.Send a query to the DB and return the result.(opt) If TRUE turn on else off (default TRUE)Bs_Exception if not supported by this DBTurn autoCommit on or offBs_Exception if not supported by this DB or on any other error.Starts a transactionBs_Exception if not supported by this DB or on any other error.Commit last queryBs_Exception if not supported by this DB or on any other error.Rollback last querythe row number, which starts at position 0.TRUE on success, NULL on a row number (param $num) that is out of bounds.Bs_Exception if not supported by this DB or on any other error.The next fetch call would return that row.Set the internal row pointer of the result id to point to the specified row number.vector , hash or NULL if there is no more dataBs_Exception if not supported by this DB or any other error.Subsequent calls will return the next row in the result set, or NULL if there are no more rows.If fetchMode is BS_DB_FETCHMODE_ASSOC (default) it returns a hash array that correspondsto the fetched row else if it's BS_DB_FETCHMODE_ORDERED returns a vector starting at offset 0.Fetch a row and return it as vector or hash depending on the fetchMode.Free the internal resources associated with $result.the number of columns per row in $resultBs_Exception if not supported by this DB or any other error.Get the number of columns (fields) in a result identifier.see aboveBs_Exception if not supported by this DB or any other error.Get the number of rows from a result identifier.see aboveBs_Exception if not supported by this DB or any other error.Gets the number of rows affected by the last data manipulation query.a positive integer, which means >=1Bs_Exception if not supported by this DB or any other error.Get the id generated from the previous INSERT operation.see aboveBs_Exception if not supported by this DB or any other error.Returns the numerical native error code from the previous DB operation or 0 (zero) if no error occured.see aboveBs_Exception if not supported by this DB or any other error.Returns the native error text from the previous DB operation or '' (empty string) if no error occured.TRUE if we already have been or are now disconnected, FALSE if we're on a persistant conn.NULL if we cannot tell in which state the connection is now. internally for this objectthe connection is 'closed'.Note: p-connected links won't be closed.Log out and disconnect from the database.NULLa reference to a real db connectionFALSETells whether we're connected.FALSETells whether we're on a persistant connection.NULL'name' => db name 'pass' => letmein'host' => localhost 'socket' => a unix socket'port' => 6667 'syntax' => mysql'user' => root 'type' => mysql'tns' => identifier for oracleDB type (mysql, oci8, odbc etc.)Db syntax (mysql, access, oracle, ...)associative array holding the db-conn info in these fields:NULLthe last executed query.reference to the globally used pseudostatic Bs_Date object.NULLThey make use of _Bs_System->isWindows() function.A few functions are system dependent like assertExtension() and the subclassed Bs_MySql.NULLwith the elements'prepare' => bool'pconnect' => bool'transactions' => bool'innerSelects' => bool'insertId' => bool'affectedRows' => bool'numRows' => bool'numCols' => bool'storedProc' => boolAssociative array of capabilities for this DB implementationarray( 'date' => "'Y-m-d'", //no escapeString() will be used on that. 'datetime' => "'Y-m-d H:i:s'", //no escapeString() will be used on that. 'timestamp' => "'YmdHis'", //no escapeString() will be used on that. )formatDateForDb()formatDatetimeForDb()formatTimestampForDb()some database specific formats. please overwrite.1Column data indexed by numbers, ordered from 0 and up2Column data indexed by column names4.0.$x$123456789101112131415161718192021222324252627isexisexceptiontohtmlpersistunpersistbs_objectbbsetoutputbbawakebbisawakebbxmsgbbxfunctionstartbbxfunctionendbbxechobbxvarbbxvardumpbbforcetracebbbufferstartbbbuffergetbbbufferendflushbbbufferendcleanbs_object_versionBs_ObjectBs_ObjectBs_MsSqlBs_MySqlBs_Oci