# PHP Tutorial Komodo IDE only

## Overview

### Before You Start

This tutorial assumes:

- PHP 4.3.11 or greater is installed on your system. See the Debugging PHP documentation for installation and configuration instructions.
- You are interested in PHP. You don't need previous knowledge of PHP; the tutorial will walk you through a simple program and suggest some resources for further information.

### PHP Tutorial Scenario

This tutorial examines a PHP program that implements a form on a website - in this case, a guest book where site visitors can log comments. In addition to providing an overview and working example of PHP, the tutorial introduces Komodo's CGI Debugging functionality. In this tutorial you will:

1. Open the PHP Tutorial Project and associated files.
2. Analyze guestbook.php, the PHP program included in the PHP Tutorial Project.
3. Run the program and generate HTML output by running the program.
4. Debug the program using the Komodo debugger.

See Debugging Programs for more information on this Komodo functionality.

## Opening the Tutorial Project

On the Start Page under Tutorials and Documentation, click PHP Tutorial, or open the php_tutorial.kpf file from the samples/php_tutorials subdirectory of Komodo's user data directory

The tutorial project will open in the Places sidebar.

### Overview of the Tutorial Files

The following components are included in the php_tutorial.kpf project file:

- guestbook.php: This PHP program writes data from an HTML form to a data file, then extracts the contents of the data file and formats it as HTML.

### Open the PHP Tutorial File

In the Places sidebar, double-click the file guestbook.php. The file opens in the Editor Pane; a tab at the top of the pane displays the filename.

## Analyzing the PHP Tutorial File

This section reviews the code in guestbook.php.

## Analyzing guestbook.php

### Introduction

In this step, you will analyze the PHP program on a line-by-line basis. Ensure that line numbers are enabled in Komodo (View|View Line Numbers) and that the file guestbook.php is displayed in the Komodo editor.

### HTML Header

#### Lines 1 to 8 - HTML Header

- a standard HTML header is written to the program output

Komodo Tip: Notice that syntax elements are displayed in different colors. Adjust the display options for language elements in the Preferences dialog box.

### PHP Declaration and Datafile

#### Line 9 - PHP Declaration

- PHP programs are embedded in HTML
- the characters `<?php` indicate the start of the PHP program

#### Lines 10 to 18 - Comments

- the `//` characters indicate a single-line comment in PHP programs; the `#` symbol can also be used. Multi-line comments are nested in `/*` and `*/` characters, as shown on lines 27 to 30

#### Line 22 - Datafile

- the file guestbook.dat is created if it does not exist
- the `tmp` directory must exist beneath the root of the drive where the program resides (unless a different location is specified in the Debugging Options).
- PHP statements are terminated with semicolons

Komodo Tip: On line 23, type `$da`. Komodo displays a list of the variables declared above the cursor position that begin with the letters `da`. This is AutoComplete.

### GuestBook Class

#### Lines 25 to 28 - Class Declaration

- a `class` is a collection of variables and functions
- `class GuestBook` contains the functions `GuestBook`, `_getData"`, `outputData`, etc
- the `var` statement declares variables as class members, thus making them portable across functions contained in the class

Komodo Tip: Click the mouse pointer at the end of line 25. Notice that the brace changes to a bold red font. The closing brace on line 144 is displayed the same way. In this case, the braces mark the beginning and end of a class. See Editing Files in the Komodo User Guide for more about matching braces.

### GuestBook Function

#### Lines 34 to 37 - GuestBook Function

- a function is a discrete block of code
- the `$datafile` argument is passed to the function `GuestBook`; multiple arguments are separated by commas
- the contents of a function are enclosed in braces
- `$_SERVER` is a pre-defined PHP variable; it is passed to the script from the web server
- - in PHP, global variables must be declared to be global inside a function if they are going to be used in that function
- a local variable is defined for the current function by use of the term `$this`; notice that the same syntax is used to call another function
- - `gb_dat` variable is declared on line 27
  - `gb_dat` variable is assigned the value of `$datafile`
  - `$this->data` variable is cleared of any prior value
  - `$this->_getData` variable calls the `_getData` function that begins on line 53; when the `_getData` function is complete, processing returns to line 40

Komodo Tip: On line 38, type `function GuestBook(`. When you type the left parenthesis, Komodo displays a pop-up hint that describes parameters for the function `GuestBook`. This is a CallTip.

#### Lines 40 to 44 - Check for Valid Form Entry

- if the `REQUEST_METHOD` contained in `$_SERVER` is equal to `POST`, processing passes to the `addGuestBookEntry` function on line 120
- if the `REQUEST_METHOD` is not equal to `POST`, a redirect message is displayed to the user
- - the `echo` command generates output
  - the characters `\"` are not included inside the double quotation marks that follow, so that the message can be displayed as output
  - the PHP variable `PHP_SELF` is the filename of the current script
  - `$_SERVER["PHP_SELF"]` extracts the `PHP_SELF` variable from the `$_SERVER` variable

#### Lines 45 to 46 - Check for Variable Value

- the `if ($this->data)` statement tests if the variable `$this->data` has a value
- - the program executes the `outputData` function and then the `outputForm` function

### _getData Function

#### Lines 53 to 58 - _getData Function

- the "file" statement parses the contents of the file stored in the `gb_dat` variable into the `$lines` array
- - the `@` symbol suppresses warnings; in this case, if the data file is empty, the program generates a non-fatal error
- the `if ($lines)` statement checks to see if the `$lines` variable has data
- the "join" statement converts the `$lines` array to a string and places it in the variable `$this->data`

PHP Pointer: Use the "@" operator with care; you could disable error messages for critical errors that terminate the execution of the script.

### outputData Function

#### Lines 64 to 66 - outputData Function

- the contents of the `$this->data` variable are written to the standard output using the `echo` statement

### _createEntryHTML Function

#### Lines 72 to 77 - Retrieve Form Data

- the PHP variable `$_POST` is used to provide data to the script via HTTP POST
- lines 74 to 77 extract the form data and place the items in variables

#### Lines 80 to 83 - Validate Form Data

- On line 80, the validity of the name and message variables is tested:
- - in `!$name` and `!$message`, "!" is a "not" operator; it is true if either variable is not true
  - The `||` symbol is an "or" operator

PHP Pointer: PHP has two "or" operators: the word "or", and the symbol `||`. The `||` operator has precedence over the word "or", providing flexibility in logic tests.

#### Line 86 - Current Date and Time

- the variable `$today` contains the result of the PHP function `date`:
- - the `date` function returns a string
  - the "switches" are interpreted as follows:
  - - `F`: text month
    - `j`: numeric day within month
    - `y`: four digit year
    - `g`: hour (12 hour format)
    - `a`: AM / PM

#### Lines 89 to 94 - Interpolate Form Data with HTML

- text and HTML tags are parsed with the `$today` variable and the form data
- the `return` statement supplies the result (true or false) of a function or the value of a variable to the routine from which it was called

### _writeDataFile Function

#### Lines 100 to 106 - Open the Data File

- the `fopen` function opens the file stored in the `$this->gb_dat` variable
- - the `w` switch opens the file if it exists
  - If the file does not exist, `fopen` will attempt to create it
  - the file is opened for writing only, and the file pointer is positioned at the top of the file
- the `if !$f` statement checks to see if the `$f` variable contains a value

#### Lines 108 to 110 - Write to the Data Files

- the `fwrite` function writes the contents of $this->data to the file contained in the `$f` variable

#### Lines 111 to 113 - Close the Data File

- the `fclose` function closes the file stored in the `$f` variable
- the value of the `return` statement is tested on line 112

Komodo Tip: Click on the minus symbol to the left of line 100. The entire`_writeDataFile` function collapses. This is Code Folding.

### addGuestBookEntry Function

#### Lines 120 to 125 - Call Functions for Writing Data

- the `$entry` variable is local to the `addGuestBookEntry` function
- the `$entry` contains the contents of the `$data` variable, returned in the `_createEntryHTML` function
- on line 123, the contents of `$entry` are concatenated with the contents of `$this->data`, and stored in `$this->data`

### outputForm Function

#### Lines 127 to 142 - The Function for HTML Form

- these lines generate a standard HTML form
- notice the PHP snippet on line 133 that provides the program name to the HTML output

### Closing Tags

#### Lines 148 to 151 - Closing Tags

- the `$gb` variable creates a new instance of the `GuestBook` class using the file specified in the `$datafile` variable
- when the functions in the `GuestBook` class are complete, the PHP program is closed using the syntax `?>`
- closing HTML tags are written as output

## Running the Program

This section reviews how to run the guestbook.php program using the Komodo debugger.

1. Run the debugger: Select Debug|Go/Continue.
2. Configure debugging options: In the Debugging Options dialog box, configure the following options:
3. - General tab: Select the Simulate CGI Environment check box.
   - CGI Input tab:
     - Set the Request Method option button to Post.
     - On the Post Type drop-down list, select URL encoded.
     - On the Type drop-down list, select the variable type Post.
     - Enter the following names in the Name text box, adding a meaningful value for each in the Value text box. For example, the value for "name" could be your own name. Click the Add button after each entry to add it to the Browser Arguments.
     - - "name"
       - "email"
       - "company"
       - "message"
4. Run the debugger: Click OK to run the debugger with the selected options.
5. View the Command Output tab: Notice the messages in the bottom left corner of the Komodo screen; these inform you of the status of the debugger.
6. View the rendered HTML: Click the HTML tab on the right side of the Debug tab. The HTML is displayed in the Bottom Pane; previous guestbook entries are displayed at the top of the output, and the HTML form is displayed at the bottom. Click the Output tab to return to the HTML code.
7. Create New File: To create a new HTML file that contains the HTML code on the Output tab, select File|New|New File. In the New File dialog box, select the Common Category, and the HTML template. Click Open.
8. Save the Output: Delete the contents of the new HTML file tab in the Editor Pane, then select the HTML code on the Output tab. Copy the contents to the new HTML file tab in the Editor Pane using the key binding associated with your selected scheme. Select File|Save As to save the file with a unique name.

## Debugging the Program

In this step you will add breakpoints to the program and debug it. Adding breakpoints lets you run the program in chunks, making it possible to watch variables and view output as it is generated. Before beginning, ensure that line numbering is enabled in Komodo (View|View Line Numbers).

1. Set breakpoints: On the guestbook.php tab in the editor, click on the gray margin immediately to the left of the code in line 9 of the program. This sets a breakpoint, indicated by a red circle. Set a second breakpoint on line 148.
2. Run the debugger: Select Go|Continue. In the Debugging Options dialog box, click OK to accept the defaults (assuming that you created the CGI variables in the previous step, Running the Program).

Komodo Tip: Notice that the Debugger Options have been saved from the last time a PHP program was run or debugged.

Komodo Tip: Debugger commands can be accessed from the Debug menu, by shortcut keys, or from the Debug Toolbar. For a summary of debugger commands, see Debugger Command List.

3. Watch the debug process: A yellow arrow on the breakpoint indicates the position at which the debugger has halted.
4. Line 9: Step In: Select Debug|Step In. "Step In" is a debugger command that causes the debugger to execute the current line and then stop at the next processing line (line 19). The lines between line 9 and line 19 are comments, not processing statements, and are therefore ignored by the debugger.
5. View Variables: Expand the Bottom Pane (if necessary) by clicking and dragging the bottom margin of the Komodo workspace. Variables defined in the program are displayed on the Locals tab.
6. Line 19: Select Go|Continue. The debugger moves to line 148. The `GuestBook` class is called from line 148.
7. Line 148: Step In: The debugger is now processing the `GuestBook` function.
8. View Variables: The Locals tab displays all variables.
9. Line 35: Step In: Expand the `$this` variable on the Locals tab in the Bottom Pane. Notice that it now has a sub-variable `gb_dat`, which stores the value of the data file.
10. Line 36: Step In: Continue to step in until the debugger stops at the `_getData` function. Continue to select Step In to process each statement in the function. After line 57 has been processed and the debugger is stopped at line 58, the `$lines` variable can be expanded on the Locals tab.
11. Line 58: Step Out: On line 58, select Step Out to process the rest of the `_getData` function. The debugger will proceed to line 40, which follows the line where `_getData` was called.

Komodo Tip: What do the debugger commands do?

- Step In: Executes the current line of code and pauses at the following line.
- Step Over: Executes the current line of code. If the line of code calls a function or method, the function or method is executed in the background and the debugger pauses at the line that follows the original line.
- Step Out: Executes the code without stepping through the code line by line (when the debugger is within a function or method). The debugger stops on the line of code following the function or method call in the calling program.

14. Line 40: Step In: Continue to select Step In until the debugger is on line 121, in the `addGuestBookEntry` function. On line 121, the `addGuestBookEntry` function calls the `_createEntryHTML` function.
15. Line 121: Step In: In the `_createEntryHTML` function, the program assigns variables to the CGI input data configured in the Debugging Options.
16. Line 74: Step Out: The `_createEntryHTML` function completes, and processing returns to line 122.
17. Line 122: Step In: Use Step In to process each line of the `addGuestBookEntry` function, until processing moves to the `_writeDataFile` function on line 102.
18. Line 102: Step In: Process line 102.
19. Open Watch Window: On line 102, the program opened the datafile (by default, \tmp\guestbook.dat). To watch the activity in the datafile, select Tools|Watch File, then specify the datafile.
20. Line 103: Step In: Continue to select Step In until line 108 has been processed. After line 108 is processed, the contents of the `$this->data` variable are written to the datafile, as displayed in the Watch tab.
21. Line 111: Step In: Step In until processing returns to line 45 of the `GuestBook` function.
22. Line 45: Step Over: The Step Over debugger command executes the current line, including any functions called by the current line. When the debugger returns to line 46, notice that the contents of the `$this->data` variable have been written to the Bottom Pane.
23. Line 46: Step Over: The debugger executes the `outputForm` function, which writes the HTML form to the Bottom Pane.
24. Continue: Select Debug|Continue to run the debugger to the end of the program.

## More PHP Resources

### Tutorials and Reference Sites

There are many PHP tutorials and beginner PHP sites on the Internet, including:

- The PHP Resource Index, a collection of resources dealing with PHP.
- www.PHP.net, the home of all that is PHP-related.