DragonFly On-Line Manual Pages
PHPSH(1) PHPSH(1)
NAME
phpsh - an interactive shell into a php codebase
SYNOPSIS
phpsh [-h] [-c | --codebase-mode] [-t | --test-file]
[-A | --no-autocomplete] [-C | --no-color] [-M | --no-multiline]
[-T | --no-ctags] [-X | --no-xdebug] [extra-includes...]
DESCRIPTION
phpsh starts and controls a command line PHP interpreter. You can load
arbitrary PHP files and pass expressions to the interpreter to
evaluate. Beginning with version 1.2 phpsh also supports PHP debugging
with xdebug.
Type php commands and they will be evaluted each time you hit enter.
Ex:
php> $msg = "hello world"
Put = at the beginning of a line as syntactic sugar for return. Ex:
php> = 2 + 2
4
phpsh will print any returned value (in yellow) and also assign the
last returned value to the variable $_. Anything printed to stdout
shows up blue, and anything sent to stderr shows up red.
You can enter multiline input, such as a multiline if statement. phpsh
will accept further lines until you complete a full statement, or it
will error if your partial statement has no syntactic completion. You
may also use ^C to cancel a partial statement.
You can use tab to autocomplete function names, global variable names,
constants, classes, and interfaces. If you are using ctags, then you
can hit tab again after you've entered the name of a function, and it
will show you the signature for that function. phpsh also supports all
the normal readline features, like ctrl-e, ctrl-a, and history (up,
down arrows).
Note that stdout and stderr from the underlying php process are
line-buffered; so php> for ($i = 0; $i < 3; $i++) {echo "."; sleep(1);}
will print the three dots all at once after three seconds. (echo ".\n"
would print one a second.)
OPTIONS
-c, --codebase-mode
Use "-c none" to load no codebase. See
/usr/local/etc/phpsh/phpshrc.php for other codebase modes.
-t, --test-file
Run a saved-phpsh-session unit test file. See test/ in the phpsh
distribution for examples.
-v, --verbose
Be more verbose, do not defer warnings about missing extensions.
-A, --no-autocomplete
Disable identifier autocomplete.
-C, --no-color
Do not try to change color for different types of output.
-M, --no-multiline
Disable support for multiline input.
-T, --no-ctags
Do not run ctags to index the code base.
-X, --no-xdebug
Do not load xdebug, disable PHP debugging support.
COMMANDS
h Display a help text.
r [files...]
Reload (e.g. after a code change). args to r append to add
includes, like: php> r ../lib/username.php (use absolute paths
or relative paths from where you start phpsh)
R [files...]
Like r, but change includes instead of appending.
d identifier
Get documentation for a function or other identifier. ex: php> d
my_function
D identifier
Like d, but gives more extensive documentation for builtins.
v identifier
Open vim read-only where a function or other identifer is
defined. ex: php> v some_function
V identifier
Open vim (not read-only) and reload (r) upon return to phpsh.
e identifier
Open emacs where a function or other identifer is defined. ex:
php> e some_function
x [=]function([args])
Execute function() with args under debugger (xdebug). Currently
geben for emacs is the only debug client supported. This command
requires X11.
c [files...]
Append new includes without restarting; display includes.
C [files...]
Change includes without restarting; display includes.
! Execute a shell command. ex: php> ! pwd
q Quit (ctrl-D also quits)
DEBUGGING
Requirements
Beginning with version 1.2 phpsh supports interactive PHP debugging via
Xdebug (http://xdebug.org/). If you want to debug PHP code from phpsh,
you will need xdebug.so compiled for your PHP version and build type
(debug or nodebug) and installed in the PHP extensions directory or in
a location given by Xdebug configuration variable (see below). The
default configuration currently requires X Windows and debugclient, a
simple Xdebug protocol client distributed with xdebug. See
XdebugClientPath configuration setting below for details.
Starting a debugger
The x command starts debugging of the specified function call in the
current phpsh execution environment. Unless configured otherwise, phpsh
will try to start emacs and load geben PHP debugging frontend
http://code.google.com/p/geben-on-emacs/. Emacs appearance can be
customized through configuration settings described below.
Debugging session
The execution stops at the first line of function, geben and xdebug
module in PHP take over control over the function execution. All basic
interactive debugging actions, such as stepping through lines, setting
breakpoints, entering functions, examining variables, are supported.
Debugging session terminates as soon as the function returns control to
phpsh. The default behavior at that point is to minimize Emacs without
closing it, this can be customized through configuration settings in
[Emacs] section of the phpsh config file. All breakpoints set during
debugging session are saved by geben and will be set automatically when
the next debugging session starts. If Emacs is terminated by user, all
breakpoints set so far are lost. When phpsh exits it kills its Emacs
process if one is running.
Other debug clients
If ClientPort is set, phpsh will expect an external xdebug client to
listen on that port and will try to connect to the client. If
connection is successful, phpsh will not attempt to start emacs, but
will be using the client as the debugging frontend. This can be used,
for example, to run debugging from phpsh without X Windows by starting
emacs with geben manually in another terminal.
CONFIGURATION
Config file support was added in phpsh-1.2. When phpsh starts up it
tries to read its configuration from /usr/local/etc/phpsh/config, then
from $HOME/.phpsh/config. If either file is not present or not
readable, it is ignored. Entries in the per-user config file
$HOME/.phpsh/config override the corresponding entries in the host-wide
config file /usr/local/etc/phpsh/config.
The config file consists of sections containing key:value pairs. Lines
starting with # are ignored. All settings are optional and have
reasonable default values. Section names are in brackets. A section
name must be present in the config file if any settings in that section
are present. The following configuration settings are supported:
[Debugging]
Xdebug
Location of xdebug.so, a debugging extension for the Zend
engine. If set to "yes" (without quoutes) phpsh will look for
xdebug.so in the extensions directory reported by php-config.
Set to "no" to disable loading xdebug into php VM. This will
disable all debugging support. Default is "yes".
DebugClient
Command to run to start an xdebug client. Default is "emacs",
which starts emacs under X and loads Geben, an xdebug frontend
written in Emacs lisp.
ClientTimeout
Number of seconds to wait for debug client to start up and begin
listening for xdebug connections. Default is 60. If set to
"none", 0 or a negative number phpsh will wait until killed.
ClientHost
Name of host on which debug client is running. You should not
set this unless you are running your own debug client. Default
is localhost.
ClientPort
Port on which the debug client listens for xdebug connections.
By default ProxyPort+1 is used.
ProxyPort
The port on which the proxy should listen for xdebug
connections. By default the proxy will use the lowest available
even-numbered port between 9002 and 9998. If DebugClient is also
unset or set to "emacs", the proxy will configure emacs PHP
debug client to listen on the next port up.
X11 If set to "yes", phpsh looks at the value of DISPLAY environment
variable to determine how it should start debug client. If
DISPLAY is set, debug client is started in a separate X window,
otherwise it is started without X support in the terminal where
phpsh is running. If this option is set to "no", debug client
will always be started in terminal. If set to "require", debug
client will not be started unless DISPLAY is set. Default is
"yes".
Help This option works only if DebugClient is unset or set to
"emacs". If set to "yes", when emacs starts it will show a help
screen for its PHP debugging mode. If set to "no", a help file
will be loaded into an Emacs buffer but will not be displayed on
startup. Default is "no".
LogDBGp
If "yes", debug proxy will log DBGp (xdebug protocol) messages
to file dbgp.log in the current directory. Defaul is "no".
[Emacs]
The following options control the appearance of Emacs debug client.
They take effect only if DebugClient option above is set to "emacs" or
left unset.
ForegroundColor
Foreground color of default typeface. Default is black.
BackgroundColor
Background color of default typeface when a debugging session is
in progress. Default is white.
InactiveColor
Background color of default typeface when Emacs window is
inactive (no debugging in progress). Default is grey75.
InactiveMinimize
If set to "yes", minimize (iconify) Emacs window upon completion
of debugging session. Restore (deiconify) window when next
session begins. Default is "yes". On some X servers Emacs fails
to deiconify correctly. If that's the case for you, set this to
"no".
FontFamily
Font family to use for default Emacs face. If not set, Emacs
defaults are used.
FontSize
Font size in points for default Emacs face. If unset, Emacs
defaults are used.
XdebugClientPath
Emacs debug client, geben, uses a simple command-line debug
client, aptly called debugclient, a part of xdebug package. This
setting controls the location that Emacs should use to start
debugclient. Default is just to pass "debugclient" to shell.
AUTHOR
Written by Charles Chiever and Dan Corson phpsh@facebook.com
PHP debugging and config file support written by Mark Marchukov
PHPSH(1)