PHP Mode Manual
***************

This manual documents PHP mode version 1.4.0 for use with GNU Emacs.

Copyright © 2008  Aaron S. Hawley

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, and no Cover Texts.  A copy of the license is included in the section entitled ``Copying This Manual.''

     A copy of the license is also available from the Free Software Foundation Web site at http://www.gnu.org/licenses/fdl.html.

The document was typeset with GNU Texinfo (http://www.texinfo.org/).

$Date$

$Revision$

Introduction
************

PHP mode is a major mode for editing PHP source code in Emacs.  As an extension of Emacs's C mode, it inherits all C mode's navigation and editing functionality.  Syntax elements of PHP source code is colored according to the grammar of PHP versions 3, 4 and 5.  By default, the indent rules follow the PHP PEAR coding guidelines.  Additional aids for developing in PHP include documentation search of the PHP manual, code completion and a class browser.

To find out what version of PHP mode you have installed run M-x php-mode-version.

PHP mode was first released in 1999 and was written by Turadg Aleahmad.  At the time of PHP mode's initial release, version 2 of PHP (PHP/FI) was only 2 years old and the release of PHP 3 had happened the year before.  In May of 2000, PHP 4 was released.  Subsequent versions of PHP mode scurried to support the quickly evolving syntax of this emerging programming language.

In 2001, PHP mode became a SourceForge project and version 1.0 was released later that year.  Further refinements of the Emacs library included improvements to the syntax coloring rules, portability between XEmacs and GNU Emacs, integration of various development tools available in various Emacsen.

PHP mode's support for PHP 5 first appeared in 2004, the same year PHP 5 was released.  2004 was the last year Aleahmad made a release.  In 2005, Lennart Borgman combined a forked version of PHP mode with his ``new XML mode for Emacs'' (nXhtml).  The stalled development of PHP resulted in people sharing various patches and improvements to PHP mode over the Internet.

The 1.4 release in 2008 represented a renewed commitment to the Emacs Lisp library with the addition of considerable updates and improvements -- the first in over 2 years.

This manual describes PHP mode for practiced Emacs users especially those who have read or can refer to the Emacs manual.  The reader should already know how to program in PHP, although one could easily learn how to program PHP using PHP mode and Emacs.  There are no explanations of PHP programming in this manual.

Electricity
***********

Certain characters when inserted in Emacs have electricity.  Emacs recognizes them as ``electric'' and automatically reacts in some way to their insertion. This is unlike the self-insert-command -- the conventional manner Emacs inserts most characters into the buffer and without side-effect.

For example, the indent commands for programming language modes -- including PHP mode -- are electric.  Hitting TAB (or C-i) typically indents the line to the correct column based on the nested declaration blocks or conditional (control) syntax statements.  Other examples of electric characters include braces ({ and }), characters related to comments (#, / and *), and semicolons.  Inserting ``electric'' characters causes the line to be automatically be indented appropriately by PHP mode.

Should PHP mode ever do something you wish it didn't, like indenting incorrectly after inserting a character when you wish it didn't, then you've been electrocuted.  To avoid this, use quoted-insert by prefixing the character with C-q.  For example, C-q TAB for a tab.  Alternatively, disable the electric effect of PHP mode with C-c C-l.  Issue C-c C-l again to activate the electric effect again.

Motion
******

The traditional point movement commands for Emacs (see Changing the Location of Point (GNU Emacs Manual).) and Emacs's C mode (see Movement Commands (CC Mode Manual).) are supported in PHP mode.  The following are noteworthy commands for working on PHP code or are extensions expressly provided by PHP mode.

C-M-f
     Move forward past the current syntax (forward-sexp). If point is in a string literal, move to the end of the string.  If point is at the beginning of a parenthetical expression, move to the end of it.  If at the beginning of statement block that is surrounded by braces, move to the end of the block.  If point is at an identifier, skip to the end of it.

C-M-b
     Same as C-M-f, except a syntactic element move to its beginning (backward-sexp).

C-M-a
     Move point to the beginning of the top-level function definition (c-beginning-of-defun).

C-M-e
     Move point to the end of the top-level function definition (c-end-of-defun).

C-M-<HOME>
     Move point to the beginning of the current function (beginning-of-defun).

C-M-<END>
     Move point to the end of the current function (end-of-defun).

M-m
     Move to the indentation at the beginning of the line (back-to-indentation).

C-c C-w
     Enable word motion across mixed case identifiers with forward-word and backward-word commands (c-subword-mode).

Most movement commands support prefixing the command with a numeric argument by using Emacs's universal argument command.  Type C-u N, where N is the number of times to repeat a command.  If no number N is provided, Emacs will repeat the command 4 times by default.  See Numeric Arguments (GNU Emacs Manual).

Indentation
***********

PHP mode's indentation settings follow the PHP PEAR ``Coding Standards'' (http://pear.php.net/manual/en/standards.php). This has the consequence in PHP mode of making the indentation commands use four spaces, and not tabs.

PHP does not appropriately indent HTML tags.  See Embedded HTML.

To customize PHP mode's indentation rules, change the following variables.

c-basic-offset
     This style variable of CC mode controls how many columns in the level of indentation.  By default this is 4 spaces in PHP mode (and in CC mode).

indent-tabs-mode
     Variable of Emacs that determines whether indentation commands should insert the tab character or insert the equivalent number of space characters.  In PHP mode, this is set to to nil by default.

tab-width
     This variable of Emacs determines how ``wide'' a tab in the buffer should be considered.  This is also traditionally described as setting the distance between ``tab stops''.  By default, PHP mode does not insert tabs for indentation.

The usual commands for indenting in Emacs (see Indentation Commands (GNU Emacs Manual).) and Emacs's C mode (see Indentation Commands (CC Mode Manual).): are supported in PHP mode, following the indentation rules of PHP.

TAB
     Properly indent current line, even from the middle of the line (c-indent-command).

C-j
     Insert text after point to a newline, and properly indent the newline (c-indent-command).

C-M-\
     Properly indent each line of region (indent-region).

C-c C-q
     Properly indent each line of current top-level function or top-level class (c-indent-defun).

Editing
*******

M-q
     Fill the paragraph to current value of fill-column. The command does the right thing for indented code and PHP comments including Docblock comments.

C-u N C-x f
     Set the fill-column to N when using the M-q command (fill-paragraph).

C-M-h
     Mark the current function (c-mark-function).  Puts the mark at the end and of the function and the point at the beginning.  Useful if you want to kill the region with C-w or M-w, or indent the region with C-M-\ or C-x TAB (see Indentation.).

M-x mark-defun
     Like C-M-h (c-mark-function), except place the mark at the end of the function even if it's not at the top-level.  With functions that are methods defined in a class, they may be indented and not top-level functions, however this command will only mark the current function.

The traditional commands for narrowing to a region in Emacs (see Narrowing (GNU Emacs Manual).) are supported in PHP mode.  The following commands are notable to mention for working with PHP or are extensions expressly provided PHP mode.

C-x n d
     Narrow the buffer to the contents of the current function (narrow-to-defun).  This will narrow to the function as identified to the current function, even if it is nestedin an object or another function.  The logic to narrow the function is the same as the beginning-of-defun and end-of-defun commands -- see Motion, and the mark-defun command -- see above.

C-x n w
     Undo any narrowing by widening the buffer again by making the rest of the buffer available (widen).

Completion
**********

Completing function names, identifiers and PHP keywords is possible in PHP mode.  In PHP mode, it is possible to complete identifiers defined by the PHP programming language, and to complete functions defined by you.

For PHP mode to know the functions of keywords of PHP, it must have access to the PHP manual.  Download the HTML archive of the manual made of separate files for each function. (http://www.php.net/download-docs.php) Unpack the files to a directory, and define the variable PHP-MANUAL-PATH to the location of these files. Configure this setting with either M-x customize-variable RET php-manual-path RET, or by setting the value in your Emacs initialization file (~/.emacs).

For functions and classes you define, you'll need to provide them to Emacs as a tag file. (See Tags Tables (GNU Emacs Manual).) Creating a tag file (TAGS) from a PHP source code file is done by running the etags command on the file. (See Creating Tags Tables (GNU Emacs Manual).) The etags command can even generate tag files for providing completion across multiple files.  For larger projects and PHP coded libraries, use a system like a Makefile to generate and maintain the tag tables.

Run,

     etags FILE

to create a TAGS file for FILE.

To generate a TAGS file for all the PHP files in the current directory, run

     etags *.php

To enable a tags file you need to use the following command.

C-u M-x visit-tags-table
     Specify the TAGS file that PHP mode should use to find completion candidates for the current buffer.

M-x visit-tags-table
     Specify the TAGS file that PHP mode should use to find completion candidates for all buffers, and even other modes other than PHP mode.

If you are interested in any one or more of the following consider using the variable php-completion-file.

 1. avoid regenerating the completion table from the PHP manual every Emacs session,

 2. generating a completion file from a facility external to Emacs tags,

 3. or provide more granular control over the completion rules for files;

Configure the variable with either M-x customize-variable RET php-completion-file RET, or by setting the value in your Emacs initialization file (~/.emacs).

In larger projects or with other specific needs, conventional methods of setting these and other variables may be inadequate.  As of 2008, third-party packages do exist for Emacs to configure Emacs settings on groups of files or for directory trees, including dirvars.el.

M-TAB

ESC TAB

C-[ TAB
     Complete function name at point (php-complete-function).

C-.
     Show in the minibuffer the argument list for the current function at point (php-show-arglist).  The argument list is generated by finding and jumping to the respective function's location specified in the tag file (see above). The argument list is then read and printed to the minibuffer.

PHP Comments
************

The usual commands for inserting, managing and editing source code comments in Emacs (see Manipulating Comments (GNU Emacs Manual).)  and Emacs's C mode (see Comment Commands (CC Mode Manual).): are supported in PHP mode.  The following noteworthy commands are useful for working with PHP or are extensions expressly provided by PHP mode.

M-;
     Insert comment at point (comment-dwim).  If comment already exist, indent comment (comment-indent).

M-j
     Insert a newline in a comment on the next line with the comment starting at the same column as the current line (c-indent-new-comment-line).

C-x ;
     Set the current column as the column to start comments from in the buffer (comment-set-column).  This affects the variable comment-column.

C-c C-c
     Comment out the current region (comment-region).  If region is already commented, the region is uncommented.

M-- C-x ;

C-u M-;
     Kill the comment on the current line (comment-kill called by comment-set-column or comment-dwim).

C-u N M-;
     Kill the next N comments (comment-dwim).

M-x comment-box
     Surround region with comment characters.

PHP Documentation
*****************

PHP mode supports the online documentation available from http://www.php.net/.  The browse-url system of Emacs supports these commands.  Run the Emacs command M-x customize-group RET browse-url RET to configure how browse-url behaves.  For example, you may want to change the Web browser Emacs uses for visiting a page of the manual for PHP.

C-c C-m

C-c RET
     Browse PHP manual in a Web browser.

C-c C-f
     Search PHP manual using identifier at point.

Index Menu
**********

PHP mode provides a menu of the functions and classes defined in the current buffer.  The menu is pretty simple, but is helpful when navigating large files.  The contents of the menu also provide a good overview to the user about the file's contents.

To enable this menu, run the following command.

M-x imenu-add-menubar-index
     Scan the file for functions and class declarations, then add a menu item called ``Index'' to the menu bar.

In the menu will be any one or more of the following menu items.

Functions
     A sub-menu containing the names of functions defined in the current buffer.  Clicking on a function name will visit the location of the function's definition.

Classes
     A sub-menu containing the names of classes defined in the current buffer.  Clicking on a class name will visit the location of the class's definition.

*Rescan*
     Rescan the contents of the current buffer, and update both the indexes the entries in the menu.

To have Emacs automatically rescan the current buffer, change the setting for imenu-auto-rescan to non-nil with either M-x customize-variable RET php-completion-file RET, or by setting the value in your Emacs initialization file (~/.emacs).

Change Logs
***********

PHP mode can help generate ChangeLog files, a widely-adopted format for documenting the changes made to source code--especially software.  PHP mode and Emacs will determine the current function, file name, author information and date and use it all to prepare a properly formatted ChangeLog entry in the file.

The add-change-log-entry commands can be run from within a buffer containing a PHP buffer, or from a buffer in Diff mode with a revision patch to a PHP source file. See Diff Mode (GNU Emacs Manual).

C-x 4 a
     Add an entry in a ChangeLog file opened in another window, or add a new line to the already begun entry (add-change-log-entry-other-window).  Provides the file name and the respective function name, when applicable, for the current point.  The point can be in a PHP source file, or in the hunk of a diff file. (See Diff Mode (GNU Emacs Manual).) This command will also add the current author and date to the entry.

Speedbar
********

FIXME: Document speedbar support for PHP mode.

Customization
*************

Customization for PHP mode can be done using Emacs's ``Customize'' feature (see Customization (GNU Emacs Manual).), or by adding bits of Emacs Lisp to your Emacs initialization file (~/.emacs).

M-x customize-group RET php RET
     Start a *Customize* buffer with the customizable settings for PHP mode.

Embedded HTML
*************

The PHP programming language is commonly embedded with HTML but also with other markup formats.  Unfortunately, PHP mode is currently unable to recognize these other bits and provide commands that behave appropriately.  Other Emacs modes for properly indenting HTML include HTML mode, SGML mode and XML mode.

For example, when editing the HTML sections found in a PHP file, consider turning on HTML mode with M-x html-mode.  Use the the mode-specific commands for manipulating the HTML.  When finished, turn back on PHP mode with M-x php-mode to return working on the PHP sections of the file.

Alternatively, consider using a multiple major mode like mumamo, mmm-mode or multi-mode.  These modes allow a single buffer to appoint different major modes to respective portions of the buffer.

Contributors
************

  * Juanjo

  * Torsten Martinsen

  * Vinai Kopp

  * Sean Champ

  * Doug Marcey

  * Kevin Blake

  * Rex McMaster

  * Mathias Meyer

  * Boris Folgmann

  * Roland Rosenfeld

  * Fred Yankowski

  * Craig Andrews

  * John Keller

  * Ryan Sammartino

  * ppercot

  * Valentin Funk

  * Stig Bakken

  * Gregory Stark

  * Chris Morris

  * Nils Rennebarth

  * Gerrit Riessen

  * Eric Mc Sween

  * Ville Skytta

  * Giacomo Tesio

  * Lennart Borgman

  * Stefan Monnier

  * Aaron S. Hawley

  * Aaron Iba

Copying This Manual
*******************

     [file fdl.texi not included]