phpsh(1)
========

NAME
----
phpsh - an interactive shell into a php codebase

SYNOPSIS
--------
[verse]
'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 /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.

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. If debugging is done in a separate X window, 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 are lost. Breakpoints are also cleared
at the end of each debugging session if debugging is run in the terminal
because X is unavailable or terminal debugging is requested via the "X11"
configuration option (see CONFIGURATION). When phpsh exits it kills its Emacs
process if one is running.

Geben debugger commands
~~~~~~~~~~~~~~~~~~~~~~~

g::
     run
i::
     step into
o::
     step over
r::
     step out
q::
     stop debugging

b::
     set breakpoint on current line
B::
     set breakpoint at specified function or exception
u::
     delete breakpoint on current line

e::
     eval a PHP expression, prints to *Messages* buffer

d::
     print stack trace, move up and down
w::
     go to current line
v::
     view locals and superglobals

?::
     geben mode help

See also "Help" option in CONFIGURATION section below.


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 /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
/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 the DISPLAY environment 
  variable to determine how it should start the debug client. If DISPLAY 
  is set, the 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", the debug client will always be started in
  the terminal. If set to "require", the 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 configuration support added by Mark Marchukov
