PHP Mode for Emacs Code

1090 lines (942 with data), 33.5 kB

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename php-mode.info
@settitle PHP Mode Manual
@set version 1.4.0
@c %**end of header
@copying
This manual documents PHP mode version @value{version} for
use with GNU Emacs.

Copyright @copyright{} 2008  Aaron S. Hawley

@quotation
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
@url{http://www.gnu.org/licenses/fdl.html}.

@end quotation

The document was typeset with
@uref{http://www.texinfo.org/, GNU Texinfo}.

$Date$

$Revision$

@end copying

@titlepage
@title PHP Mode Manual
@subtitle Editing PHP in GNU Emacs
@author Aaron S. Hawley <aaronh@@localhost.localdomain>
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@c Output the table of the contents at the beginning.
@contents

@ifnottex
@node Top
@top PHP Mode Manual

@insertcopying
@end ifnottex

@c Generate the nodes for this menu with `C-c C-u C-m'.
@menu
* Introduction::                
* Electricity::                 
* Motion::                      
* Indentation::                 
* Editing::                     
* Completion::                  
* PHP Comments::                
* PHP Documentation::           
* Index Menu::                  
* Change Logs::                 
* Speedbar::                    
* Customization::               
* Embedded HTML::               
* Contributors::                
* Copying This Manual::         
* Concept Index::               
* Function Index::              
* Keyboard Index::              
* Variable Index::              
@end menu

@c Update all node entries with `C-c C-u C-n'.
@c Insert new nodes with `C-c C-c n'.
@node Introduction
@chapter Introduction

@cindex C mode
@cindex features
@cindex PEAR
@cindex PHP versions
@cindex syntax highlighting
@cindex version, PHP
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.

@cindex version, PHP mode
@findex php-mode-version
To find out what version of PHP mode you have installed run
@kbd{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.

@c In 2007, Aaron S. Hawley offered to update and maintain
@c PHP mode.  PHP mode's files were moved from CVS to a
@c Subversion code repository.  A release appeared in 2008
@c with a number of improvements and updates to support
@c newer versions of CC mode and Emacs that were finally
@c released in 2007.  PHP mode shipped with a 16 page
@c Texinfo manual authored by Hawley.

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.

@node Electricity
@chapter Electricity

@c This article explains electricity, because the Emacs
@c manual, as of 2008, doesn't do a good job of introducing
@c the concept.

@c The section only gives examples of ``electric''
@c commands.  There should be a list of those commands.

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

@cindex indentation, electric
@cindex electric indentation
@cindex declaration blocks
@cindex conditional statements
@cindex braces
@cindex comments
@kindex TAB
For example, the indent commands for programming language
modes -- including PHP mode -- are electric.  Hitting
@kbd{TAB} (or @kbd{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.

@findex quoted-insert
@kindex C-q
@findex c-toggle-electric-state
@kindex C-c C-l
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 @dfn{electrocuted}.  To
avoid this, use @code{quoted-insert} by prefixing the
character with @kbd{C-q}.  For example, @kbd{C-q TAB} for a
tab.  Alternatively, disable the electric effect of PHP mode
with @kbd{C-c C-l}.  Issue @kbd{C-c C-l} again to activate
the electric effect again.

@c Is there a setting to use in ones .emacs to permanently
@c shut off electricity?

@node Motion
@chapter Motion

@c It's important to explain when a feature is really a
@c subset of a feature of Emacs or C Mode, and take the
@c opportunity to create a cross-reference to those free
@c manuals.

@cindex motion
@cindex movement
@cindex C mode, movement
@cindex point
The traditional point movement commands for Emacs@footnote{@xref{Moving
Point, Changing the Location of Point, Changing the Location
of Point, emacs, GNU Emacs Manual}.} and Emacs's C
mode@footnote{@xref{Movement Commands, Movement Commands,
Movement Commands, ccmode, 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.

@table @kbd

@c The forward-sexp command isn't optimally named nor
@c behaved for a language like PHP, but it comes for free
@c (gratis) from Emacs, and may prove useful.  It would be
@c better to have a php-forward-syntax command that follows
@c the parsing rules of PHP and not a lisp language.  FOr
@c intance, if at the beginning or end of a statement, move
@c to the next statement.  The syntaxes that would be useful
@c to move accross would need to be researched.
@cindex block
@cindex braces
@cindex parentheses
@cindex string
@cindex statements
@cindex syntax, forward
@findex forward-sexp
@kindex C-M-f
@item C-M-f
Move forward past the current syntax (@code{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.
@cindex syntax, backward
@findex backward-sexp
@kindex C-M-b
@item C-M-b
Same as @kbd{C-M-f}, except a syntactic element move to its
beginning (@code{backward-sexp}).
@cindex beginning of function
@cindex function, beginning of
@findex c-beginning-of-defun
@kindex C-M-a
@item C-M-a
Move point to the beginning of the top-level function
definition (@code{c-beginning-of-defun}).
@cindex end of function
@cindex function, end of
@findex c-end-of-defun
@kindex C-M-e
@item C-M-e
Move point to the end of the top-level function definition
(@code{c-end-of-defun}).
@cindex end of function
@cindex function, end of
@findex beginning-of-defun
@kindex C-M-<HOME>
@item C-M-<HOME>
Move point to the beginning of the current function
(@code{beginning-of-defun}).
@cindex end of function
@cindex function, end of
@findex end-of-defun
@kindex C-M-<END>
@item C-M-<END>
Move point to the end of the current function
(@code{end-of-defun}).
@cindex indentation, move to
@findex back-to-indentation
@kindex M-m
@item M-m
Move to the indentation at the beginning of the line
(@code{back-to-indentation}).
@cindex bumpy case
@cindex camel case
@cindex mixed case
@cindex case, mixed
@cindex function, end of
@findex backward-word
@findex forward-word
@findex c-subword-mode
@kindex C-c C-w
@item C-c C-w
Enable word motion across mixed case identifiers with
@code{forward-word} and @code{backward-word} commands
(@code{c-subword-mode}).
@end table
@cindex universal argument
@cindex numeric argument
@findex universal-argument
@kindex C-u
Most movement commands support prefixing the command with a
@dfn{numeric argument} by using Emacs's @dfn{universal
argument} command.  Type @kbd{C-u @var{n}}, where @var{n} is
the number of times to repeat a command.  If no number
@var{n} is provided, Emacs will repeat the command 4 times
by default.  @xref{Arguments, Numeric Arguments, Numeric
Arguments, emacs, GNU Emacs Manual}.

@node Indentation
@chapter Indentation

@c It's important to explain when a feature is really a
@c subset of a feature of Emacs or C Mode, and take the
@c opportunity to create a cross-reference to those free
@c manuals.

@cindex indentation, rules for
@cindex C mode, indentation rules
PHP mode's indentation settings inherit the defaults set by
Emacs C mode, or the rules customized for C
mode.@footnote{@xref{Customizing Indentation, Customizing
Indentation, Customizing Indentation, ccmode,
CC Mode Manual}.}

@cindex PEAR, indentation
@cindex spaces
@cindex tabs
PHP mode provides indentation settings that follow the PHP
PEAR ``Coding
Standards''@footnote{@url{http://pear.php.net/manual/en/standards.php}}.
It has the consequence in PHP mode of making the indentation
commands use four spaces, and not tabs.  This setting is
turned on whenever the file name associated with a buffer
includes the string ``PEAR'', case insensitive and the file
ends in ``.php''.

@cindex indentation, force PEAR rules
@vindex php-mode-force-pear
@findex customize-variable
You can force the use of this setting for
all files edited with PHP mode by setting
@code{php-mode-force-pear} to non-nil.  Configure the
variable with either @kbd{M-x customize-variable RET
php-mode-force-pear RET}, or by setting its value in your
Emacs initialization file (@file{~/.emacs}).

@cindex HTML
PHP does not appropriately indent HTML tags.  @xref{Embedded
HTML}.

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

@c There are probably other variables that are safe for
@c users to change and are worth mentioning.  One's from C
@c mode come to mind, like indentation-style.  Some day it
@c would also be useful to support a variety of PHP
@c programming styles.

@c Perhaps the indentation commands should be featured
@c before customization.  They could have separate sections.

@table @code

@cindex indentation, level of
@vindex c-basic-offset
@item c-basic-offset
This style variable of C mode controls how many columns in
the level of indentation.  By default this is 4 spaces in
PHP mode (and in C mode).
@vindex indent-tabs-mode
@item 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.
@vindex tab-width
@item 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.
@item php-mode-force-pear
Use the indentation rules of PHP PEAR for all files opened
in PHP mode.  See above.

@end table

@cindex indentation, commands for
@cindex C mode, indentation rules
@cindex C mode, indentation commands
The usual commands for indenting in
Emacs@footnote{@xref{Indentation Commands, Indentation
Commands, Indentation Commands, emacs, GNU Emacs Manual}.}
and Emacs's C mode@footnote{@xref{Indentation Commands,
Indentation Commands, Indentation Commands, ccmode, CC Mode
Manual}.}: are supported in PHP mode, following the
indentation rules of PHP.

@table @kbd

@cindex tab
@cindex indent line
@cindex line, indent
@findex c-indent-command
@kindex TAB
@item TAB
Properly indent current line, even from the middle of the
line (@code{c-indent-command}).
@c provide examples? -- ash 2007-12-29
@cindex newline
@cindex indent newline
@cindex indent newline
@findex newline-and-indent
@kindex C-j
@item C-j
Insert text after point to a newline, and properly indent
the newline (@code{c-indent-command}).
@cindex indent region
@cindex region, indent
@findex indent-region
@kindex C-M-\
@item C-M-\
Properly indent each line of region (@code{indent-region}).
@c I'm not going to bother mentioning C-x TAB,
@c M-x indent-rigidly. -- ash 2007-12-29
@cindex function, indent
@cindex indent function
@cindex class, indent
@cindex indent class
@findex c-indent-defun
@kindex C-c C-q
@item C-c C-q
Properly indent each line of current top-level function or
top-level class (@code{c-indent-defun}).
@end table

@node Editing
@chapter Editing

@c Provide an introduction to this section.

@table @kbd

@cindex paragraph, fill
@cindex filling
@cindex indentation, filling
@cindex filling indentation
@cindex filling comment
@cindex comment, filling
@cindex Docblock comment
@cindex comment, Docblock
@findex c-fill-paragraph
@kindex M-q
@item M-q
Fill the paragraph to current value of @code{fill-column}.
The command does the right thing for indented code and PHP
comments including Docblock comments.
@cindex column, fill
@cindex fill column
@cindex fill-column
@findex set-fill-column
@findex fill-paragraph
@kindex C-x f
@item C-u @var{n} C-x f
Set the @code{fill-column} to @var{n} when using the @kbd{M-q}
command (@code{fill-paragraph}).
@cindex function, mark
@findex kill-region
@findex kill-ring-save
@findex indent-region
@findex indent-rigidly
@findex c-mark-function
@kindex C-M-h
@kindex C-w
@kindex M-w
@kindex C-M-\
@item C-M-h
Mark the current function (@code{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
@kbd{C-w} or @kbd{M-w}, or indent the region with
@kbd{C-M-\} or @kbd{C-x TAB} (@xref{Indentation}.).
@cindex defun, mark
@findex mark-defun
@kindex M-x mark-defun
@item M-x mark-defun
Like @kbd{C-M-h} (@code{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.

@c Perhaps, M-x mark-defun should be the default for running
@c C-M-h again.  This is the downside of inheriting C mode's
@c keybindings.

@end table

@c This narrowing stuff could deserve its own
@c chapter/section.

@cindex narrowing
@cindex widening
The traditional commands for narrowing to a region in
Emacs@footnote{@xref{Narrowing, Narrowing, Narrowing, emacs,
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.

@table @kbd

@cindex function narrowing
@cindex function, narrow
@findex narrow-to-defun
@kindex C-x n d
@item C-x n d
Narrow the buffer to the contents of the current function
(@code{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 @code{beginning-of-defun}
and @code{end-of-defun} commands -- see @ref{Motion}, and
the @code{mark-defun} command -- see above.
@cindex widening
@findex widen
@kindex C-x n w
@item C-x n w
Undo any narrowing by widening the buffer again by making
the rest of the buffer available (@code{widen}).
@end table

@node Completion
@chapter Completion

@cindex 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.

@cindex customization, PHP manual path
@cindex PHP manual path
@vindex php-manual-path
@cindex .emacs, php-manual-path
@findex customize-variable
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.@footnote{@uref{http://www.php.net/download-docs.php}}
Unpack the files to a directory, and define the variable
@var{php-manual-path} to the location of these files.
Configure this setting with either @kbd{M-x
customize-variable RET php-manual-path RET}, or by setting
its value in your Emacs initialization file
(@file{~/.emacs}).

@c FIXME: Explain how the function name completion works, as
@c much as the user would need to know.

@c The following explains how to get completion to work in
@c detail, with any expectation that the reader knows how
@c completion works in Emacs.  The more opportunities to
@c share features that come with Emacs as they apply to PHP
@c development, the better.

@cindex etags
@cindex tag file
@cindex Makefile
For functions and classes you define, you'll need to provide
them to Emacs as a @dfn{tag file}.@footnote{@xref{Tags, Tags
Tables, Tags Tables, emacs, GNU Emacs Manual}.} Creating a
tag file (@file{TAGS}) from a PHP source code file is done
by running the @command{etags} command on the
file.@footnote{@xref{Create Tags Table, Creating Tags
Tables, Creating Tags Tables, emacs, GNU Emacs Manual}.} The
@command{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.

@cindex etags, running
Run,

@example
etags @var{file}
@end example

to create a @file{TAGS} file for @var{file}.

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

@example
etags *.php
@end example

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

@table @kbd

@cindex tag
@findex visit-tags-table
@item C-u M-x visit-tags-table
Specify the @file{TAGS} file that PHP mode should use to
find completion candidates for the current buffer.

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

@end table

@cindex customization, PHP completion file
@cindex PHP completion file
@vindex php-completion-file
@cindex .emacs, php-completion-file
@findex customize-variable
If you are interested in any one or more of the following
consider using the variable @code{php-completion-file}.

@enumerate
@item
avoid regenerating the completion table from the PHP manual
every Emacs session,
@item
generating a completion file from a facility external to
Emacs tags,
@item
or provide more granular control over the completion
rules for files;

@end enumerate

Configure this setting with either @kbd{M-x
customize-variable RET php-completion-file RET}, or by
setting its value in your Emacs initialization file
(@file{~/.emacs}).

To create a file that can be set for
@code{php-completion-file}, create with the following shell
commands with the HTML version of the PHP manual installed
at @file{/usr/share/doc/php-manual/en/html}.

@example
$ cd /usr/share/doc/php-manual/en/html
$ ls -1 function*.html \
  | sed -e 's/^function\.\([-a-zA-Z_0-9]*\)\.html/\1/' \
  | tr - _ \
  > ~/.emacs.d/php/php-completion-file
@end example

@c PHP mode could ship with a php-completion-file, but that
@c could require releasing a new version of PHP mode
@c whenever significant changes occur to the API of PHP.

@c Keep the following notes on third-party packages updated
@c with respect to managing Emacs settings on a per-project
@c basis.  Otherwise, delete the paragraph(s).  Perhaps the
@c Emacs project will choose or develop a solution, soon.

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 @file{dirvars.el}.

@table @kbd

@cindex complete function
@cindex function, complete 
@findex php-complete-function
@kindex M-TAB
@kindex ESC TAB
@kindex C-[ TAB
@item M-TAB
@item ESC TAB
@item C-[ TAB
Complete function name at point (@code{php-complete-function}).
@cindex argument list, function
@cindex function argument list
@cindex minibuffer
@findex php-show-arglist
@kindex C-.
@item C-.
Show in the minibuffer the argument list for the current
function at point (@code{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.
@end table

@node PHP Comments
@chapter PHP Comments

@cindex comment
The usual commands for inserting, managing and editing
source code comments in Emacs@footnote{@xref{Comments,
Manipulating Comments,Manipulating Comments, emacs, GNU
Emacs Manual}.}  and Emacs's C mode@footnote{@xref{Comment
Commands, Comment Commands, Comment Commands, ccmode, 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.

@c These commands aren't provided by PHP mode, but are
@c important to mention sine the PHP language has comments!
@c It should probably discuss the various types of comments.

@c A section should explain the phpdoc format as supported
@c in PHP mode.

@table @kbd

@cindex comment, insert
@cindex indent comment
@cindex insert comment
@cindex comment, indent
@findex comment-indent
@findex comment-dwim
@kindex M-;
@item M-;
Insert comment at point (@code{comment-dwim}).  If comment
already exist, indent comment (@code{comment-indent}).
@kindex M-x comment-indent
@cindex newline, comment
@cindex comment newline
@findex c-indent-new-comment-line
@kindex M-j
@item M-j
Insert a newline in a comment on the next line with the
comment starting at the same column as the current line
(@code{c-indent-new-comment-line}).
@cindex column, comment
@cindex comment column
@vindex comment-column
@findex comment-set-column
@kindex C-x ;
@item C-x ;
Set the current column as the column to start comments from
in the buffer (@code{comment-set-column}).  This affects the
variable @code{comment-column}.
@cindex comment region
@cindex region, comment
@findex comment-region
@kindex C-c C-c
@item C-c C-c
Comment out the current region (@code{comment-region}).  If
region is already commented, the region is uncommented.
@c I'm not going to bother mentioning the numeric prefix
@c argument variations. -- ash 2008-01-01
@cindex comment, kill
@cindex kill comment
@findex comment-dwim
@findex comment-set-column
@findex comment-kill
@kindex M-- C-x ;
@item M-- C-x ;
@item C-u M-;
Kill the comment on the current line (@code{comment-kill}
called by @code{comment-set-column} or @code{comment-dwim}).
@item C-u @var{n} M-;
Kill the next @var{n} comments (@code{comment-dwim}).
@cindex region, comment box
@cindex comment box
@findex comment-box
@kindex M-x comment-box
@item M-x comment-box
Surround region with comment characters.

@end table

@node PHP Documentation
@chapter PHP Documentation

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

@table @kbd

@cindex browse PHP manual
@findex php-browse-manual
@kindex C-c C-m
@kindex C-c RET
@item C-c C-m
@item C-c RET
Browse PHP manual in a Web browser.
@cindex search PHP manual
@findex php-search-documentation
@kindex C-c C-f
@item C-c C-f
Search PHP manual using identifier at point.

@end table

@node Index Menu
@chapter Index Menu

@c Imenu is documented, because PHP explicitly supports it by
@c setting imenu-generic-expression to
@c php-imenu-generic-expression.  Imenu is documented well,
@c but 

@cindex index menu
@cindex menu, index
@cindex index, class
@cindex index, function
@cindex class index
@cindex function index
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.

@c Initially contributed by Gerrit Riessen

To enable this menu, run the following command.

@table @kbd

@cindex menu bar
@findex imenu-add-menubar-index
@item 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.

@end table

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

@table @samp

@findex imenu
@item 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.
@findex imenu
@item 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.
@findex imenu-update-menubar
@cindex rescan
@item *Rescan*
Rescan the contents of the current buffer, and update both
the indexes the entries in the menu.

@end table

@cindex customization, Imenu auto rescan
@cindex rescan, automatically
@cindex .emacs, imenu-auto-rescan
@vindex imenu-auto-rescan
@findex customize-variable
To have Emacs automatically rescan the current buffer,
change the setting for @code{imenu-auto-rescan} to non-nil
with either @kbd{M-x customize-variable RET
php-completion-file RET}, or by setting its value in your
Emacs initialization file (@file{~/.emacs}).

@node Change Logs
@chapter Change Logs

@vindex php-beginning-of-defun-regexp
@vindex add-log-current-defun-header-regexp
@c This is documented, because PHP mode explicitly supports
@c the features of add-log by setting the value for the
@c add-log-current-defun-header-regexp to
@c php-beginning-of-defun-regexp.  This feature is
@c documented in the PHP manual, but it is worth advertising
@c to PHP programmers.

@cindex ChangeLog
@cindex file, ChangeLog
PHP mode can help generate @file{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 @file{ChangeLog} entry in the file.

@cindex Diff mode
@cindex diff file
@cindex file, diff
@cindex patch file
@cindex file, patch
@findex add-change-log-entry
The @code{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.
@xref{Diff Mode, Diff Mode, Diff Mode, emacs, GNU Emacs
Manual}.

@table @kbd

@cindex ChangeLog entry
@cindex add ChangeLog entry
@findex add-change-log-entry-other-window
@kindex C-x 4 a
@item C-x 4 a
Add an entry in a @file{ChangeLog} file opened in another window,
or add a new line to the already begun entry
(@code{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.@footnote{@xref{Diff
Mode, Diff Mode, Diff Mode, emacs, GNU Emacs Manual}.}
This command will also add the current author and date to
the entry.

@end table

@node Speedbar
@chapter Speedbar

FIXME: Document speedbar support for PHP mode.

@node Customization
@chapter Customization

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

@table @kbd
@findex customize-group
@item M-x customize-group RET php RET
Start a @samp{*Customize*} buffer with the customizable
settings for PHP mode.

@end table

@c There are other sections that talk about customization,
@c but they aren't mentioned here and they don't
@c cross-reference back to this section.

@c Things that aren't documented elsewhere but deserve
@c documentation, in order of importance:

@c * php-mode-hook
@c * php-search-url
@c * php-file-patterns
@c * php-mode-pear-hook

@node Embedded HTML
@appendix Embedded HTML

@c Someday, there will be a decisive way to work on PHP and
@c HTML markup together.  For now, it's not decided.  This
@c section offers some workarounds and offers some suggestions.

@cindex markup formats
@cindex XML
@cindex SGML
@cindex embedded code
@cindex indentation, markup
@cindex HTML
@findex php-mode
@kindex M-x php-mode
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.

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

@cindex multiple major mode
@cindex mumamo
@cindex mmm-mode
@cindex multi-mode
Alternatively, consider using a @dfn{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.

@node Contributors
@appendix Contributors

@itemize
@item Juanjo
@item Torsten Martinsen
@item Vinai Kopp
@item Sean Champ
@item Doug Marcey
@item Kevin Blake
@item Rex McMaster
@item Mathias Meyer
@item Boris Folgmann
@item Roland Rosenfeld
@item Fred Yankowski
@item Craig Andrews
@item John Keller
@item Ryan Sammartino
@item ppercot
@item Valentin Funk
@item Stig Bakken
@item Gregory Stark
@item Chris Morris
@item Nils Rennebarth
@item Gerrit Riessen
@item Eric Mc Sween
@item Ville Skytta
@item Giacomo Tesio
@item Lennart Borgman
@item Stefan Monnier
@item Aaron S. Hawley
@item Aaron Iba
@end itemize

@node Copying This Manual
@appendix Copying This Manual

@c Get fdl.texi from http://www.gnu.org/licenses/fdl.html
@include fdl.texi

@node Concept Index
@unnumbered Concept Index

@printindex cp

@node Function Index
@unnumbered Function Index

@printindex fn

@node Keyboard Index
@unnumbered Keyboard Index

@printindex ky

@node Variable Index
@unnumbered Variable Index

@printindex vr

@bye

@c Local Variables: **
@c mode: auto-fill **
@c fill-column: 60 **
@c End: **
@c php-mode.texi ends here

@c  LocalWords: texinfo setfilename php settitle url uref
@c  LocalWords: Docblock titlepage vskip pt FI filll
@c  LocalWords: insertcopying ifnottex HTML cindex findex
@c  LocalWords: kbd dfn kindex pxref ccmode var xref sexp
@c  LocalWords: defun subword CC ChangeLog Diff XML SGML
@c  LocalWords: html mumamo mmm Juanjo Torsten Martinsen
@c  LocalWords: Vinai Kopp Stig Marcey McMaster Folgmann
@c  LocalWords: Rosenfeld Yankowski Sammartino Bakken
@c  LocalWords: ppercot Rennebarth Gerrit Riessen Mc Sween
@c  LocalWords: Skytta Tesio fdl cp Lennart Borgman Monnier
@c  LocalWords: texi printindex fn ky RET etags ESC CVS
@c  LocalWords: imenu menubar samp Turadg Aleahmad
@c  LocalWords: SourceForge Emacsen Hawley nXML vindex
@c  LocalWords: dirvars arglist FIXME speedbar vr minibuffer
@c  LocalWords: dwim nXhtml emacs makefile el uncommented
@c  LocalWords: online multi