Introduction

In this article you learn about a prototypical development process for writing PHP code, including the creation of PHP files, code debugging cycle, and sharing of files with team members. This process takes place within the context of the Eclipse development environment and uses the features of the PHP integrated development environment (IDE) project and CVS.

Information in this article should not be interpreted as a rigid set of development guidelines that must be followed, but rather as a place to start when doing your own development within Eclipse.

Eclipse terminology

In Parts 3 and 4 of this series, you learned to install and configure the Eclipse development environment for Windows® and Linux®, respectively. You should be familiar with the following Eclipse terminology:

Plug-ins

Functionality packaged together that can extend or be extended by others

Features

A collection of plug-ins for download and installation (This simplifies the packaging and distribution of plug-ins.)

Perspectives

An Eclipse configuration that includes several views that work together to support a specific task (There are perspectives for working with PHP coding, Java™ coding, CVS, and so on.)

Views

A view is part of a window frame that provides one function to support the task of the perspective it is in (Views typically provide information about the project you are working with, such as explorers, outlines, consoles, and more.)

Editors

A type of view used to edit content that is associated with a particular file type, such as PHP editor, Java editor

Figure 1 shows the Eclipse PHP IDE that you will be installing and configuring in this article to write and debug PHP code.

In this article you'll create a new module in our project, learn how to debug it, and finally, share it with co-developers using CVS.

Writing PHP

During the installation of Eclipse, you learned how to create a project and import the files to your Web site. When creating the custom Announcements module, you learned how to create new PHP files.

When writing your PHP code, it is helpful to provide documentation of the functions. phpDocumentor is helpful in the writing stage of PHP development. It is a tool, written in PHP, designed to create documentation directly from both the PHP code and external documentation. Additional markup is added to comment regions to provide more information. Knowledge of PHP is used to generate the documentation as well. phpDocumentor generates manual-format documentation by reading it from DocBlocks -- special PHP comments. DocBlocks allow the writer of PHP code to provide appropriate information for documentation.

HTML Tidy is another tool that might be useful in writing HTML code. HTML Tidy cleans up HTML code by finding and fixing mistakes in markup. It also has limited support for PHP and XML. Eclipse is useful in finding markup errors by colorizing the code appropriately.

Back to top

Installing and configuring the PHP debugger

There are many ways you can debug your Drupal modules during their development. Methods using var_dump and print_r are perfectly valid and definitely have their place in your testing process. However, using a full-fledged debugger is a very powerful tool for understanding how code works, discovering problems, and solving functional issues. In the following section, you'll learn to install, configure, and use a debugger within your Eclipse environment.

Choosing a debugger

In Parts 3 and 4 you explored how to install PHPEclipse, an Eclipse feature that provides an IDE perspective to develop PHP-based projects. If you are using the correct version of PHP, you can install and configure the DBG debugger to work with your Eclipse setup. Another option is to use the XDebug debugger.

A third option is Zend's PHP development environment for Eclipse that incorporates the Zend debugger. (You can read more about the PHP IDE project at Zend or Eclipse.) In the rest of this section, you learn how to install, configure, and use the Zend tool to help you debug a Drupal module. We'll use the Announcement module as an example.

Disabling the PHPEclipse feature

Assuming you have installed PHPEclipse, you can either disable or uninstall this feature. First, open the Manage Configuration dialog through the Help > Software Updates > Manage Configuration menu, as shown in Figure 2.

This dialog, as shown in Figure 3, lists the features (collections of plug-ins) for your Eclipse installation. You should see the PHPEclipse feature in the list; select it to view more information.

Right-click PHPeclipse in this list to display a context menu that provides the option of disabling or uninstalling this feature. For now, you can simply disable this feature. Follow the prompts and restart Eclipse to complete the process.

Installing PHP IDE and the Zend debugger

First, install the PHP IDE feature. Start Eclipse, and open the Find and Install dialog (Help > Software Updates > Find and Install).

Check Search for new features to install and click Next. To add a new Update Site, click New Remote Site, and enter the update URL along with the description of the project. At the time of this writing, the update URLs described in the Zend or Eclipse PHP IDE project pages are http://downloads.zend.com/phpide and http://download.eclipse.org/tools/php/updates/. Add the Zend update URL like that shown in Figure 4.

When the Update URL is added, make sure the PHP IDE list item is the only one checked and click Finish. Eclipse now looks up which new features are available and presents you with a dialog like the one in Figure 5.

This represents what features are available from the URL you added. Check both the PHP IDE and Zend debugger features. Click Finish and Eclipse will attempt to install these new components. You are then presented with a dialog asking you to accept the terms and conditions of the license for these new features. Check Accept and click Next. A list of what will be installed is presented in the next dialog. Click Finish to continue the installation.

While the components are being downloaded and installed, the progress dialog, shown in Figure 6, gives you the option of running this process in the background while you continue to work within Eclipse.

After installation, Eclipse will display the dialog shown in Figure 7 to restart itself in order to activate the new features.

The new PHP IDE perspectives

As shown in Figure 8, Eclipse will now show two new items listed in the perspective dialog: the PHP and PHP Debug perspectives.

The PHP and PHP Debug perspective icons look slightly different than the PHPEclipse perspective (not shown here) and provide a new layout for your PHP development. Figure 9 shows this new perspective.

Select the new PHP perspective while viewing an existing PHP project. You'll notice several new panes, such as the PHP Explorer, PHP Project Outline, and PHP Functions. If the Outline pane is not displaying any of the functions in a PHP file you're editing, migrating your project will fix that.

Migrating an existing PHPEclipse project to PHP IDE

If you have followed Parts 3 or 4, you should have a PHPEclipse project set up. To take advantage of the features in the PHP IDE perspective, you will need to make some minor changes to your existing project file, .project, which is in the project directory under the Eclipse workspace. This is a hidden file so you can manually edit it with File > Open, or edit it outside of Eclipse in a standard text editor. This file should look similar to Listing 1.

<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
	<name>drudal.development</name>
	<comment></comment>
	<projects>
	</projects>
	<buildSpec>
		<buildCommand>
			<name>net.sourceforge.phpeclipse.parserbuilder</name>
			<arguments>
			</arguments>
		</buildCommand>
	</buildSpec>
	<natures>
		<nature>net.sourceforge.phpeclipse.phpnature</nature>
	</natures>
</projectDescription>
	

Within the buildSpec and natures section of this XML file you will notice the references to two PHPEclipse classes. Change these to the PHP IDE classes, as shown in Listing 2.

<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
	<name> drudal.development </name>
	<comment></comment>
	<projects>
	</projects>
	<buildSpec>
		<buildCommand>
			<name>org.eclipse.php.core.PhpIncrementalProjectBuilder</name>
			<arguments>
			</arguments>
		</buildCommand>
	</buildSpec>
	<natures>
		<nature>org.eclipse.php.core.PHPNature</nature>
	</natures>
</projectDescription>
	

To enable the text colorization for .module files (and .inc and .engine files), you will have to edit the Eclipse preferences. Open the preferences dialog from the Window > Preferences menu. In the filter field in the upper left, enter type and select Content Types under General. Select the PHP Content Type. You will see a number of file extensions (.php, .php3, .php4, and so on) listed. Select Add to add *.module as a file association. See Figure 10 for details.

While in the preferences dialog, you can control which browser is used when you begin to debug the file. Under the General / Web Browser category, you can select which browser to use -- an external or an internal one. If you select the external browser, you can choose which of the browsers that are installed to use.

Now, if you restart your Eclipse application, your PHP project should take full advantage of the PHP IDE features, including the Outline pane.

Installing and configuring the server side of the Zend debugger

An additional part of the Zend debugger needs to be installed as part of your PHP installation so that Eclipse PHP Debug perspective works. At the bottom of the Zend PHP IDE project page mentioned above, there is a link to Zend debugger extension binaries for various platforms, as shown in Figure 11.

Clicking this link displays a list of downloadable files for their associated platform, such as ZendDebugger-5.2.1-Windows-i386.zip for Windows XP. Download this file and unzip it into a temporary directory. Follow the directions in the README file. For Windows, this means placing the dynamic link library (DLL) into the PHP extension directory, C:\php\ext created in Part 3, and updating the PHP configuration php.ini with the additional lines in Listing 3.

zend_extension_ts=c:\php\ZendDebugger.dll.
zend_debugger.allowed_hosts=localhost
zend_debugger.expose_remotely=always
	

See core php.ini directives for a description of other directives.

To enable a new extension, restarting Apache is normally required.

Back to top

Debugging PHP

Now that all the parts of the PHP IDE and Zend debugger are in place, you'll set up a debug session using a current Drupal project within Eclipse. So that we can see the debugger running, we need to set a breakpoint that will be encountered in the HTTP request life cycle. For this example we'll use the index.php file. This is the first file called on the server side in the request to a Drupal installation.

Creating a breakpoint

Open the index.php file in your project. You can toggle a breakpoint by double-clicking the gray margin beside the line of code. A breakpoint is set on the line where the Drupal bootstrap is initiated, as shown in Figure 12.

Configuring a debug session

Now you need to configure a debug session. Click the down arrow next to the bug icon in your Eclipse window, as in Figure 13, and select Debug.

The debug configuration dialog is now displayed, as shown in Figure 14. Click the PHP Web page item listed in the pane on the left to start the creation of a new debug session.

Enter a configuration name, such as Watch a Drupal request. To edit the details of the server, click Configure. A dialog like the one shown in Figure 15 is displayed.

Give the server details a name; for example, Drupal development server. Complete the URL field for the development server and path of the Eclipse workspace you defined in Part 3 or 4, and click OK.

Back on the debug configuration dialog, enter the File/Project field with the project name you defined in Part 3 or 4. Make sure you check Auto Generate. The dialog should look similar to Figure 16.

Running a debug session

Now click Debug. Eclipse will try to switch to the PHP Debug perspective. The dialog in Figure 17 is displayed. You might want to check Remember my decision so that this doesn't appear each time you run a debug session.

The perspective changes to look like the one shown in Figure 18.

A new browser window is also opened as the HTTP request prepares to render the Web page.

The debug view, shown in Figure 19, controls the progress and displays backtrace and status of the debug session. You can stop, suspend, resume, and step through code line by line using the controls along the top.

The Variables view in Figure 20 provides a live list of variables defined by the code as the debug session progresses. By clicking the value of a variable, you can change its value while a debug session is suspended at a breakpoint.

To step into the code line by line, press F5. As you debug your code, you'll notice the middle view provides the PHP file with the active line of code currently being computed as highlighted. In our example, pressing F5 just after the debug perspective displays causes the first line of the drupal_bootstrap function within the bootstrap.inc file to display. If you wanted to step over the function call to drupal_bootstrap in the index.php file, you would have used the step over action, or F6. This step would have taken you to the next line in the index.php file.

If you want to return from the drupal_bootstrap function without having to step through all the remaining lines of code until you reached the return at the end, you can use the step return action, or F7.

Any warnings or errors that occur during the debug session appear in the Console pane.

As you go through this HTTP request, you can watch how the database connection is created, how the user session is created, how the Drupal variables are defined, and how the Web page is created -- resulting in a rendered Web page in the Web browser. This is a very simple example designed to get you started using the PHP IDE debugger.

Back to top

Tracking code changes

You learned in Part 3 that Eclipse provides excellent support for managing code changes in CVS. This section covers some of the common usage scenarios we encountered while developing the IBC site. We will not delve into the details of CVS' more advanced features (such as branching and merging), but when you are ready to use those features you can do so from within Eclipse.

The general workflow for using CVS in Eclipse is to:

• Create a CVS repository connection.
• Import or check out source code.
• Make changes to the source code.
• Synchronize your changes with the CVS repository.

These four items form the core of how CVS allows developers to coordinate on their project. Let's start by adding a new CVS repository connection inside of the Eclipse workspace.

Open the CVS Repository Exploration perspective, and your screen should look similar to Figure 21. On the left is the CVS Repositories view, which displays all of the CVS repositories that Eclipse knows about. Right-click inside the CVS Repositories view and choose New > Repository location, as shown in Figure 22.

A dialog opens that allows you to enter the details about the CVS repository. You can see an example of this dialog, complete with the necessary repository information, in Figure 23.

We filled out the location information with the hostname of the server and the directory on that server that contains the CVS repository. Enter your username and password; then choose the connection type for this CVS repository. There are two popular mechanisms for connecting to a CVS repository. The one selected in Figure 23, extssh, is generally accepted as more secure and preferred over the other connection types. The second popular one is the standard connection type provided by CVS, called pserver. Contact the system administrator if you don't know which connection type to select.

Now that you have added a CVS repository connection, it's time to share your project on the CVS server. This is easily done through an Eclipse wizard that's accessed from the Share Project menu item under Team, as shown in Figure 24.

You are prompted to select the CVS repository that will store your source code. Choose the repository we just created and click Next, as shown in Figure 25.

You now must enter a module name that will identify this project on the CVS server. The dialog should look similar to Figure 26. Choose Use project name as module name unless you have a specific reason to create your own or to use an existing module.

At this point you are prompted to review the code that will be imported into the CVS repository. The dialog in Figure 27 allows you to examine every file and directory that will be sent to the CVS repository. Verify that everything is correct, that Launch the Commit wizard is checked, then click Next.

The Eclipse CVS client attempts to guess what kind of content is stored in the files it is sending to the CVS repository. This is easy for things like PHP source files because they are a known file type. There are cases where you are importing a file into CVS and Eclipse does not know anything about that file. When this happens, you can assist Eclipse in classifying what kind of content is in the file - either text data or binary data. Figure 28 shows an example dialog that lists file types that are unknown to Eclipse. All of these files in the Drupal project are ASCII Text and should be stored in the CVS repository as ASCII Text. Click Next when you have made the necessary changes.

Figure 29 shows the final step in the import process. You have the option to review the files again, and you can also enter a comment that describes what and why you are committing these files. You should always enter a meaningful message when committing your changes to the CVS repository. Click Finish when you have entered your commit message.

Now that you have your source code resides in a CVS repository, you can make any and all necessary changes while preserving previous versions for comparison and regression testing. Once you have finished writing and testing your code you can commit it to the CVS repository. We are going to focus on the Synchronize with Repository method for sending your changes to the CVS repository and for receiving any updates from your team members. There are cases when it is useful to update or commit a single file rather than synchronizing an entire project. Before describing how to synchronize your project with the CVS repository, let's look at committing and updating a single file.

In Figure 30 you can see the Team menu (found by right-clicking on a file or directory within the project), with the items Commit and Update. Choosing Commit sends your changes to the CVS repository, while Update retrieves any changes from the CVS repository. In both cases, CVS will attempt to merge your version with the version in the repository. If for any reason CVS is unable to merge your version of the file with the CVS repository's version of the file, it forces you to process the merge manually. (This process is outlined in the CVS documentation.)

Synchronizing with the repository

Now that you and your team have made changes to your code, you need to send and receive those changes from the CVS repository. As mentioned, it is possible to update and commit individual files, but that process is not efficient if you have made many changes. The proper way to send and receive large numbers of changes is to use the Synchronize with Repository Team menu item. This switches you to the Team Synchronizing perspective and determines what differences exist between the version of the source code on your local computer and the version of the source code in the CVS repository. Figure 31 shows the Synchronize with Repository menu item.

The Team Synchronizing perspective is shown in Figure 32. This perspective provides an overview of the changes and allows you to examine the changes to an individual file. On the left of the screen is the Synchronize view, which contains a listing of all the files that need to be synchronized. This view has four modes that filter the files we are synchronizing.

Figure 33 shows the buttons that activate the four modes.

The four modes, shown in Figure 33, are:

Make sure you are in Incoming/Outgoing Mode so you see the changes that you and your team members have made. You can see whether or not a file is outgoing or incoming by examining its icon. A right arrow, gray in color, indicates an outgoing change while a left arrow, blue in color, indicates an incoming change. Arrows with a plus sign (+) indicate that a file is being added, and arrows with a minus sign (-) indicate that a file is being removed. Arrows without a plus or minus sign signify a change has been made, with the direction of the arrow indicating where the change was made. Figure 34 shows examples of these icons.

Now that you understand the information presented in the Synchronize view, you must act on it. Right-click a file or directory, and you'll see a menu that looks like Figure 35.

There are two menu items that you will frequently use:

Update

Merge changes between the local copy and the copy in the repository.

Commit

Commit the local changes to the repository.

Use the Update menu item when you want to have CVS automatically merge changes between your local source file and the repository. Use this when you have made changes to your local file and a team member has made changes to the same file but has already committed their changes to the repository. Once you have updated the source file, you must commit the changes back to the repository. Use the Commit menu item to send your changes to the repository. This menu item is used when you have made changes to your local file and no one else has committed changes to the same file in the repository.

Sometimes you need to examine the differences between your local file and the file in the repository. If you open any of the files found in the Synchronize view the compare editor will open. Figure 36 and Figure 37 show examples of the compare editor. The left side of the compare editor shows your local source file, and the right side shows the repository's file. When there are changes between the two, a box will surround the change on both sides. Once you understand what has changed and are satisfied that the changes are appropriate, you can use the context menu in the Synchronize view to send your changes to the repository.

Back to top

Summary

In this article you continued to explore the development process within the Eclipse environment and learned how you can use Eclipse in your development process to ease code creation, debugging, maintenance, and deployment. You also learned about using a full-featured debugger to step through code and inspect the variables in your PHP code. And you were provided with specific examples of using CVS to synchronize your code development with other team members.

Part 14 provides a complete description of the code for our announcement module and the corresponding downloadable file.

Back to top

Downloads

• For relevant downloads for Windows, see Part 3 of this series.
• For relevant downloads for Linux see Part 4 of this series.
• Part 14 provides the complete announcement module download.

Resources

Learn

• Please note that the PHP IDE project has been replaced by the PHP Dev Tools project. Get more details about the PHP Dev Tools project and learn more about Eclipse.org.
  
  
• Eclipse PHP debugger: Learn more about this project.
  
  
• HTMLtidy: Read about maintenance and further development of the HTML Tidy program.
  
  
• phpDocumentor: The current standard auto-documentation tool for the php language.
  
  
• Visit developerWorks Architecture to get the resources you need to advance your skills in the IT architecture arena.
  
  
• Stay current with developerWorks technical events and webcasts.
  
  
• Browse the technology bookstore for books on these and other technical topics.
  
  
• RSS feed for this series. (Find out more about RSS.)
  
  

Get products and technologies

• Download Zend PDT downloads.
  
  
• Build your next development project with IBM trial software, available for download directly from developerWorks.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Participate in developerWorks blogs and get involved in the developerWorks community.
  
  

About the authors

Alister Lewis-Bowen is a senior software engineer in IBM's Internet Technology Group. He has worked on Internet and Web technologies as an IBM UK employee since 1993. Alister was brought to the U.S. to work on the Web sites for the IBM-sponsored sports events, then as senior Webmaster for ibm.com. He is currently helping create semantic Web prototypes.

Louis Weitzman is a senior software engineer in IBM's Internet Technology Group. For 30 years he has worked at the intersection of design and computation. He helped develop an XML, fragment-based content management system in use by ibm.com, and currently is involved with bringing the design process to emerging projects.

Stephen Evanchik is a software engineer in IBM's Internet Technology Group. He has been a contributor to many open source software projects, the most notable being his IBM TrackPoint driver in the Linux kernel. Stephen is currently working with emerging semantic Web technologies.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Writing PHP
• Installing and configuring the PHP debugger
• Debugging PHP
• Tracking code changes
• Summary
• Downloads
• Resources
• About the authors
• Comments

Next steps from IBM

With the no-charge DB2 Express-C, Zend Core PHP, and Java you can develope advanced Web 2.0 applications quickly that matter.

---

• Try: Download a free trial version of DB2 Express-C, which includes Zend Core PHP and pureXML technology that is ideally suited for managing both XML and relational data and powering a new breed of SOA and Web 2.0 solutions.
• Article: This IBM Redbook shows how to port PHP apps from MySQL to DB2, and includes code samples for creating Zend Core PHP applications.
• Tutorial: In this Mastering Facebook app development tutorial series, you will use Java and PHP in parallel to build a Facebook interface for an online stock trading J2EE application using the Spring framework.
• Buy: DB2 9 for Linux, UNIX and Windows

My developerWorks community