documentation.txt

PHPLOB注释详细版 使用模板技术的好帮手 PHP最有用的东东了

     DDBB__SSqqll(($$qquueerryy ==
        Constructor. When creating an instance, you may optionally
        supply a query string.



          ___________________________________________________________________
          $db = new DB_Sql_Subclass("select * from mytable");)
          ___________________________________________________________________





     qquueerryy(($$qquueerryy__ssttrriinngg))
        query_string is a SQL statement that is sent to the database.
        After sending the statement, Error and Errno are updated.  If
        the query is syntactically incorrect (no valid result id is
        being produced), halt() is called with a meaningful error
        message.

        If there is no active link to the database, a pconnect() is made
        using the information from the Host, Database, User and Password
        instance variables.

        Returns the result of the query() statement, which is guaranteed
        to be a valid result id (or false, if Halt_On_Error isn't
        "yes").



     nneexxtt__rreeccoorrdd(())
        next_record() advances the cursor through the current query
        result and updates the Record, Row, Errno and Error instance
        variables.

        Returns true, if there is a new result record. Returns false, if
        done with the current result set.  If Auto_Free is true,
        free_result() is called automatically before false is returned.


     nnuumm__rroowwss(()),, nnff(())
        Returns the number of rows returned by the current SELECT query.

        _N_o_t_e_: This information is not available in all database
        interfaces. Some of the more advanced databases begin to return
        query results asynchronously while the backend is still
        appending result rows. In such environments the complete size of
        the result set is never known.

        You should duplicate your WHERE clause of the query in such
        environments and ask for the COUNT(*). This will be less
        inefficient as it seems as the query path and query result have
        been cached by the database.


     aaffffeecctteedd__rroowwss(())
        Returns the number of rows affected by the current INSERT,
        UPDATE or DELETE query.


     nnuumm__ffiieellddss(())
        Returns the number of columns returned by the current query.


     nnpp(())
        Prints the number of rows returned by the current query.


     ff(($$ffiieelldd))
        Identical to accessing Record[$field].


     pp(($$ffiieelldd))
        Identical to printing Record[$field].


     hhaallttmmssgg(($$mmssgg))
        This function is called by halt() and will actually print the
        database error message. You may override this method in your
        subclass of DB_Sql and format the error message to be consistent
        with the layout of the rest of your application.  You may also
        add additional error handling such as informing the application
        operator by mail that a database error has occured.


     sseeeekk(($$ppooss))
        Positions the Row pointer within the result set. Useful for
        reading the same result set twice or otherwise jumping around
        within the result. $pos is not checked in any way for validity.

        _N_o_t_e_: If Auto_Free is true, seek() may not be useable, because
        the result set has already been free'ed when next_record() when
        behind the last record of the result set.

        _N_o_t_e_: Not all database interfaces provide a cursor that is
        capable of seeking. This function will be unavailable in such
        environments.


     lliinnkk__iidd(())
        This function will return the current link ID, as returned by
        the pconnect() executed internally by the database class.

        You should not need this information.


     qquueerryy__iidd(())
        This function will return the current result ID, as returned by
        the query() executed internally by the database class.

        You should not need this information.


     mmeettaaddaattaa(($$ttaabbllee ==
        $table is a SQL table name in the current database. The function
        returns an array of hashes indexed on the (0 based) column
        number of $table. Each hash is indexed by table (table of which
        this column is part of), name (name of this column), type
        (column data type), len (column width) and flags (database
        specific column flags, if applicable) with one row per table
        column. Each row describes a column in your table.

        The data returned by metadata() is suitable for passing it to
        the Table class. If you specify the full parameter, an
        additional column meta is added, which is indexed by field name
        and returns the field number of that name. Also, a column
        num_fields is added, containing the width of the table.

        If $table is omitted, the function returns metadata on the
        result of the last executed query.  _N_o_t_e_: This is currently
        implemented only for the MySQL interface.  You are encouraged to
        implement this feature for other interfaces.

        _N_O_T_E_: At the moment, the PostgreSQL and ODBC interface only
        report the table, name and type data reliably. You are
        encouraged to fix this.


     ttaabbllee__nnaammeess(())
        Returns an array with table name and tablespace name.



          ___________________________________________________________________
          table name      : $return[$i]["table_name"]
          tablespace_name : $return[$i]["tablespace_name"]
          ___________________________________________________________________




     Tables are from $i=0 to last table;

     Implemented in db_oracle.inc,db_oci8.inc,db_mysql.inc,db_pgsql.inc


     nneexxttiidd(($$sseeqquueennccee__nnaammee))
        This function will return a sequence number from the sequence
        named by $sequence_name. This number is guaranteed to be
        obtained in an atomic manner and can be used as a primary key.


  33..11..22..22..  IInntteerrnnaall iinnssttaannccee mmeetthhooddss



     ccoonnnneecctt(())
        Used internally to generate a Link_ID, if necessary. Link
        creation is implicit, there is no need to call connect()
        manually, ever.


     hhaalltt(($$mmssgg))
        Used by query() if the initial database connection cannot be
        made or the target database does not exist. Depending on the
        setting of Halt_On_Error, this method will call haltmsg() to
        report the error.


     ffrreeee(())
        Used internally by next_record() to free the result set, if so
        configured.


  33..11..33..  EExxaammppllee

  Use a subclass to provide the appropriate parameters for a database
  connect. You may overwrite halt() to customize the error message,
  although a sensible default is provided.



       ______________________________________________________________________
       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 [e-mail] and report the ");
           printf("exact error message.<br>\n");
         }
       }
       ______________________________________________________________________




  Use an instance of the subclass to manage your queries:













  ______________________________________________________________________
  $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"));
  }
  ______________________________________________________________________





  33..11..44..  AAddddiittiioonnaall iinnffoorrmmaattiioonn aabboouutt ddaattaabbaassee ccoonnnneeccttiioonnss


  PHP reuses connections, if possible. When a connection is being made
  to the same Host with the same Username and Password as an existing
  connection, no second connection is being made by PHP.  Instead the
  existing connection is returned to the caller. This is true for both,
  the *_connect() and *_pconnect() calls of all PHP database interfaces.

  This has implications for MySQL users: Never use the MySQL "use"
  command to change the current database. If you do, session management
  will fail to operate properly. Instead, create all PHPLIB tables as
  part of your application.

  Some databases (for example Oracle) have very expensive connect()
  operations. For these databases, performance is dramatically improved
  if you switch from CGI PHP to mod_php.  This is, because PHPLIB uses
  the "*_pconnect()" method to connect to your database. In mod_php, the
  database connection is kept around by the web server process after the
  page has been processed and is reused if a further connect requires a
  connection with the same Host/Username/Password pattern.

  This means that there will be at most "number of web server processes"
  times "number of Host/Username/Password-combinations" many
  simultaneous connections to your database server. Keep that in mind
  when planning licenses and server load. Using CGI PHP will probably
  reduce the number of concurrent connects to your database server at
  the expense of connection setup time. For database servers where
  connection setup time is negligible (MySQL for example) this is a
  viable solution (don't try it with Oracle) though.


  33..11..55..  UUssiinngg nneexxttiidd(())


  The nextid() function can be used to obtain a sequence number which
  can be used as a primary key. The function manages an arbitrary number
  of named sequences, you have to provide the name of a sequence upon
  call.









  ______________________________________________________________________
  $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);
  }
  ______________________________________________________________________






  33..22..  PPaaggee MMaannaaggeemmeenntt



  33..22..11..  AAcccceessssiibbllee FFuunnccttiioonnss


  Page Management currently consists a collection of functions:


     ppaaggee__ooppeenn((aarrrraayy((
        This function is to be called with an array of page
        features/classname pairs. Valid features are at the moment:


        sseessss
           This page makes use of session variables.


        aauutthh
           This page uses session authentication. If you specify the
           auth feature, you MUST specify the sess feature, also.


        ppeerrmm
           This page is protected by permissions and only accessible to
           authenticated users with matching rights.  If you specify the
           perm feature, you MUST specify the auth and sess features,
           also.


        uusseerr
           This page makes use of user variables. If you specify the