documentation.txt

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

  _N_o_t_e_: PHPLIB requires that you have track_vars compiled in and
  enabled.

  _N_o_t_e_: PHPLIB does not require short_open_tag to be enabled. The
  library always uses <?php as the PHP command introducer.

  _N_o_t_e_: PHPLIB does not require magic_quotes_gpc to be enabled. The
  library always uses addslashes() when necessary.


  22..33..22..  DDaattaabbaassee rreeqquuiirreemmeennttss

  The PHP base library requires a database connection in the default
  setup for storage of session variables, but this can be circumvented
  by selection another storage container type at installation time.
  Currently, storage containers are available for SQL databases (the
  default), SQL databases with limited string length (ct_split_sql.inc),
  System V shared memory (requires a PHP interpreter with SYSVSHM and
  SYSVSEM support), LDAP servers (requires a PHP interpreter with LDAP
  support), flat files, and DBM files.

  Using SQL, currently MySQL is fully supported and PostgreSQL, mSQL,
  Sybase, Microsoft SQL Server, ODBC and Oracle have limited support
  (the limitation is only relevant if you intend to access metadata
  information, i.e. table definitions and the like).  Database
  interfaces are not difficult to write and you can easily write your
  own interface.

  You need a database server connection with select, insert, update and
  delete privileges from your CGI environment. You need create and drop
  privileges from an administrative account outside your CGI environment
  as well.

  PHPLIB core functionality requires two tables as part of your
  application table name space: active_sessions (select, insert, update
  and delete privilege required for the application user) and auth_user
  (select privilege required for the application user. insert, update
  and delete privilege required for the application user if user
  management is to be done from within the application).

  Extended functionality may require additional tables.


  22..33..33..  NNaammee ssppaaccee rreeqquuiirreemmeennttss


  PHPLIB tries to be as name space neutral as possible with its core
  features. Is issues no HTML by default and it occupies only few names
  in the global name space. These are the class names for the classes
  defined: DB_Sql, DB_SAM, CT_Sql, Session, Auth, Perm, User.
  Additionally, the classnames DB_Example, Example_CT_Sql,
  Example_Session, Example_Auth, Example_Challenge_Auth, Example_Perm
  and Example_User are defined by the sample setup in local.inc, but
  these names can and shall be customized by the application developer.
  PHPLIB defines the function names page_open(), page_close, sess_load()
  and sess_save() for the page management functions. The global variable
  $_PHPLIB (a hash) is taken. Only if page_open() is being used, globals
  are defined by the library by default, but one global for each
  "feature" requested in the page_open() statement is taken.  These are
  at most $sess, $user, $auth and $perm.

  Including extension functionality or HTML widgets may occupy
  additional classnames, function names or variables in the global name
  space.


  22..33..44..  YYeeaarr 22000000 ccoommpplliiaannccee ssttaatteemmeenntt


  PHPLIB uses date fields within the column changed in the table
  active_sessions in your database.  The changed field is used in
  garbage collection, that is, to clean out abandoned sessions. The date
  field is a 14 character field of the format YYYYMMDDhhmmss, that is,
  the date field has four digit years and will cope properly with the
  new millennium.

  PHPLIB sets cookies in the client browser. These cookies by default
  have session lifetime, that is, they do not expire but are not written
  to disk. Date calculations are not involved.

  It is possible to have PHPLIB set cookies with a limited lifetime by
  defining the $lifetime slot of the Session class.  If this is done, it
  depends on the date handling of the client browser and client
  operating system, if the result is Y2K compliant. There are known
  issues with longterm cookies and any browser on MS-DOS/Windows 3.11
  systems.

  PHPLIB does some date arithmetic internally that involves mktime() and
  date() functions of the PHP3 language and Unix time_t data types. The
  signed 32 bit Unix time_t data type counts seconds since 01-Jan-1970
  Midnight GMT and will overflow sometime in the year 2038.

  PHPLIB itself will function up to 2038 and longer, if the Unix time_t
  is being extended in time. PHPLIB does not protect you from date and
  Y2K issues in your PHPLIB application, the PHP3 interpreter, the
  server operating system oder server software, the client browser, the
  client operating system or other parts of your installation.


  22..44..  IInnssttaallllaattiioonn pprroocceedduurree

  mod_php note: The following instructions apply to the CGI version of
  PHP as well as to the module version. If you are working with mod_php,
  you must restart your web server to force a reload of the php3.ini
  file, though.

  If you are using mod_php, you have additional configuration options:
  See the section below on using PHPLIB mit mod_php.



     LLiibbrraarryy SSeettuupp
        Create a directory php next to your cgi:



          ___________________________________________________________________
          /home/www/servers/phplib.netuse.de/pages   <- document root
                                             cgi     <- php binary
                                             php     <- includes and prepends
          ___________________________________________________________________

     Make this php directory your php include directory: Put
     include_path = /home/www/servers/phplib.netuse.de/php into
     cgi/php3.ini. If you already have an include path defined in your
     setup, add the PHPLIB include path to the existing include path
     using the separator character applicable for your operating system
     (":" on UNIX, ";" on Windows).  Defining an include path will not
     actually include code on your pages; it only tells the PHP
     interpreter in which directories to look for files referenced in
     require() and include() statements.

     Into the php directory go all the files from the php directory of
     the distribution. Into documentroot, put all the files and
     directories from the pages directory of the distribution.

     Have documentation.txt handy and read it.


     DDaattaabbaassee aacccceessss wwiitthh MMyySSQQLL
        The following information applies to MySQL only. No information
        is provided for other database servers as of now. You are
        encouraged to copy this section, adapt it for your database
        server and submit it to the authors. It will be included in
        further releases of PHPLIB.

        Edit prepend.php3. Change the first require() statement to
        require("db_mysql.inc");. This will include the MySQL database
        interface (Interfaces for other databases are provided in
        db_<databasename>.inc. The require() statement has to be adapted
        to reflect this).

        Assuming your database server is named database.netuse.de and
        your CGI user is webuser and you are accessing the database
        myapp, do



          ___________________________________________________________________
          mysql -h database -u webuser myapp
          ___________________________________________________________________




     If it does not work, connect your database as administrator and
     create the proper mysql access permissions. Adapt and run
     create_database.mysql from the stuff subdirectory of the
     distribution to create the databases active_sessions and auth_user
     as well as the sample user kris with password test. Try again to
     connect like shown above. Can you do select * from active_sessions?
     and insert into active_sessions values ("1", "2", "3", "") as well
     as delete from active_sessions? Can you select * from auth_user?

     _N_o_t_e_: Additional database creation scripts are provided for several
     different databases in the stuff directory of the distribution.


     MMeerrggiinngg tthhee lliibbrraarryy wwiitthh yyoouurr PPHHPP ffiilleess
        Decide if you want to use include or auto_prepend_file. We do
        use auto_prepend_file here and we add the statement
        auto_prepend_file =
        /home/www/servers/phplib.netuse.de/php/prepend.php3 to our
        php3.ini.

        Not all classes are included/required by prepend.php3, only core
        functionality files are: db_xxx.inc, ct_sql.inc, session.inc,
        auth.inc, perm.inc, user.inc, local.inc and page.inc. The
        library provides other, less essential classes that can be
        included manually on a page-by-page basis.  Some classes make
        themselves persistent, if used. These classes require that you
        include their definitions in the prepend.php3 file where
        indicated to function correctly.  See the usage instructions for
        these classes for details.

        Having done this, access /index.php3. The counter should
        increment when that page is being reloaded. Also, checking
        active_sessions in the database should reflect that session.


     SSuubbssccrriibbee ffoorr ssuuppppoorrtt
        Subscribe to the mailing list [e-mail]. Do so by
        sending a mail body of subscribe to phplib-
        [e-mail] and follow instructions. Share your
        experiences.



  22..55..  UUssiinngg iinncclluuddee(())  iinnsstteeaadd ooff aauuttoo__pprreeppeenndd__ffiillee==

  If you do not want to use auto_prepend_file to load the PHPLIB core
  functionality, you can load the class definitions for the core
  manually on each page that requires them.

  You will have to define a valid include_path=-statement in your
  php3.ini file as outlined previously to reflect the location of the
  *.inc files. Then, all core functionality can be loaded with
  include("prepend.php3") as the first statement at the top of each
  page.

  To further optimize performance, you can minimize the contents of the
  prepend file, if you do not need all core functionality.  You _m_a_y
  leave out auth.inc, perm.inc and user.inc, if you do not require these
  features (note that there are dependencies among these classes!).


  22..66..  PPHHPPLLIIBB wwiitthh mmoodd__pphhpp ((AAppaacchhee mmoodduullee))


  Installing PHPLIB onto a web server that has PHP3 as a module
  (actually Apache) mainly differs in where you can set up runtime
  settings for PHP3 itself.  PHP3 can be compiled with a wealth of
  parameters (see the PHP section in phpinfo()), most of which can get
  overridden by the php3.ini file. The location of this file is shows as
  part of the output of phpinfo().

  With PHP3 as a module you have a wider choice on placing these
  settings: they are overridden, in this order, by what is defined in
  httpd.conf and in your per-directory .htaccess file. Directives in
  these files are identical to their php3.ini brothers, but are prefixed
  with php_ to avoid clashes with Apache configuration keywords. Also,
  as they are Apache configuration keywords, they have no equals ("=")
  sign in them. If x=y is a configuration directive from php3.ini, you
  should be using php3_x y within the Apache configuration instead. That
  is, you should prepend php3_ to the keyword and omit the equals sign.
  If you misspell a configuration directive, you will get an error 500
  from your webserver and find more details about the error in the
  logfile you configured with ErrorLog in your webserver setup.

  _E_x_a_m_p_l_e_: If below we talk about setting in your php3.ini the
  configuration



  ______________________________________________________________________
  include_path = "/bla"
  ______________________________________________________________________




  mod_php users may alternatively configure in their httpd.conf the
  following:



       ______________________________________________________________________
       <Directory /home/www/servers/phplib.netuse.de/pages>
       php3_include_path "/bla"
       </Directory>
       ______________________________________________________________________




  Of special interest to PHPLIB users are the following directives:



       ______________________________________________________________________
       ;;;;;;;;;;;;;;;;;
       ; Data Handling ;
       ;;;;;;;;;;;;;;;;;
       magic_quotes_gpc = Off    ; magic quotes for incoming
                                 ; GET/POST/Cookie data
       magic_quotes_runtime = Off; magic quotes for runtime-generated data,
                                 ; e.g. data from SQL, from exec(), etc.
       magic_quotes_sybase = Off ; Use Sybase-style magic quotes
                                 ; (escape ' with '' instead of \')
       track_vars = On           ; enable $PHP_GET_VARS[], $PHP_POST_VARS[]
                                 ; and $PHP_COOKIE_VARS[] arrays

       ; automatically add files before or after any PHP 3.0 document
       auto_prepend_file = (add path to prepend.php3 here)
       auto_append_file  =

       ;;;;;;;;;;;;;;;;;;;;;;;;;
       ; Paths and Directories ;
       ;;;;;;;;;;;;;;;;;;;;;;;;;
       include_path      = (add path to the directory with all .inc files)
       ______________________________________________________________________




  All of this comes very handy when you have multiple virtual hosts
  (e.g. you are an ISP). In this case you can comfortably place the php3
  directives in the <VirtualHost> block or in an .htaccess file in the
  client directory.



  33..  CCoorree FFuunnccttiioonnaalliittyy

  Each class contains instance variables and instance methods. Some of
  these variables and methods are available for customization, some are
  internal to the classes themselves. All are documented, but tampering
  with internal variables and methods is not supported. Internal
  interfaces are subject to change without notice from one version of
  the library to another.
  This section covers PHPLIB core functionality in reference form.
  Classes are presented in order of dependency, though, because the core
  structure is easier understood in this order. You will need to
  understand the complete core structure to successfully use all of
  PHPLIB's features.


  33..11..  DDBB__SSqqll

  DB_Sql is used by CT_Sql and Auth to access a SQL database. You are
  encouraged to use it directly, too.


  33..11..11..  IInnssttaannccee vvaarriiaabblleess





                      Accessible instance variables.




                       Internal instance variables.


  33..11..22..  IInnssttaannccee mmeetthhooddss



  33..11..22..11..  AAcccceessssiibbllee iinnssttaannccee mmeetthhooddss