📄 documentation-3.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><HTML><HEAD> <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9"> <TITLE>PHP Base Library Documentation, Release phplib_7_2: Core Functionality</TITLE> <LINK HREF="documentation-4.html" REL=next> <LINK HREF="documentation-2.html" REL=previous> <LINK HREF="documentation.html#toc3" REL=contents></HEAD><BODY><A HREF="documentation-4.html">Next</A><A HREF="documentation-2.html">Previous</A><A HREF="documentation.html#toc3">Contents</A><HR><H2><A NAME="s3">3. Core Functionality</A></H2><P>Each class contains instance variables and instance methods. Some of thesevariables and methods are available for customization, some are internal tothe classes themselves. All are documented, but tampering with internalvariables and methods is not supported. Internal interfaces are subject tochange without notice from one version of the library to another.<P><P>This section covers PHPLIB core functionality in reference form.Classes are presented in order of dependency, though, becausethe core structure is easier understood in this order. You willneed to understand the complete core structure to successfullyuse all of PHPLIB's features.<P><H2><A NAME="ss3.1">3.1 DB_Sql</A></H2><P><CODE>DB_Sql</CODE> is used by <CODE>CT_Sql</CODE> and <CODE>Auth</CODE> to access aSQL database. You are encouraged to use it directly, too.<P><H3>Instance variables</H3><P><P><CENTER><TABLE BORDER><TR><TD><BR>Host </TD><TD>Host where your SQL server is running on.</TD></TR><TR><TD>Database</TD><TD>Name of database or instance to use on that server.</TD></TR><TR><TD>User </TD><TD>The username used in connections attempts.</TD></TR><TR><TD>Password</TD><TD>The password used in connection attempts.</TD></TR><TR><TD>Row </TD><TD>Number of the current result row starting at 0.</TD></TR><TR><TD>Errno </TD><TD>Integer: error number of last database operation.</TD></TR><TR><TD>Error </TD><TD>String: error message of last database operation.</TD></TR><TR><TD>Halt_On_Error</TD><TD>One of "yes", "no", "report". If set to"yes" (the default), the database interface will report any errors and haltthe program. If set to "report", the database interface will still reportany errors, but continue reporting "false" back to the application, withErrno and Error set appropriately. If set to "no", the database interfacewill not report any errors, but silently report "false" back to application,with Errno and Error set appropriately.</TD></TR><TR><TD>Auto_Free</TD><TD>Boolean: In some DB interfaces a flag for earlyresult memory release.</TD></TR><TR><TD>Debug </TD><TD>Boolean: If set, the database class will output all queriesand additional diagnostic output.</TD></TR><TR><TD>type </TD><TD>Contant string: The name of the database interface, e.g."mysql" or "oracle"</TD></TR><TR><TD>revision</TD><TD>Contant version string: The version of the database API(e.g. 1.2), NOT the CVS revision of the file implementing the API.Sql_Table</TD><TD>string: The name of the table used by the<CODE>nextid()</CODE> API function.</TD></TR><TR><TD><CAPTION>Accessible instance variables.</CAPTION></TD></TR></TABLE></CENTER><P><CENTER><TABLE BORDER><TR><TD><BR>Record </TD><TD>In some DB interfaces a hash of the current table result row.</TD></TR><TR><TD>Link_ID </TD><TD>SQL Link ID.</TD></TR><TR><TD>Query_ID</TD><TD>SQL Result ID.</TD></TR><TR><TD><CAPTION>Internal instance variables.</CAPTION></TD></TR></TABLE></CENTER><P><H3>Instance methods</H3><P><P><H3>Accessible instance methods</H3><P><P><DL><DT><B>DB_Sql($query = "")</B><DD><P>Constructor. When creating an instance, you may optionally supply a query string.<P><BLOCKQUOTE><CODE><HR><PRE>$db = new DB_Sql_Subclass("select * from mytable");)</PRE><HR></CODE></BLOCKQUOTE><P><DT><B>query($query_string)</B><DD><P><CODE>query_string</CODE> is a SQL statement that is sent to the database.After sending the statement, <CODE>Error</CODE> and <CODE>Errno</CODE> are updated.If the query is syntactically incorrect (no valid result id isbeing produced), <CODE>halt()</CODE> is called with a meaningful errormessage.<P>If there is no active link to the database, a <CODE>pconnect()</CODE> ismade using the information from the <CODE>Host</CODE>, <CODE>Database</CODE>,<CODE>User</CODE> and <CODE>Password</CODE> instance variables.<P>Returns the result of the <CODE>query()</CODE> statement, which isguaranteed to be a valid result id (or false, ifHalt_On_Error isn't "yes").<P><DT><B>next_record()</B><DD><P><CODE>next_record()</CODE> advances the cursor through thecurrent query result and updates the <CODE>Record</CODE>, <CODE>Row</CODE>,<CODE>Errno</CODE> and <CODE>Error</CODE> instance variables.<P>Returns true, if there is a new result record. Returns false, ifdone with the current result set. If <CODE>Auto_Free</CODE> is true,<CODE>free_result()</CODE> is called automatically before falseis returned.<P><DT><B>num_rows(), nf()</B><DD><P>Returns the number of rows returned by the current SELECT query.<P><EM>Note:</EM> This information is not available in all databaseinterfaces. Some of the more advanced databases begin to returnquery results asynchronously while the backend is stillappending result rows. In such environments the complete size ofthe result set is never known. <P>You should duplicate your WHERE clause of the query in suchenvironments and ask for the COUNT(*). This will be lessinefficient as it seems as the query path and query result havebeen cached by the database.<P><DT><B>affected_rows()</B><DD><P>Returns the number of rows affected by the current INSERT,UPDATE or DELETE query.<P><DT><B>num_fields()</B><DD><P>Returns the number of columns returned by the current query.<P><DT><B>np()</B><DD><P>Prints the number of rows returned by the current query.<P><DT><B>f($field)</B><DD><P>Identical to accessing <CODE>Record[$field]</CODE>.<P><DT><B>p($field)</B><DD><P>Identical to printing Record[$field].<P><DT><B>haltmsg($msg)</B><DD><P>This function is called by <CODE>halt()</CODE> and will actually printthe database error message. You may override this method in yoursubclass of <CODE>DB_Sql</CODE> and format the error message tobe consistent with the layout of the rest of your application.You may also add additional error handling such as informing theapplication operator by mail that a database error has occured.<P><DT><B>seek($pos)</B><DD><P>Positions the <CODE>Row</CODE> pointer within the result set. Useful forreading the same result set twice or otherwise jumping aroundwithin the result. <CODE>$pos</CODE> is not checked in any way forvalidity.<P><EM>Note:</EM> If <CODE>Auto_Free</CODE> is true, <CODE>seek()</CODE> may not beuseable, because the result set has already been free'ed when<CODE>next_record()</CODE> when behind the last record of the resultset.<P><EM>Note:</EM> Not all database interfaces provide a cursor that iscapable of seeking. This function will be unavailable in suchenvironments.<P><DT><B>link_id()</B><DD><P>This function will return the current link ID, as returned bythe <CODE>pconnect()</CODE> executed internally by the database class.<P>You should not need this information.<P><DT><B>query_id()</B><DD><P>This function will return the current result ID, as returned bythe <CODE>query()</CODE> executed internally by the database class.<P>You should not need this information.<P><DT><B>metadata($table = "", $full = false)</B><DD><P><CODE>$table</CODE> is a SQL table name in the current database. Thefunction returns an array of hashes indexed on the (0 based)column number of <CODE>$table</CODE>. Each hash is indexed by <CODE>table</CODE>(table of which this column is part of), <CODE>name</CODE> (name of thiscolumn), <CODE>type</CODE> (column data type), <CODE>len</CODE> (column width)and <CODE>flags</CODE> (database specific column flags, if applicable)with one row per table column. Each row describes a column inyour table.<P>The data returned by <CODE>metadata()</CODE> is suitable for passingit to the Table class. If you specify the <CODE>full</CODE> parameter,an additional column <CODE>meta</CODE> is added, which is indexed byfield name and returns the field number of that name. Also, acolumn <CODE>num_fields</CODE> is added, containing the widthof the table.<P>If <CODE>$table</CODE> is omitted, the function returns metadata on the resultof the last executed query. <EM>Note:</EM> This is currently implemented onlyfor the MySQL interface. You are encouraged to implement this featurefor other interfaces.<P><EM>NOTE:</EM> At the moment, the PostgreSQL and ODBC interface only reportthe <CODE>table</CODE>, <CODE>name</CODE> and <CODE>type</CODE> data reliably. You areencouraged to fix this.<P><DT><B>table_names()</B><DD><P>Returns an array with table name and tablespace name.<P><BLOCKQUOTE><CODE><HR><PRE>table name : $return[$i]["table_name"]tablespace_name : $return[$i]["tablespace_name"]</PRE><HR></CODE></BLOCKQUOTE><P>Tables are from $i=0 to last table;<P>Implemented in db_oracle.inc,db_oci8.inc,db_mysql.inc,db_pgsql.inc<P><DT><B>nextid($sequence_name)</B><DD><P>This function will return a sequence number from the sequencenamed by <CODE>$sequence_name</CODE>. This number is guaranteedto be obtained in an atomic manner and can be used as a primarykey.</DL><P><H3>Internal instance methods</H3><P><P><DL><DT><B>connect()</B><DD><P>Used internally to generate a <CODE>Link_ID</CODE>, if necessary. Linkcreation is implicit, there is no need to call <CODE>connect()</CODE>manually, ever.<P><DT><B>halt($msg)</B><DD><P>Used by <CODE>query()</CODE> if the initial database connection cannotbe made or the target database does not exist. Depending onthe setting of <CODE>Halt_On_Error</CODE>, this methodwill call <CODE>haltmsg()</CODE> to report the error.<P><DT><B>free()</B><DD><P>Used internally by <CODE>next_record()</CODE> to free the resultset, if so configured.</DL><P><H3>Example</H3><P>Use a subclass to provide the appropriate parameters for adatabase connect. You may overwrite <CODE>halt()</CODE> to customize theerror message, although a sensible default is provided.<P><BLOCKQUOTE><CODE><HR><PRE>class DB_Article extends DB_Sql { var $classname = "DB_Article"; var $Host = "sales.doma.in"; var $Database = "shop_project"; var $User = "webuser"; var $Password = ""; function haltmsg($msg) { printf("</td></table><b>Database error:</b> %s<br>\n", $msg); printf("<b>MySQL Error</b>: %s (%s)<br>\n", $this->Errno, $this->Error); printf("Please contact shopmaster@doma.in and report the "); printf("exact error message.<br>\n"); }}</PRE><HR></CODE></BLOCKQUOTE><P>Use an instance of the subclass to manage your queries:<P><BLOCKQUOTE><CODE><HR><PRE>$q = new DB_Article;$query = sprintf("select * from articles where article like '%%%s%%'", $searchword);$q->query($query);while($q->next_record()) { printf("<tr><td>%s</td><td>%s</td></tr>\n", $q->f("art_id"), $q->f("article"));}</PRE><HR></CODE></BLOCKQUOTE><P><H3>Additional information about database connections</H3><P><P>PHP reuses connections, if possible. When a connection is beingmade to the same Host with the same Username and Password as anexisting connection, no second connection is being made by PHP.Instead the existing connection is returned to the caller. Thisis true for both, the *_connect() and *_pconnect() calls of allPHP database interfaces.<P>This has implications for MySQL users: Never use the MySQL "use"command to change the current database. If you do, sessionmanagement will fail to operate properly. Instead, createall PHPLIB tables as part of your application.<P>Some databases (for example Oracle) have very expensiveconnect() operations. For these databases, performance isdramatically improved if you switch from CGI PHP to mod_php.This is, because PHPLIB uses the "*_pconnect()" method toconnect to your database. In mod_php, the database connection iskept around by the web server process after the page has beenprocessed and is reused if a further connect requires aconnection with the same Host/Username/Password pattern.<P>This means that there will be at most "number of web serverprocesses" times "number of Host/Username/Password-combinations"many simultaneous connections to your database server. Keep thatin mind when planning licenses and server load. Using CGI PHPwill probably reduce the number of concurrent connects to yourdatabase server at the expense of connection setup time. Fordatabase servers where connection setup time is negligible(MySQL for example) this is a viable solution (don't try it withOracle) though.<P><H3>Using <CODE>nextid()</CODE></H3><P><P>The <CODE>nextid()</CODE> function can be used to obtain a sequencenumber which can be used as a primary key. The function managesan arbitrary number of named sequences, you have to provide thename of a sequence upon call.<P><BLOCKQUOTE><CODE><HR><PRE>$db = new DB_Article;$artnr = $db->nextid("article_sequence");$query = sprintf("insert into articles ( artnr, ...) values ('%s', ...)", $artnr, ...);$db->query($query);reset($articles);while(list($itemnr, $itemdesc) = each($articles)) { $itemnr = $db->nextid("item_sequence"); $query = sprintf("insert into items (artnr, itemnr, ...) values ('%s', '%s', ...)", $artnr, $itemnr, ...); $db->query($query);}</PRE><HR></CODE></BLOCKQUOTE>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -