Install and use phpLaunch

What is PHPLaunch?

PHPLaunch is a Windows program that allows you to use PHP script-based webpages like PhpGedView. With PHPLaunch on your computer you can view and edit PhpGedView without the need to install a web server. The difference between a web server and PHPLaunch is that PHPLaunch is only available on your own computer and can not be visited by others through the internet, so on-line editing is not possible. PHPLaunch can also be burned on a CD to transport PhpGedView to another computer. Because PhpGedView "writes back" to its parent, you can't easily run PHPLaunch from a CD. If you have copied PHPLaunch from a CD to your hard drive and want to edit it, you may need to turn off the "read-only" attributes.

What is this guide?

This installation guide will walk you step-by-step through installing and upgrading PHPLaunch, so you can use PhpGedView on your computer or burn it on a CD and give it away to family members. Don’t be afraid to try this out. It’s much easier then you think! This guide will help you with pictures and easy-to-read text.

Will this guide help me?

This guide was written after some PHPLaunch installation tests. But you can also use it as a reference with other versions and different configurations. The following configurations have been tested.

Hard drive installation

• PhpGedView 3.8.8
  • PHP and PHP pecl 5.1.2 version
    • Index files (simple)
    • SQLite database (recommended)
    • MySQL database 5.0.18 (advanced)
    • Microsoft SQL Server 2005 Express (not recommended, compatibility fault with PHP)

• PhpGedView 4 Beta 4 (not recommended)
  • PHP and PHP pecl 5.1.2 version
    • Index files (unavailable)
    • SQLite database (unavailable)
    • MySQL database 5.0.18 (not recommended, surfing problems)
    • Microsoft SQL Server 2005 Express (not recommended, compatibility fault with PHP)

• PhpGedView 4.0.1
  • PHP and PHP pecl 5.1.4 version
    • Index files (unavailable)
    • SQLite database (unavailable)
    • MySQL database 5.0.22 (for advanced users)
    • Microsoft SQL Server 2005 Express (not recommended, compatibility fault with PHP)

CD installation

• PhpGedView 3.8.8
  • PHP and PHP pecl 5.1.2 version
    • Index files (simple)
    • SQLite database (recommended)
    • MySQL database (not recommended)
    • Microsoft SQL Server 2005 Express (not recommended, compatibility fault with PHP)

• PhpGedView 4 Beta 3 (not recommended)
  • PHP and PHP pecl 5.1.2 version
    • Index files (unavailable)
    • SQLite database (unavailable)
    • MySQL database 5.0.18 (not recommended, surfing problems)
    • Microsoft SQL Server 2005 Express (not recommended, compatibility fault with PHP)

• PhpGedView 4 Beta 4 (not recommended)
  • PHP and PHP pecl 5.1.2 version
    • Index files (unavailable)
    • SQLite database (unavailable)
    • MySQL database (not recommended and surfing problems)
    • Microsoft SQL Server 2005 Express (not recommended, compatibility fault with PHP)

What do I need to start?

You need to download the following files

1. PHPLaunch
2. PHP zip package
3. PHP pecl modules package
4. PhpGedView

PhpGedView and PHPLaunch: http://sourceforge.net/projects/phpgedview/ [1]
PHP and PHP pecl package: http://www.php.net/ [2]

You need to download PHP and PHP pecl to upgrade PHPLaunch and to get a few extensions (DLL files) to make PhpGedView work properly. Always use the same version with PHP and PHP pecl.

For more advanced database like MySQL for Hard drive installation: http://www.mysql.com/ [3]
(You are on your own!)

Are you running a web server with php?

If you have a web server installed and running with php on your computer, than I suggest that you temporarily shut it down during this installation. Or use another computer.
If you have your php.ini in a global folder, like “C:\WINDOWS”, than it’s a good thing that you rename the php.ini file, otherwise PHPLaunch will use that php.ini file instead of what you will configure later.
If you would start up PHPLaunch with a running web server and php installed, the error page in the PHPLaunch would be:
“The page can not be found”, “HTTP 404 – File not found”

Install PHPLaunch

Make a “temp” folder on your hard drive “C:\”
Find the downloaded PHPLaunch zip file and extract it to “C:\temp” folder.
See Figure 1

PHPLaunch, figure 1

You can test “PHPLaunch.exe” now. Double click on the file as shown here.
If you see error messages, see Figure 2 and “Page not found” in the PHPLaunch window, than you have NOT renamed the php.ini in “C:\WINDOWS”.
Stop your web server and rename “C:\WINDOWS\php.ini” to something else

If you have followed the instructions, you will see Figure 3.

Figure 3

As you can see on the picture, “C:\temp\php.ini” has been loaded correctly.

Upgrading PHPLaunch with PHP

The currrent PHPLaunch package includes PHP version 5.0.3. We will update this to the latest version and get the extensions (DLL files) that we will need for PhpGedView.

Make a “php” folder on your hard drive “C:\”
Find the downloaded PHP zip file and extract it to “C:\php” -folder.
Mark and copy these files in the “C:\php\” -folder:

• php5ts.dll
• php.ini-recommended
• php-cgi.exe

See Figure 4

PHPLaunch, figure 4

Paste the copied files into the “C:\temp\” folder and overwrite the old files. See Figure 5

PHPLaunch, figure 5

If you start up “PHPLaunch.exe” now, you will see that now we have the latest PHP version installed.
In this case, it is the version 5.1.2. See Figure 6

PHPLaunch, figure 6

PHP has a folder called “C:\php\ext\”. In this folder you can see a bunch of DLL files and some of them are needed to use PhpGedView.
Sometimes PHP includes in their own package the DLL files that you need to run PhpGedView but these change from time to time. If a DLL file is missing from the PHP package then you will find it in the PHP pecl package.

Find the downloaded PHP pecl zip file and extract it to “C:\php\ext” folder.

Which extensions (DLL files) you need depends on how you want to use PhpGedView. With “Index files” you don’t need any database extension.

PhpGedView 3.8.8
General extensions you’ll need

• php_gd2.dll
  
• php_mbstring.dll
  

Database extensions with SQLite database

• php_pdo.dll
  
• php_sqlite.dll
  

Select and copy all the DLL files you need in the “C:\php\ext\” folder.
Make an “ext” folder in “C:\temp\” and paste the copied files there.

Example for PhpGedView 3.8.8 with SQLite database. See Figure 7

PHPLaunch, figure 7

You can of course copy the whole PHP directly to the “C:\temp\” folder and PHP pecl to “C:\temp\ext\ folder if you have plenty of space.
This example is using only the minimal requirements.

How to configure php.ini for PHPLaunch

Php.ini is the PHP‘s configuration file. PHP read this file to know what to do.
When you make a change in this file you have to shut down your web server, PHPLaunch and other programs that using PHP or the changes will not take place.

We want to update php.ini to the latest version as well, just in case.
Delete “C:\temp\php.ini”
Rename the file “C:\temp\php.ini-recommended” to “php.ini”.
Open to edit “C:\temp\php.ini” with notepad or another text editor.
Find:

max_execution_time = 30

and change to:

max_execution_time = 120

This will increase a scripts execution time limit to 120 seconds. You can change this to a higher value if needed.

Find:

extension_dir = "./"

and change to:

extension_dir = "ext"

This will tell PHP where are all the extensions (DLL files)

Go the “Dynamic Extensions” section.
Here you will find many lines that start with something like

extension=xxxyyy.dll

Here we will enable or write in all the extensions we need to tell PHP what to use, how to work. These are the extensions that we have already copied to “C:\temp\ext\” folder. See Figure 7 in the “Upgrading PHPLaunch with PHP” section

Enable the following extensions by removing the “;” at the beginning of the line, like this:

extension=php_mbstring.dll
extension=php_gd2.dll

As an example, this guide is using SQLite database with PhpGedView, then we need the following extensions exactly in this order. If you write these lines in the wrong order you will receive error messages.

extension=php_pdo.dll
extension=php_sqlite.dll

If you need other extensions, enable or write them here.

Start up “PHPLaunch.exe” and control if these extension has been loaded.
If they have been correctly loaded, you will see “gd”, “mbstring” and “SQLite” on the page.
Example for “mbstring”, see Figure 8

PHPLaunch, figure 8

Install PhpGedView

Find the downloaded PhpGedView zip file and extract it to “C:\temp\web\” -folder.
Example for PhpGedView 3.8.8. See Figure 9

PHPLaunch, figure 9

Now you can start up “PHPLaunch.exe”
If everything is right, in this example PhpGedView 3.8.8 will start up.
See Figure 10

PHPLaunch, figure 10

Congratulations! DON’T SKIP THESE LINES! IMPORTANT!

As you can see on the picture, the “Configuration help” window pops up. Do not close this window!
For some reason this window allows you to make selections in the boxes. If you close the window, you will get this error message and you will not be able to choose any boxes, see Figure 11 or see Figure 13

If you close the “Configuration help” window by mistake, don’t worry, you can either push “F5” on your keyboard to refresh the window or just shut down “PHPLaunch.exe” and start it again and this time don’t close the window.

It’s time to copy all the files you need to run PhpGedView.
Copy your GEDCOM record to “C:\temp\web\index\” folder.
You can even use GEDCOM record that has been updated with Beta 4 versions. I have tested them up to 4.0 Beta 4
Copy your multimedia files to “C:\temp\web\media\” folder.

Caution
If you are planning to have PhpGedView on a CD and give it away and have sensitive information in your GEDCOM file then it’s time to delete them. The GEDCOM record is just a text file that can be viewed by anyone with a text editor.

When you are finished with all the copying, you can start up “PHPLaunch.exe” and start with the configurations.

Please follow the PhpGedView manual on how to configure PhpGedView.

To use PHPLaunch:

1. Make a desktop shortcut to PHPLaunch.exe, and you will have a convenient start-up
   

To admininister PHPLaunch:

1. Open PHPLaunch as in the step above
2. Open your web browser and point it to http://localhost:32123/index.php
   
3. Log in as administrator, and you can edit, add, subtract and generally modify your file
   

Tested with Internet Explorer 6 and PhpGedView 3.8.8

CD or hard drive installation?

- PhpGedView on your hard drive doesn’t need any special consideration to run. You can view, edit, upgrade. You have no limitations.

- If you are planning to have PhpGedView only an a CD
PhpGedView is trying to write always to some files, that means you will have warning messages because a CD is a Read-Only media. So it’s a good thing to disable all kind of writings made by PhpGedView like logging, online-editing.
Before you burn this project to a CD you can test it by marking all the files under the “C:\temp\web\index\”, right-click with the mouse, choose “Properties” and mark the “Read-only” attributes.
PhpGedView will try to write to these files so you will see all the warning messages. Don’t waste your CD’s for testing until you reduce the warning messages.
PhpGedView has no functions to check if the installation is on a read-only CD or on your hard drive.

- So why burn it on a CD if you get annoying warning messages?
The good thing with the CD installation is that you can give it away to your family members, which is the whole idea. Just tell them to copy the whole CD on they hard drive before they want to use it. Then they will enjoy it in a warnings free environment.

When you are ready with everything, you can burn all the files and folders under “C:\temp\” –folder to your CD.
See Figure 12

PHPLaunch, figure 12

If you are distributing PHPLaunch by CD and want to give it all a professional appearance, have a look at http://www.jrsoftware.org/isinfo.php This allows you to present a Windows-installer look alike "wrapper" to your information, and makes installation a breeze. The software is free.

Problems?

Use this as guidelines and not as an absolute problem solver.

-- At start of PHPLaunch:
“The page can not be found”, “HTTP 404 – File not found”

-You have a php.ini file in your “C:\WINDOWS\” –folder.
Rename that php.ini –file to something else, while you are using or installing PHPLaunch.

---

“The procedure entry point yyy could not be located in the dynamic link library xxx.dll.”

-You have a php.ini file in your “C:\WINDOWS\” –folder.
Rename that php.ini –file to something else, while you are using or installing PHPLaunch.
Or
-The xxx.dll –file is another version than PHP
See “Upgrading PHPLaunch with PHP” section.

---

At start of PHPLaunch
In the main window:
“Your current database configuration is bad. Please check your database connection parameters and configure again.
DB Error:extension not found [DB Error:extension not found]**Array”
and
In the pop-up window:
“PHP Warning: PHP Startup: Unable to load dynamic library 'xxx\php_ sqlite.dll' - The specified module could not be found. in Unknown on line 0”

-You have a php.ini file in your “C:\WINDOWS\” –folder.
Rename that php.ini –file to something else, while you are using or installing PHPLaunch.
Or
Check your php.ini that - extension_dir = "ext" - is correct
Or
Check your php.ini for the extension=php_pdo.dll, in this case. If it is misspelled or missing from your php.ini.
See “How to configure php.ini for PHPLaunch” section.

---

In the main window only.
“Your current database configuration is bad. Please check your database connection parameters and configure again.
DB Error:extension not found [DB Error:extension not found]**Array”

-You have a php.ini file in your “C:\WINDOWS\” –folder.
Rename that php.ini –file to something else, while you are using or installing PHPLaunch.
Or
Check your php.ini that - extension_dir = "ext" - is correct
Or
You want to use “Index file” as your database. Ignore this warning and continue.
See “How to configure php.ini for PHPLaunch” section.

---

“Internet Explorer Script Error” or “A Runtime error has occurred”

Which error message you receive depends on your systems installation but it’s the same thing.
And the “URL: http://localhost:32123/xxx.php“can be different. Depends on where you are…
See Figure 13

Or, see Figure 11

- You have probably closed a pop-up window.
Click “Yes”
Or
Press or “F5” on your keyboard to refresh the window or close PHPLaunch and start it up again.

---

“php-cgi.exe – Unable To Locate Component”
See Figure 14

-Check your php.ini for the extension=php_pdo.dll, in this case. If it is misspelled or missing from your php.ini.
See “How to configure php.ini for PHPLaunch” section.
Check also if this file is missing from your folder. In this installation example “C:\temp\ext\”.
See Figure 7

---

Warning in the pop-up window. And no warnings in the main window.
“PHP Warning: PHP Startup: Unable to load dynamic library 'ext\php_sqlite.dll' - The specified module could not be found. in Unknown on line 0”

-Check your php.ini. It is possible that you wrote some lines in this order:

extension=php_sqlite.dll
extension=php_pdo.dll

Switch these two lines.
See “How to configure php.ini for PHPLaunch” section.

---

Can not edit the Welcome page. The error message is:
Access Denied
You do not have access to this resource.

-Start PHPLaunch
-Start Internet Explorer and type in the address bar:
http://localhost:32123/index.php

Now log in and continue to edit.