A walkthrough for installation of PWS, Perl, and PHP4 on a Win98 SE machine.
Copyright (c) 2000 - 2003 David J. Fischer - fischer@shoutingman.com

***** Preface ****************************************************

This was written for myself, in case I ever have to reinstall all of this stuff. But I also like to give something to the community that provides such wonderful, free software. Like the little drummer boy, I don't have much, but I will offer what I can. This, then, is my gift to all the other newbies who, like me, don't know jack about server side processing, Perl or PHP. This is quite long, but I think it is very clear and direct.

This information is accurate to the best of my knowledge, but I cannot guarantee that it won't destroy your computer and all your files, especially since you will be modifying the registry. As I say later, backup your registry before starting. You may also want to do a backup of your files too, since registry editing can be a dangerous thing. That said, the first time I tried to install PHP4, I screwed things up and my computer crashed on boot until I booted in safe mode, which completed properly. Then I restarted, and that fixed things. After that, not real problems. But, your mileage may vary.

If you find this helpful please email and let me know.
If you find any errors, please notify me so I can correct them.
If you find something confusing, tell me and I'll try and clarify it.

Sincerely,

Dave Fischer

***** System Configuration ***************************************

Windows 98 SE (Win98 SE), x86, Win32
Microsoft Personal Web Server (PWS)
Perl, CGI (Build 616)
PHP (PHP4)

***** Preparation ************************************************

Time required: 3 - 5 hours

General recommendations: Do one at a time, as described here. After uninstalling and reinstalling PWS after Perl & PHP were isntalled, they stopped working. It required a fresh install of all three to restore full functionality.

First, back up your registry
	Start->Run->regedit
		Registry->Export Registry File
			Export range = All
			Save as type Registration Files (*.reg)

Now, uninstall PWS, Perl, PHP if you previously installed any of them and are having problems. This is to avoid possible weird conflicts. After uninstalling and rebooting as needed, search and remove from the registry all references to php, pl, cgi, perl that relate to file types, program behavior; don't worry about shortcuts, favorites, and file menu defaults. Searching the registry can be slow.

Restart in DOS mode. Run scanreg /fix to make sure everything is in order; this will take several minutes. Reboot, and back up the registry again, under a different name. If you're really paranoid, copy both registry backups onto a physically different harddrive, CD, Zip disk, etc.

***** PWS Installation *******************************************

Download mtssetup.exe from Microsoft.

Copy all files from D:\add-ons\pws, where D: is your Win98 CD, to a temp file on your hard-drive. 
Run mtssetup.exe to extract the Mtssetup.dll file into the pws temp directory; confirm that you want to overwrite the former Mtssetup.dll file.
Run setup.exe
Choose your configuration; I did custom, and added the ASP docs, and removed the Frontpage extensions.
Set your root publishing directory. PWS makes this the Home virtual directory. It places the scripts, iissamples, and I think webpub folders one level above the Home directory.
Example: on my computer, I renamed My Documents to Fischer, and my web design directory looks like:
C:\
	Fischer\
		WebDesign\
			fischer_dj\
			WC-Javascript\
			WC-Perl\
			WC-PHP\

I set fischer_dj as the root publishing directory. the scripts etc files were placed in the WebDesign folder.

After installation and subsequent reboot, bring up the Personal Web Server Setup program (from your Start menu or the icon tray). *DO NOT* go to Advanced yet! 

Choose either the Publish or Web Site options, it doesn't matter at this point, and go through the default web page install. The page may not display correctly or the browser may report errors. This seems to be associated with not using the default install root publish directory. It's not a problem

Now you can go to the Advanced options. It's time for a bit of advance planning. Create directories on your hard-drive for the Perl and PHP installations. I prefer my programs to be in the Program Files folder, so I create

C:\Program Files\Perl
C:\Program Files\PHP

In the PWS Advanced Options, select Home, then click Add. Set the alias to Perl, and set the directory to be the Perl folder you created. All three access settings must be checked: Read, Execute, Scripts. Click Home again, and make a PHP virtual directory, again with all three access privileges enabled. Finally, since fischer_dj, my site prototype, is home, which is under Web Design, I'd like a way to access all my web design stuff. So I edit the WEBPUB virtual folder and set the directory to 
C:\Fischer\WebDesign

Check the "Allow Directory Browsing" option. I prefer un-checking "Enable Default Document", but it's a preference thing. When checked, if any of the listed files are found, they are automatically loaded. That's handy for a web-site, but it prevents you from seeing the directory directly, which can be a bother for testing and prototyping.

Exit PWS (don't worry, it just hides it)

Now, we'll make our DNS substitute:
Load C:\Windows\HOSTS.SAM into a text editor, and save it as "HOSTS"--make sure there is no .txt or other suffix. This has the default entry for localhost, which references the Home virtual directory. You can add other Domain Name entries, if you wish, which also will reference Home. I am running an internal server. It's not connected to the 'net, but it is networked with my apt-mate's computer, so I added the following entries:

169.254.0.1 tacogato	# my computer name; use internal-only IP address
169.254.0.1 shoutingman.com	# I can alias multiple names to the same IP address
169.254.0.2 ryan		# alias my roomie's computer

These are necessary for him to see me; localhost always references your computer, from his computer localhost would be his system, not mine. Now, he can go to http://tacogato and see my web stuff.

Place a copy of this file in C:\WINDOWS on every computer on your intranet that will access your server.

Let's test it now.
Load a browser, and go to the URL http://localhost
If it can't find it, reboot. I'm not sure if the HOSTS file is read dynamically or at boot.
After a reboot, localhost and any other aliases to your computer should work fine. If you're on an intranet, you should also be able to use your aliases to see your server directory.

Another simple way to see if your server is really serving, is with dynamic frames. This is a method of passing information between pages using the URL followed by a "?" with the information following. It looks like this

http://www.mydomain.com?a=doc1.html?b=doc2.html?name=fischer

This is processed server side, and won't work on a PC without server access.

An example is at:
http://developer.netscape.com/docs/examples/javascript/frames/examples.html

You can download the code for example 1 (view and save as index.html and then view source on the frames and save as document_a.html, document_b.html, document_c.html, document_d.html. Place them all in your Home folder, and then open the URL 
http://localhost/index.html
	then change it to
http://localhost/index.html?a=document_d.html&b=document_c.html&c=document_b.html?d=document_a.html
All four frames should change. If you get an error, either you're trying to load the file from a folder instead of through the server, e.g. C:\mywebstuff\index.html?... instead of http://localhost/index.html?...;  or your server is not running properly.


Once you've seen that it works, reboot (you can't go wrong with a reboot).

***** Perl Installation ******************************************

This is how I installed ActivePerl, Build 616.

Download 
InstMsi.exe
ActivePerl-5.6.0.616-MSWin32-x86-multi-thread.msi (or the current version)

Run InstMsi.exe to create the MSI installer. Then you can run the ActivePerl msi file. 

Choose Custom install. Set the install directory to be the Perl directory you made earlier. Then click every install option and choose the "Entire feature will be installed on local hard-drive" option in the pop-up menu. Do this for all six options. Installation takes several minutes. Select Finish when complete. The readme file has never appeared after my installations, but it's not a problem.

Reboot

Open a DOS window. Enter "path" to check the path variable. There should be at least one line for the bin directory of the Perl install. If not, then run sysedit to modify the autoexec.bat.

Start->Run->sysedit

At the end of the SET PATH= statement, add the location of your Perl bin folder, e.g. (I also added the lib folder too, as recommended by the Perl docs.

;c:\progra~1\perl\bin;c:\progra~1\perl\lib

Reboot (sigh)

Open a DOS window. Go to Perl/eg/ and enter

perl example.pl

It should output

Hello from ActivePerl!

Congratulations! You've got the basic interpreter running. Time for the server big guns. From the documentation, it seemed best to use the ISAPI dll for processing perl/cgi scripts via the web server. That's what I describe here.

You need to tell the server how to execute a perl code. It's really simple. Just create a file named "Perl.reg" and enter the following text exactly, except for the start & end designators:

***** start file: Perl.reg *****
REGEDIT4

[HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\W3SVC\Parameters\Script Map]
".pl"="C:\\Program Files\\Perl\\bin\\PerlIS.dll"
".cgi"="C:\\Program Files\\Perl\\bin\\PerlIS.dll"

***** end file: Perl.reg *****

Change the extensions according to your needs, and the directory to suit your installation. You can have more or less extensions, one per line. Just don't add extra returns or spaces between the lines and be sure to keep the double back-slashes (\\). Save the Perl.reg file, then run it. Confirm that you want to modify your registry.

Now those extensions will be associated with the scripts for the server. To test this, bring up a browser and go to URL

http://localhost/perl/eg/IE3Samples/index.htm

If you set up the Perl virtual directory during PWS installation, it will load the PerlScript Samples Library page. Otherwise, first make a Perl virtual directory as described in the PWS directions.

Follow the links to test the perl script processing. It worked for me without a reboot. If nothing happens or an error is given, try a reboot. The Registry is voodoo and may not be fully reread until a reboot.

Then go to 

http://localhost/perl/eg/Core/cgi/index.html

This is the examples of CGI files. Try these out. This will test the association of .cgi with the Perl ISAPI module. If none of them work, especially the first couple, and you haven't rebooted since adding the Perl registry keys, reboot now. (I had to reboot here to get this to work.) If you have rebooted since modifying the registry, then something is not right. Check the keys to make sure they have the right path for the dll; make sure you typed the file extensions correctly; make sure you are running the cgi's through the server and not via a file load, i.e. C:\Perl\eg\.. bad, http://localhost/perl/eg... good.

If all that is working, then Perl is installed!

***** PHP Installation *******************************************

This is the install process for PHP4. I used php-4.0.1pl2-Win32.zip. The documentation claims that you need the updated dcom95.exe from microsoft. On win 98, dcom95.exe won't run, so don't bother getting it. There is a dcom98.exe, but PHP4 runs both with and without it, in my experience (Win 98SE).

Unzip the file and copy all the files to your PHP directory. Rename:

php.ini-dist to php.ini

Open it in a text editor. 
Search for the string doc_root and make sure it is not set to any value. 
Search for extension_dir and set its value to "c:\progra~1\PHP", or whatever your PHP directory is. Use the quotes. I've read that you don't need the quotes, but others have told me that you need the quotes. I recommend using them. I'm also not sure if long filenames (even within quotes) work, so I recommend using the truncated DOS equivalent. Search for brows_cap and delete the semi-colon (;) before it to uncomment it.

The various lines should now look like (with the quotes):

doc_root = ; the root of the php pages, used only if nonempty

extension_dir = "c:\progra~1\PHP" ; directory in which the loadable extensions (modules) reside

browscap = "c:\windows\system\inetsrv\browscap.ini"

Move the php.ini file to C:\WINDOWS\
Move the php4ts.dll & msvcrt.dll files to C:\WINDOWS\SYSTEM\. If there is already a msvcrt.dll, you don't need to replace it.

Now you need to tell the server what file extensions to associate with PHP. Create a file PHP.reg, enter the following text (except the start/end designations), save, and run it to add the keys to the Registry, as in the Perl installation.

***** start file: PHP.reg *****
REGEDIT4

[HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\W3SVC\Parameters\Script Map]
".php"="C:\\Program Files\\PHP\\php4isapi.dll"
".phtml"="C:\\Program Files\\PHP\\php4isapi.dll"

***** end file: PHP.reg *****

Note: if you choose to directly edit the registry key values, enter

C:\Program Files\PHP\php4isapi.dll

without quotes; it then appears as "C:\Program Files\PHP\php4isapi.dll" in the key display. Likewise, you can use the alternate method

"C:\Php\php.exe" "%s %s"

using the quotes; it appears as ""C:\Php\php.exe" "%s %s"" in the key. Of course, you can accomplish either using the PHP.reg file, which I what I recommend. I've found it is easier to do right.

Reboot (PHP might work without the reboot, but I doubt it.)

Time for a test. Enter the following code into a text editor and save it as
test.html
test.php
test.phtml (or whatever other file extensions you associated with PHP).

***** start file: test.html, .php, .phtml *****
<html>
	<head>
		<title>Example</title>
	</head>
	<body>
		Hello, I'm not a script!</P>
		<script language="php"> 
			echo("Hi, I'm a PHP script!");
		</script>
	</body>
</html>
***** end file: test.html, .php, .phtml *****

Place all the files in your PHP install directory. The go to the URLs
http://localhost/php/test.html
http://localhost/php/test.php
http://localhost/php/test.phtml

If you set up the PHP virtual directory as described in the PWS installation, you will load the test file and execute the php code. The output will look like:

Hello, I'm not a script!

Hi, I'm a PHP script!

for the .php and .phtml files. Only the 'not a script' text will appear for the .html file. If the scripts don't work, make sure you've got Execute privilege set in PWS for the folder the files are in; make sure you're browsing via the server (http://) and not the file directory (C:\My Documents); make sure the registry keys were set correctly.

If it worked, congratulations, you've installed PHP!


I now recommend rebooting (yes, again) and then testing everything again. (Perl and PHP files).


***** PHP4 Sessions ***********

In the php.ini file, the "session.save_path" variable is initially set at "/tmp", which normally doesn't exist in a Windows setup. Change it to a variable that exists, or create a C:\tmp directory. I have a C:\Temp directory, so I set the line to be:

session.save_path         = /Temp   ; argument passed to save_handler

***** PHP4 Cookies ************

The "setcookie" function is used to set cookies. It must be used before output HTML is sent to the browser window. The fifth argument is the domain for which the cookie is valid. If you are viewing files via http://localhost, then that field can be left blank ("", that is). Otherwise, the cookie may not be created. To check on the existence of the cookie, look in "C:\Windows\Temporary Internet Files" (press F5 to refresh too); look for a file labeled "Cookie:username@localhost/". It can be opened by dragging it into some text editors (aside: Windows is kinda weird about the way it handles the cookie files. Some text editors don't handle the file names properly and so won't open them.)

PHP automatically reads and sets all cookie variables from stored cookies. 

***** ASP Test ***************************************************

While you're at it, you might as well test Active Server Pages (ASP). This example comes from the WSP documentation. In the Contents tree, go to Lesson 1 in:

Microsoft Personal Web Server/Web Applications/ASP Tutorial/Creating ASP Pages

Or, create a new file, named test.asp, enter the following code (except the start/end designators), and save it in a directory for which you've specified execute privilege in PWS. Then load it in the browser, i.e. http://localhost/asp/test.asp

***** start file: test.asp *****
<%@ LANGUAGE = "JScript" %>
<HTML>
<BODY> 
<% for (i = 3; i <=7;  i++) { %> 
<FONT SIZE=<% = i %>> 
Hello World!<BR>
 </FONT>
<% } %>
</BODY>
</HTML>
***** end file: test.asp *****

If it works, it prints the line "Hello World!" five times with increasing font size.

***** File type association **************************************

It's all working. So what more could you ask for? I like to have cut little icons for the various filetypes, and I really like to be able to right-click Open With... to load all these files in my HTML editor. Here's the easy way to do that:

Open a folder on the screen and bring up the file type associate panel:

View->Folder Options...->File Types

***** .pl *****
New Type
Change Icon: C:\PROGRA~1\PERL\BIN\PERL.EXE (yellow dot)
Description of type: Perl File
Associated extension: .pl
Content Type (MIME): application/x-perl
Default Extension: .pl
Actions: New: 
	Action: &Open
	Application: C:\PROGRA~1\PERL\BIN\PERL.EXE "%1" %*
	OK
Actions: New: 
	Action: Open with Arachnophilia
	Application: "C:\Program Files\Arachnophilia\arach.exe" "%1"
	OK
OK

***** .cgi *****
New Type
Change Icon: C:\PROGRA~1\PERL\BIN\PERL.EXE (yellow dot)
Description of type: Perl File
Associated extension: .pl
Content Type (MIME): application/x-perl
Default Extension: .pl
Actions: New: 
	Action: &Open
	Application: C:\PROGRA~1\PERL\BIN\PERL.EXE "%1" %*
	OK
Actions: New: 
	Action: Open with Arachnophilia
	Application: "C:\Program Files\Arachnophilia\arach.exe" "%1"
	OK
OK

***** .php *****
New Type
Change Icon: C:\WINDOWS\SYSTEM\SHELL32.DLL (I like the gear-in-a-window)
Description of type: PHP File
Associated extension: .php
Content Type (MIME): application/x-httpd-php
Default Extension: .php
Actions: New: 
	Action: &Open
	Application: "C:\Program Files\PHP\php.exe"
	OK
Actions: New: 
	Action: Open with Arachnophilia
	Application: "C:\Program Files\Arachnophilia\arach.exe" "%1"
	OK
OK

***** .phtml *****
New Type
Change Icon: C:\WINDOWS\SYSTEM\SHELL32.DLL (I like the gear-in-a-window)
Description of type: PHP File
Associated extension: .phtml
Content Type (MIME): application/x-httpd-php
Default Extension: .php
Actions: New: 
	Action: &Open
	Application: "C:\Program Files\PHP\php.exe"
	OK
Actions: New: 
	Action: Open with Arachnophilia
	Application: "C:\Program Files\Arachnophilia\arach.exe" "%1"
	OK
OK

***** .shtml *****
For perl/cgi scripts to be loaded within an HTML document, the file extension must be one recognized by the server for Server Side Includes (SSI). The suffix .shtml is one such extension, and it doesn't seem to be associated in windows initially to an icon, so I did it myself. This isn't necessary, but if you like pretty icons like I do, you'll want to.

New Type
Change Icon: C:\PROGRA~1\INTERN~1\iexplore.exe (I used the standard explorer doc icon)
Description of type: Microsoft HTML Document 5.0
Associated extension: .shtml
Content Type (MIME): text/html
Default Extension: .html
[Replicate actions from .htm, .html filetypes. You can bring up a second File Types panel from a second folder to cut/paste from one to the other.]
OK

***** Random Thoughts: Tips and Tricks ***************************

********** Tip #1: Calling Perl/CGI scripts within shtml files ***
I had a lot of trouble getting Perl scripts to execute when called from within html files. Here is what I learned:
1) make sure the filetype is one associated with SSI, as noted earlier in the .shtml file association description.
2) Use the right call, the right way. Here's what I found to work:

Explicitly run the Perl executable on the file. It think it requires full path names. This can be placed in the <HEADER> of the shtml doc. e.g.
<!--#exec cmd="c:\progra~1\perl\bin\perl.exe c:\fischer\webdesign\wc-perl\axs-counter\ax.pl" -->

Call it as a cgi. The script location must be referenced from a virtual directory with execute privilege. e.g.
<!--#exec cgi="Perl/AXS-Counter/ax.pl" -->

Include Perl code that address the Document Object Model (DOM) from within HTML <SCRIPT> tags. This requires that the <SCRIPT> tags be placed either in the perl script initially, or surrounding the call to the script. As with the exec cgi call, the file must be referenced from a virtual directory. I have found that in some cases this works, but produces errors that don't occur via the cgi method. e.g.

<SCRIPT LANGUAGE="PerlScript"><!--#include virtual="Perl/AXS-Counter/ax.pl" --></SCRIPT> 

Here is a simple example of the above.

***** start file: test.shtml *****
<HTML>
	<BODY>
		<SCRIPT LANGUAGE="PerlScript">
			<!--#include file="example.pl" -->
		</SCRIPT>
		<BR>And so do I.
	</BODY>
</HTML>
***** end file: test.shtml *****

***** start file: example.pl *****
$window->document->write("Hello world!\n\n");
$window->document->write("PerlScript says: Hello, world!");
***** end file: example.pl *****

********** Tip #2: Thoughts on Installing PWS, Perl, PHP ***
I've done this installation three times now.
PWS crashed near the end of the install until I got mtssetup.exe from Microsoft. Then it went smoothly.
I also have trouble running through the PWS Publish & Web Site if I change the virtual directories first. Of course, since I don't use the Publish feature, it doesn't matter.
It can be hard to find, but there is some really good information in the PWS documentation.

The Perl installation was a breeze. My troubles came from not knowing anything about Perl, nor understanding the difference between generic Perl scripts and scripts that use the Document Object Model, and the nuances of calling scripts via SSI. Once the SSI stuff is setup properly, life gets much easier.

PHP4 installation was a major hassle because the install documentation of this writing is still for PHP3, and does not totally correspond with the PHP4 files. Further, the PHP4 readme.txt differs from the Manual Installation instructions which varies from user comments in the www.PHP.net comments and FAQts. However, when you finally figure out what's going on, it's very simple. Change two lines in php.ini and stick it in the windows dir, move php4ts.dll to windows/system, and edit and run a registry file, reboot. Anything more than that is icing.

********** Tip #2b: Thoughts on Installing PWS, Perl, PHP ***
I just reinstalled PWS after having troubles with a PHP upgrade. Several things: The setup program works as the uninstaller. So copy the pws install files back onto the harddrive, add the alternate mtssetup.dll and then run the setup program to uninstall. I first did a manual uninstall and I think that caused me troubles.

Upon reinstall I had the problem wth PWS installer crashing, as mentioned in Tip #2, even with the modified mtssetup.dll file. What I realized, though, after much effort and manual editing of the registry, is that the MTS program was being installed. So I re-ran the installer, chose Add/Remove and told it to add the PWS software. It finished correctly this time with PWS installed. Things are working again.

********** Tip #2b: Thoughts on Installing PWS, Perl, PHP ***
The comments about installing PHP4 seem to be deprecated. There are install programs available. The php4aspi.dll is not required (the php4ts.dll has worked for me, as has the php.exe in CGI mode). It now seems that placing the dll in the Windows/System directory is discouraged. Instead, just set the Registry key to point to the PHP directory / dll as mentioned earlier (re: ...W3SVC\Parameters\Script Map)

After further efforts, I've found the simplest thing to do is let the PHP installer program run everything. I've had further problems getting PHP to work manually, even following my own instructions. But the installers do a decent job. However, there has been one problem... (see #2c)

********** Tip #2c: Thoughts on Installing PWS, Perl, PHP ***
I had much trouble installing PHP 4.3.0. The server would fail to find the page: no 500 error or anything. Just a generic "can't find server" error. After much hassle, and I found that "cgi.force_redirect=0" must be set in the php.ini file, for this to work with PWS on Win98. This was most obvious with the PHP 4.2.3 files  as they failed to work with an explicit error message about being compiled with forced redirect on. The manual install instructions also mentions this issue in the IIS4 (WinNT) instructions. This is something that should be done by the installer and made clearer in the installation instructions.

Also noted: the installer sets things to work in CGI mode: the php.exe is called by the server, which seems subsequently to rely on php4ts.dll.

I've also found that the php.exe and php4ts.dll files can be manually replaced with other versions (e.g. 4.1.1, what I was using prior to this upgrade). Running the phpinfo function returns the php version number, a simple way to see if things are working and verify the version being used. This ultimately allowed me to track down my problem by switching between the binaries for 4.1.1, 4.2.3, and 4.3.0.

********** Tip #3: Major system malfunction and horrible crashing ***
That said, the first time I tried to install PHP4, I screwed things up and my computer crashed on boot about 15 times in a row. I thought at first I was going to have to do a complete system reinstall. But then I booted in safe mode (press F5 during the boot) and windows loaded properly. Then I restarted, and that fixed things. Moral: Safe Mode is a Happy Place when things go wrong.