This goal of this extension of phplib is to let phplib use PHP4 native sessions instead of using a database for storing sessions data. The reason for the extension is to keep up with PHP4 technology and use it's new session feature and speed instead of offering a second way of doing sessions in PHP4.

So, this distribution is not a port but just an extension to phplib 7.2c. I think this is great because using this extension, PHP3 users are still able to use new versions of phplib without having to modify the code themselves. You can use phplib like you do with PHP3, running PHP3 or PHP4.

The main goal was to maintain compatiblity so that the interface would be the same and a minimum of effort has to be made to create new phplib sites or to port old sites to the new lib. This all has worked out quite well i think.

If you experience any problems with the extension, contact the author at <regiment@dds.nl>

For the impatient follows a quick installation guide covering the necessary steps to get phplib for PHP4 to work:

1) Download and unpack the archive:

         tar -zxvf phplib-4.tar.gz

or for the zipped version of the archive:

         unzip phplib-4.zip

2) Copy the files to the include directory of the website that you wish to use phplib for php4 for. Note that no files are overwritten.

         cp phplib-4/php/* /path/to/your/website/php

3) Next, open prepend.php4 in your favorite editor and edit it to match your website's preferences. Note the xxx4.inc files. Most users may only include some extra files here.

         vi /path/to/your/website/php/prepend.php4

4) Next, open local4.inc in your favorite editor and edit it to match your website's preferences. Most of the configuration can be copied from local.inc I guess.

         vi /path/to/your/website/php/local4.inc

5) In httpd.conf (or the approriate .htaccess file), search for a line like this (in the appropriate VirtualHost section):

         php_value auto_prepend_file /path/to/your/website/prepend.php3

and replace it with a line like this:

	php_value auto_prepend_file /path/to/your/website/prepend.php4

If you cannot modify httpd.conf but you can make the settings in a .htaccess file, make the setting in the .htaccess file!

If you cannot modify httpd.conf and .htaccess and you are using an include("prepend.php3") on top of every page, change all the include prepend.php3's to prepend.php4 or simply overwrite prepend.php3 with prepend.php4.

6) Now, open your browser and check it out! If you experience any problems, read the more thorough installation guide. Good luck!

The extension includes only 5 files:

session4.inc - new class Session that uses PHP4 sessions

user4.inc - new class User that uses PHP4 sessions

page4.inc - same old functions, using PHP sessions

local4.inc - new config file, using PHP sessions

prepend.php4 - new file to autoprepend, oh god, it's using PHP sessions!

The first two files are the main thing that has changed. The third is only adapted a little and the latter two are for convenience only, you can do without them as soon as you know what's inside them. Below I cover what happened.

The old code is always just commented out with // and /* */, so its easy to figure out what has been changed. Deprecated functions are emptied, not removed. Remember, nothing in phplib-7.2c has changed, only some files are copied and modified. So if you copy the new files to your existing php include directory, nothing is overwritten. You can use phplib like before, it just includes more!

The files:

Porting your sites to phplib for PHP4 is useful to keep up with new technologies, for that little extra speed or maybe just to finish a port to PHP4.

Porting your PHP3 sites is so very easy. The basic steps are:

1) Copy session4.inc, user4.inc and page4.inc to your existing phplib directory.

2) Copy local4.inc and prepend.php4 to the same directory as where local.inc and prepend.php3 reside. This might very well be the same directory as in step 1, but some users want to keep the library and the config files (local.inc, prepend.php, setup.inc) in separate locations, which is good practice if you have multiple sites that use the same phplib files.

3) Configure prepend.php4. That means, make it the same as your old prepend.php3 except it includes session4.inc, user4.inc and page4.inc instead of session.inc, user.inc and page.inc.

4) Configure local4.inc. That means, copy your configuration from local.inc to local4.inc. Keep these things in mind however:

a. If you use User variables, you must configure DB_Sql to use the appropriate database. If you don't use User variables, you probably still want to configure this to connect to a database. Most users just copy their existing 'class xxx extends DB_Sql' from local.inc.

b. The Session class does not support the session configuration anymore. If you want to change the session configuration, change php.ini. Typically, you change the classname and specify only $cookiename and $allowcache, but you dont even have to do this. You can still use $auto_init if you used it before. Most users don't change anything here, except the classname maybe.

c. The User class implements some stuff from the old Session class. Typically, you change the classname and specify $cookiename. Most users don't change anything here, except the classname maybe.

5) Configure httpd.conf. Tell Apache to auto_prepend your new prepend.php4 instead of prepend.php3. This is normally a per-site configured setting so change only the setting from the appropriate VirtualHost!

	php_value auto_prepend_file /path/to/your/website/prep

Restart Apache :-)

If you cannot modify httpd.conf but you can make the settings in a .htaccess file, make the setting in the .htaccess file!

If you cannot change your httpd.conf you are probably including prepend.php3 on top of every page using sessions. Change the includes to include prepend.php4. Or simply backup prepend.php3 and rename prepend.php4 to prepend.php3.

If Apache is configured to auto_prepend prepend.php3, but you are not allowed to change it again, backup prepend.php3 and rename prepend.php4 to prepend.php3.

6) Forget about local.inc and prepend.php3. Archive them and make sure no forgotten scripts use them accidentally.

After completing these steps you're set! You can test you site. For most sites you should be done within a few minutes without any problems. Otherwise, complain.

You can create your sites using sessions like you are used to do, either using PHP4's session functions or phplib's Session class. However, using phplib is sometimes more convenient because it offers some functions that PHP4 doesn't. Evaluate your configuration before you start your project:

If you want to create a site that uses sessions but doesn't use auth, perms or user variables, it is recommended NOT to use phplib for PHP4, but PHP4 session functions. But then you have to take care of the session id in links yourself:

If you have full control over PHP4 compilation, you should recompile PHP4 with the --enable-trans-sid option. With this option enabled, PHP4 adds session ids to all links in your documents automatically, depending on the reader's browser supporting cookies or not. So you don't have to worry about the session id in links anymore. Note that in PHP 4.0.3 you can enable this option in php.ini, without recompiling.

If you don't have full control over the PHP4 compilation or configuration, you are probably bound to the standard configuration (without the --enable-trans-sid option). If this case you have to add the session id to all links manually (for no-cookie browsers). In this case you should use phplib for PHP4 because it offers convenient url functions, while still using PHP4 native sessions.

Check phpinfo() for details about your configuration.

If you want to use phplib's auth, perms or user variables, it is better not to use PHP4's session functions, but only phplib's. Take care not to mix things. For example:

         session_start();
	page_open(array("sess" => "Example_Session",
                         "auth" => "Example_Auth",
                         "perm" => "Example_Perm",
                         "user" => "Example_User"));

is a mistake, because this way the session management will be started twice, with unknown results.

         session_start();
	page_open(array("auth" => "Example_Auth",
                         "perm" => "Example_Perm",
                         "user" => "Example_User"));

isn't any good either, because this way the auth, perms and user will not be started at all.

	page_open(array("sess" => "Example_Session",
                         "auth" => "Example_Auth",
                         "perm" => "Example_Perm",
                         "user" => "Example_User"));

is the only good way to start a PHP4 native session with phplib auth, perms and user.

At the end of your page you can page_close() your page, but this is only necessary if you are using User variables.

The rest of the library is the same as before. More documentation on how to use phplib can be found at:

http://www.sanisoft.com/phplib/.

You can simply use this url to get your copy of PHPlib along with PHP4 extensions:

Download just the extensions

* Adapted from the original README4 by <regiment@dds.nl>