Eclipse PHP

Eclipse PHP is Eclipse with the PHP Development Kit (PDT) plugin. Latest release of PDT at the time of writing this article is 2.2 (release in June 2010).

Eclipse PDT provides features for PHP development. The PHP editor has syntax highlighting, code formatting, and syntax verification. With PDT, you can execute PHP scripts and run them on a Web server. PDT also supports debugging PHP files locally and on a server.

We use RMHHomebase1.5 as the running example to demonstrate development tools and configuration settings for Eclipse PHP.

Getting started with a PHP project
To set up a project for PHP development with Eclipse PHP, you need to have the following components in place:

Web server solution stack
A web server solution stack bundles several software applications: web server, database server, and scripting language interpreters. XAMPP is an example of a web server solution stack that is open source, cross-platform, and integrates an Apache web server, MySQL database server, and Perl and PHP interpreters. 
 * Install XAMPP on your hard drive or a thumb drive. For example, C:\xampp or Z:\xampp. See XAMPP wiki article for instructions.
 * Launch XAMPP Control Panel application. It's called xampp-control.exe and located in the xampp directory.
 * Start Apache and MySQL applications by clicking Start buttons to the right of their names on the control panel. A green label called Running shows up to the right of the server application name, and button changes to Stop.

What is document root?
The document root is the directory from where a web server application serves web pages to a browser (web client application). Depending on the type of operating system and web server application, the document root has different locations and names.

In our example, we use XAMPP web server solution stack for Windows operating system. The document root configuration decisions explained here correspond to this particular infrastructure.

What is the default document root for XAMPP on Windows?
XAMPP uses the Apache web server. By default, XAMPP Apache's document root for Windows OS is xampp\htdocs directory. Apache can be configured to recognize other directories as document root directories. Such configuration settings are written in the httpd.conf, the main Apache server configuration file, located in xampp\apache\conf directory.

How do we configure multiple document root directories?
There are three methods to change and/or add other document root directories to the default one:
 * 1) Override  directive. NOT RECOMMENDED!
 * 2) Define other directories, besides the default one, from which the server satisfies browser's requests, and set up aliases to these directories.
 * 3) Define virtual hosts for the same purpose.

How do we define a new document root directory?
We will use method #2 to make Apache serve web pages outside the default xampp\htdocs directory.


 * Open httpd.conf file in Notepad++ for editing. File is located in xampp\apache\conf
 * Define a new directory by writing the following code after the directory definition for xampp/htdocs (typically between lines 200 and 240):
 * Set up an alias to the directory you just defined.
 * Go to the module where aliases are explained.
 * Write an alias directive after the comment block that has an alias directive example. For example, write:
 * Save the httpd.conf file
 * Stop and Start the Apache server from the XAMPP control panel application.

To test your configuration:
 * Write a very simple html file in C:\devel\web directory. Let's call it index.html.
 * Open a browser.
 * Enter the URL  http://localhost/web 
 * The browser displays the message: This document root has the path C:/devel/web!

Project code base
In this tutorial we use the RMHhomebase1.5 project as an example.


 * RMHhomebase1.5 code base is a zip file, RMHHomebase1.5.zip, located at http://sourceforge.net/projects/rmhhomebase.
 * Download this zip file and unzip it with 7-Zip (or other archiving tool)
 * Look for the rmh15 subdirectory and move it in its entirety in one of the directories that have been configured as document root on your computer. In our example, the document root is c:\devel\web. Note: If XAMPP is on a USB drive, the drive letter is not C:\. See XAMPP article about remembering drive letter.

NOTE: If the rmh15 directory has Eclipse and Mercurial configuration files and directories, you have to delete them before you create an Eclipse project with the RMH code base. Look inside the rmh15 directory and:
 * Delete .settings directory (created by Eclipse)
 * Delete .externalToolBuilders (created by PHPUnit Eclipse plug-in)
 * Delete .hg directory (created by Mercurial version control system)
 * Delete .buildpath and .project files (created by Eclipse)

Eclipse workbench
Eclipse PDT package is used for PHP development. Read the Eclipse wiki article on OpenComputing to learn about how to install Eclipse and get familiar with its basic features.


 * Start Eclipse. When Eclipse first opens, it asks you to select a workspace - that's a directory where Eclipse projects will be stored. If the Workspace Launcher window is displayed:
 * Browse to the top-level directory of the project's code base.
 * Select it and it will appear in the Workspace text field. Click OK.


 * A Welcome screen is displayed.


 * Close the Welcome screen by clicking X by the tab's name.
 * PHP Eclipse workbench user interface is displayed. Nothing is shown in any of the frames.

New PHP Project in Eclipse
The first step is to create a PHP Project and populate it with the RMH Homebase code base.

To create a PHP project, select   from the menu bar.


 * New PHP Project window opens up.
 * Type the project's name rmh15.
 * Project is created in the selected workspace, as shown in the Directory text field.
 * Check Enable JavaScript support for this project.
 * Click Finish.


 * Directory structure of the code base appears in the Eclipse PHP Explorer view.

Set up a Run Configuration in Eclipse
The RMH Homebase software is a web-based application and runs in a browser. To test how the application runs, you have to configure a Run Configuration for the rmh15 PHP project.
 * Select   and click on  Default PHP Web Server server definition. NOTE: For Mac, this path is   .
 * Select Edit to start the Edit Server window.
 * Leave the Server tab unchanged. It shows that the URL of the document root(s) is  http://localhost .
 * Select Path Mapping tab and click Add
 * Enter c:/devel/web for the Path on server
 * Browse to the rmh15 project and select it for the Path in Workspace. Click OK.  Press OK once more back at the Edit Server window, saving the changes.

Test it!
To test it, in the PHP Explorer view (left frame)
 * Expand the rmh15 directory by clicking the + sign.
 * Right click on the index.php file
 * Select Run As->PHP Web Page
 * If this is the first time you run any of the PHP or HTML files in the code base as a PHP Web page, a Run PHP Web Page window opens with a Launch URL text field displaying  http://localhost/rmh15/index.php . Click OK.
 * Object not found! error is displayed.

How to fix it
Eclipse tells Apache to serve pages from:
 * C:/devel/web by using the URL http://localhost/rmh15/index.html.

However, Apache is configured to serve pages from:
 * C:/xampp/htdocs, whose URL is http://localhost
 * C:/devel/web, whose URL is http://localhost/web

We need to add a new alias in the httpd.conf file to resolve the URL http://localhost/rmh15.
 * Open httpd.conf
 * Add the directive.
 * Save the file.
 * Restart Apache server application from the XAMPP control panel.

Run again index.php as a PHP Web Page. If successful, the login page of this application is shown in the Eclipse editor. 

Run PHP web pages in an external browser
To run PHP web pages in a browser and not in Eclipse
 * Select Windows->Web Browsers...
 * Pick something else other than Internal Web Browser. It can be the default system browser, Firefox, etc.

NOTE: If you configure the web browser for running PHP web pages the first time, selecting Windows->Web Browsers... could take a long time. Be patient! It took me a few minutes to see the options from which I could select another browser.

Create database and user accounts
Start MySQL server application. Use XAMPP Control Panel and click Start.

Test MySQL server application

 * Open Windows command prompt utility. If you don't know what this utility is, learn about Command Prompt.
 * Type mysql - u root -p. When prompted to enter password, click Enter. If you changed the root superuser account to use a password, type in the password. If you don't know how to use it, learn about MySQL Utility.
 * If you get an error saying that mysql command is not recognized, learn about the PATH system variable and how to set it to list C:\xampp\mysql\bin directory.
 * At mysql prompt type show databases;
 * A list of databases is displayed.

Create user accounts and a database
Write a SQL script to create the database and local and remote user accounts for the RMH application:
 * In Notepad++ type in the following code:

mysql>source c:\devel\web\rmh15\sqlcode\create_db_and_user.sql The output from executing this script is: Query OK, 0 rows affected, 1 warning (0.00 sec)
 * In rmh15 directory, create the subdirectory sqlcode, and save this script as create_db_and_user.sql file.
 * In Windows command prompt, launch mysql utility and at the mysql prompt type:

Query OK, 1 row affected (0.01 sec)

ERROR 1396 (HY000): Operation DROP USER failed for 'rmh15DB'@'%' ERROR 1396 (HY000): Operation DROP USER failed for 'rmh15DB'@'localhost' Query OK, 0 rows affected (0.00 sec)

Query OK, 0 rows affected (0.00 sec)

Query OK, 0 rows affected (0.00 sec)

Query OK, 0 rows affected (0.00 sec)

mysql>

Test it!

 * Exit the MySQL server application (type exit)
 * Log in again to the MySQL server, only this time specify rmh15DB as the user. When prompted for the password, type rmh15DB.
 * List the databases to which rmh15DB has access
 * Use show databases;.
 * rmh15DB is listed along with test and information_schema databases.
 * Check the privileges granted to the rmh15DB user.
 * Use show grants;
 * Usage and database scope privileges are shown for this user.

Create database tables
To create the database tables in the rmh15DB database, run the dbinstall.php script. In the PHP Explorer view:
 * Expand the rmh15 directory
 * Expand the database subdirectory
 * Run dbinstall.php as a PHP Web page

Either the Eclipse internal browser or the browser you have selected to run PHP pages displays a status report that lists the tables that have been created: Installing Tables... connected... database selected... dbWeeks added... dbSchedules added... dbShifts added... dbDates added...

Admin account created. username = admin, password = admin. dbPersons added... dbSCL added... dbLog added... Installation of mysql tables complete. To prevent data loss, run this program only if you want to clear all the tables.

Populate tables with sample data
To load the dbPersons and dbSchedules tables in the rmh15DB database with 71 persons and 100 master schedule entries, run the script dbInstallsandbox.php as PHP Web page. This operation might take a while. The first and last few lines of the output that gets displayed in the browser are: my_group=One; day=Mon; time=9-12; slots=2; persons=,jane2077291234,linda2077291234; notes=; my_group=Two; day=Mon; time=9-12; slots=2; persons=,jane2077291234,cathy2077291234; notes=; my_group=FamOne; day=Mon; time=9-12; slots=1; persons=; notes=; ... my_group=Wkd; day=Sun4; time=9-12; slots=1; persons=,gayle2077291234; notes=; my_group=Wkd; day=Sun4; time=2-5; slots=1; persons=; notes=; my_group=Wkd; day=Sun4; time=5-9; slots=1; persons=,leeann2077291234; notes=; my_group=Wkd; day=Sun5; time=9-12; slots=1; persons=; notes=; my_group=Wkd; day=Sun5; time=2-5; slots=1; persons=; notes=; my_group=Wkd; day=Sun5; time=5-9; slots=1; persons=,chris2077291234; notes=; id=jane2077291234; first_name=jane; last_name=jones; address=14 Way St; city=Harpswell; state=ME; zip=04079; phone1=2077291234; phone2=; email=jane@bowdoin.edu; type=volunteer,sub; background_check=; interview=; shadow=; convictions=; wherelived=; experience=; motivation=; specialties=; availability=Mon9-12,Thu3-6; schedule=,OneMon9-12,TwoMon9-12,OneThu3-6; history=; birthday=02-19-89; start_date=03-14-08; public_notes=; my_notes=; private_notes=; password=631521b9243a2c3395e93be81af38532; id=linda2077291234; first_name=linda; last_name=jones; address=14 Way St; city=Harpswell; state=ME; zip=04079; phone1=2077291234; phone2=; email=linda@bowdoin.edu; type=volunteer,sub; background_check=; interview=; shadow=; convictions=; wherelived=; experience=; motivation=; specialties=; availability=Mon9-12,Tue6-9,Wed9-12; schedule=,OneMon9-12,TwoTue6-9,OneWed9-12; history=; birthday=02-19-89; start_date=03-14-08; public_notes=; my_notes=; private_notes=; password=704095bbe351df5fb11474acb4279e1a; Sandbox installed

Test it!

 * Run the index.php script as a PHP web page.
 * A login page is displayed
 * Enter admin and admin for user name and password
 * A welcome page is displayed with a prompt to change the password.

If you see errors on this page, this is because the PHP engine is configured to display any type of error, including warnings and notices. As you learn more about PHP programming, you will be able to figure out and fix these errors.

Setting up a debugging tool
See the Xdebug page for a discussion on this topic.

Setting up a unit testing tool
See the SimpleTest page for a discussion on this topic.

Setting up documentation tool
See Doxygen wiki article.