PHP Cookbook
############

Documenting a fresh installation, to document the telesign_php SDK.

Install the Prerequisites
*************************

Prerequesites

* PHP
	* Apache HTTP Web Server
	
* XSL Extension for PHP
	* Graphviz

Then you can install **PHPDomentor2**.

Install Apache HTTP Web Server (Method Recommended by http://windows.php.net/qa/)
=================================================================================

The folks at Windows PHP.net built their PHP installer using Apache HTTP Web Server builds from Apache Lounge. The guys at Apache Lounge used VS 2012 to build from the latest source files from Apache.org - so you don't have to worry about Apache.org not having current Win32 builds.

Drop Point:	http://www.apachelounge.com/viewtopic.php?p=23836.
Redirects to:	http://www.apachelounge.com/viewtopic.php?p=24281 (updated with VS 2012 SP 1).

There are three files to download and install:
----------------------------------------------

Win64: httpd-2.4.4-win64-VC11.zip:	http://www.apachelounge.com/download/win64/modules-2.4/modules-2.4-win64-VC11.zip
Win64:  modules-2.4-win64-VC11.zip:	http://www.apachelounge.com/download/win64/modules-2.4/modules-2.4-win64-VC11.zip
Visual C++ Redistributable for VS 2012 Update 1 (this is for folks who don't have VS 2012):	http://www.microsoft.com/en-us/download/details.aspx?id=30679

Open the first zip file, and follow the instructions in ReadMe.txt.
-------------------------------------------------------------------

Also, I found a good set of instructions here: http://www.sitepoint.com/how-to-install-apache-on-windows/.

To run the Apache Web Server as a service, open a command prompt and enter:
---------------------------------------------------------------------------

C:\\Apache24\\bin\\httpd.exe -k install

To get Apache Web Server to startup every time you logon to Windows:
--------------------------------------------------------------------

Open Computer Management (by right-clicking Computer in Explorer), and navigate to Services and Applications. Look for the service called Apache2.4, and double-click it. Make sure Startup type=Automatic.

To run ApacheMonitor
--------------------

either double-click ApacheMonitor.exe, or create a TaskScheduler task to run it every time you log onto the system. This is a good idea because you can set it to run with the highest priveleges.

Create an environment variable
------------------------------

(just for the heck of it - I'm not sure it's necessary).
APACHE_HOME=%SystemDrive%\\Apache24

Path its /bin directory.
------------------------

;%APACHE_HOME%\\bin

Modify the initialization file "C:\\Apache24\\conf\\httpd.conf"
---------------------------------------------------------------

Here are the specific lines that I added to my httpd.conf.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bro

	ServerRoot "c:/Apache24"
	Listen *:80
	LoadModule cgi_module modules/mod_cgi.so
	Action application/x-httpd-php "/php/php-cgi.exe"
	ServerAdmin chris.boorman@gullinx.com
	ServerName localhost:80
	<Directory />
	    AllowOverride none
	    Require all denied
	</Directory>
	DocumentRoot "c:/Apache24/htdocs"
	<Directory c:/Apache24/htdocs>
	    Options Indexes FollowSymLinks Includes ExecCGI    
	    AllowOverride All    
	    Require all granted
	</Directory>
	<IfModule dir_module>
	    DirectoryIndex index.php
	</IfModule>
	<IfModule alias_module>
	    ScriptAlias /cgi-bin/ "c:/Apache24/cgi-bin/"
	    ScriptAlias /php/ "c:/php/"
	</IfModule>
	<Directory c:/Apache24/cgi-bin>
	    AllowOverride None
	    Options None
	    Require all granted
	</Directory>
	<Directory c:/php>
	    Require all granted
	</Directory>
	<IfModule mime_module>
	    TypesConfig conf/mime.types
	    AddType application/x-compress .Z
	    AddType application/x-gzip .gz .tgz
	    AddType application/x-httpd-php .php
	</IfModule>

Here are all of the uncommented lines in my httpd.conf file:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bro

	ServerRoot "c:/Apache24"
	Listen *:80
	LoadModule access_compat_module modules/mod_access_compat.so
	LoadModule actions_module modules/mod_actions.so
	LoadModule alias_module modules/mod_alias.so
	LoadModule allowmethods_module modules/mod_allowmethods.so
	LoadModule asis_module modules/mod_asis.so
	LoadModule auth_basic_module modules/mod_auth_basic.so
	LoadModule authn_core_module modules/mod_authn_core.so
	LoadModule authn_file_module modules/mod_authn_file.so
	LoadModule authz_core_module modules/mod_authz_core.so
	LoadModule authz_groupfile_module modules/mod_authz_groupfile.so
	LoadModule authz_host_module modules/mod_authz_host.so
	LoadModule authz_user_module modules/mod_authz_user.so
	LoadModule autoindex_module modules/mod_autoindex.so
	LoadModule cgi_module modules/mod_cgi.so
	LoadModule dir_module modules/mod_dir.so
	LoadModule env_module modules/mod_env.so
	LoadModule include_module modules/mod_include.so
	LoadModule isapi_module modules/mod_isapi.so
	LoadModule log_config_module modules/mod_log_config.so
	LoadModule mime_module modules/mod_mime.so
	LoadModule negotiation_module modules/mod_negotiation.so
	LoadModule setenvif_module modules/mod_setenvif.so
	Action application/x-httpd-php "/php/php-cgi.exe"
	<IfModule unixd_module>
	User daemon
	Group daemon
	</IfModule>
	ServerAdmin chris.boorman@gullinx.com
	ServerName localhost:80
	<Directory />
	    AllowOverride none
	    Require all denied
	</Directory>
	DocumentRoot "c:/Apache24/htdocs"
	<Directory c:/Apache24/htdocs>
	    Options Indexes FollowSymLinks Includes ExecCGI
	    AllowOverride All
	    Require all granted
	</Directory>
	<IfModule dir_module>
	    DirectoryIndex index.php
	</IfModule>
	<Files ".ht*">
	    Require all denied
	</Files>
	ErrorLog "logs/error.log"
	LogLevel warn
	<IfModule log_config_module>
	    LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined
	    LogFormat "%h %l %u %t \"%r\" %>s %b" common
	    <IfModule logio_module>
	      LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" %I %O" combinedio
	    </IfModule>
	    CustomLog "logs/access.log" common
	</IfModule>
	<IfModule alias_module>
	    ScriptAlias /cgi-bin/ "c:/Apache24/cgi-bin/"
	    ScriptAlias /php/ "c:/php/"
	</IfModule>
	<IfModule cgid_module>
	</IfModule>
	<Directory c:/Apache24/cgi-bin>
	    AllowOverride None
	    Options None
	    Require all granted
	</Directory>
	<Directory c:/php>
	    Require all granted
	</Directory>
	<IfModule mime_module>
	    TypesConfig conf/mime.types
	    AddType application/x-compress .Z
	    AddType application/x-gzip .gz .tgz
	    AddType application/x-httpd-php .php
	</IfModule>
	<IfModule proxy_html_module>
		Include conf/extra/proxy-html.conf
	</IfModule>
	<IfModule ssl_module>
	SSLRandomSeed startup builtin
	SSLRandomSeed connect builtin
	</IfModule>

Test to see if your Apache Web Server installation Works
---------------------------------------------------------

When the installation completes, open IE, and then open http://localhost. You should see the text "It works".
If instead, you get an error, then open Apache Monitor, and Start the server.

Now proceed with installing PHP.

Install PHP
===========

I installed from: http://windows.php.net/qa/.

I wanted to try-out an x64 build, but the only ones were for PHP 5.5.0 Beta 4 - so what the heck. Since I'm not using IIS, I can use the Threadsafe version.

VC11 x64 Thread Safe (2013-Apr-25 18:24:59)
-------------------------------------------

http://windows.php.net/downloads/qa/php-5.5.0beta4-Win32-VC11-x64.zip

Save the zip archive to a local disk
------------------------------------

(I saved it to X:\\php\\5.5.0 Beta\\).

Open it with WinZip
-------------------

and extract it to C:\\php\\.

Create a system environment variable for the php executibles in C:\\php:
-------------------------------------------------------------------------

.. code-block:: bro

	PHP_HOME=%SystemDrive%\\php

Path it.
--------

Here's my current Path Statement:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bro

	C:\\WINDOWS
	C:\\WINDOWS\\system32
	C:\\WINDOWS\\System32\\Wbem
	C:\\WINDOWS\\System32\\WindowsPowerShell\\v1.0
	C:\\apache-ant-1.8.4\\bin
	C:\\Program Files (x86)\\Git\\cmd
	C:\\Program Files (x86)\\Git\\bin
	C:\\Users\\Chris\\src
	C:\\Program Files\\Java\\jdk1.7.0_15\\bin
	C:\\Program Files\\Java\\jdk1.7.0_15\\bin
	C:\\Program Files\\Java\\jre7\\bin
	C:\\Program Files (x86)\\GnuWin32\\bin
	C:\\Python27
	C:\\Python27\\Scripts
	C:\\Program Files (x86)\\AMD APP\\bin\\x86
	C:\\Program Files (x86)\\AMD APP\\bin\\x86_64
	C:\\Program Files (x86)\\ATI Technologies\\ATI.ACE\\Core-Static
	C:\\Program Files (x86)\\NVIDIA Corporation\\PhysX\\Common
	C:\\Program Files (x86)\\QuickTime\\QTSystem
	C:\\Program Files (x86)\\Windows Kits\\8.0\\Windows Performance Toolkit
	C:\\Program Files (x86)\\Beyond Compare 3\\
	C:\\Program Files\\MiKTeX 2.9\\miktex\\bin\\x64\\
	C:\\php
	C:\\php\\dev
	C:\\php\\ext
	C:\\php\\pear

Now you need to configure the Apache server to run PHP engine as CGI to support PHP scripts.
--------------------------------------------------------------------------------------------

I.e., so when you open a \\*.php file with IE, it executes the php code inside.

You do this, and more, by creating and modifying the file "C:\\php\\php.ini".

Start by saving "php.ini-production" as "php.ini."

Here are the custom directives that I added:

.. code-block:: bro

	doc_root = "C:\\Apache24\\htdocs"
	user_dir = "C:\\Apache24\\htdocs"
	extension_dir = "C:\\php\\ext"
	date.timezone = America/Los_Angeles

Here's the contents of my entire php.ini file, but with all the commented lines removed:

.. code-block:: bro

	[PHP]
	engine = On
	short_open_tag = Off
	asp_tags = Off
	precision = 14
	output_buffering = 4096
	zlib.output_compression = Off
	implicit_flush = Off
	unserialize_callback_func =
	serialize_precision = 17
	disable_functions =
	disable_classes =
	zend.enable_gc = On
	expose_php = On
	max_execution_time = 30
	max_input_time = 60
	memory_limit = 128M
	error_reporting = E_ALL & ~E_DEPRECATED & ~E_STRICT
	display_errors = Off
	display_startup_errors = Off
	log_errors = On
	log_errors_max_len = 1024
	ignore_repeated_errors = Off
	ignore_repeated_source = Off
	report_memleaks = On
	track_errors = Off
	html_errors = On
	variables_order = "GPCS"
	request_order = "GP"
	register_argc_argv = Off
	auto_globals_jit = On
	post_max_size = 8M
	auto_prepend_file =
	auto_append_file =
	default_mimetype = "text/html"
	doc_root = "C:\\Apache24\\htdocs"
	user_dir = "C:\\Apache24\\htdocs"
	extension_dir = "C:\\php\\ext"
	enable_dl = Off
	file_uploads = On
	upload_max_filesize = 2M
	max_file_uploads = 20
	allow_url_fopen = On
	allow_url_include = Off
	default_socket_timeout = 60
	extension=php_curl.dll
	extension=php_gd2.dll
	extension=php_mbstring.dll
	extension=php_mysql.dll
	extension=php_mysqli.dll
	extension=php_pdo_mysql.dll
	extension=php_xmlrpc.dll
	[CLI Server]
	cli_server.color = On
	[Date]
	date.timezone = America/Los_Angeles
	[filter]
	[iconv]
	[intl]
	[sqlite]
	[sqlite3]
	[Pcre]
	[Pdo]
	[Pdo_mysql]
	pdo_mysql.cache_size = 2000
	pdo_mysql.default_socket=
	[Phar]
	[mail function]
	SMTP = localhost
	smtp_port = 25
	mail.add_x_header = On
	[SQL]
	sql.safe_mode = Off
	[ODBC]
	odbc.allow_persistent = On
	odbc.check_persistent = On
	odbc.max_persistent = -1
	odbc.max_links = -1
	odbc.defaultlrl = 4096
	odbc.defaultbinmode = 1
	[Interbase]
	ibase.allow_persistent = 1
	ibase.max_persistent = -1
	ibase.max_links = -1
	ibase.timestampformat = "%Y-%m-%d %H:%M:%S"
	ibase.dateformat = "%Y-%m-%d"
	ibase.timeformat = "%H:%M:%S"
	[MySQL]
	mysql.allow_local_infile = On
	mysql.allow_persistent = On
	mysql.cache_size = 2000
	mysql.max_persistent = -1
	mysql.max_links = -1
	mysql.default_port =
	mysql.default_socket =
	mysql.default_host =
	mysql.default_user =
	mysql.default_password =
	mysql.connect_timeout = 60
	mysql.trace_mode = Off
	[MySQLi]
	mysqli.max_persistent = -1
	mysqli.allow_persistent = On
	mysqli.max_links = -1
	mysqli.cache_size = 2000
	mysqli.default_port = 3306
	mysqli.default_socket =
	mysqli.default_host =
	mysqli.default_user =
	mysqli.default_pw =
	mysqli.reconnect = Off
	[mysqlnd]
	mysqlnd.collect_statistics = On
	mysqlnd.collect_memory_statistics = Off
	[OCI8]
	[PostgreSQL]
	pgsql.allow_persistent = On
	pgsql.auto_reset_persistent = Off
	pgsql.max_persistent = -1
	pgsql.max_links = -1
	pgsql.ignore_notice = 0
	pgsql.log_notice = 0
	[Sybase-CT]
	sybct.allow_persistent = On
	sybct.max_persistent = -1
	sybct.max_links = -1
	sybct.min_server_severity = 10
	sybct.min_client_severity = 10
	[bcmath]
	bcmath.scale = 0
	[browscap]
	[Session]
	session.save_handler = files
	session.use_cookies = 1
	session.use_only_cookies = 1
	session.name = PHPSESSID
	session.auto_start = 0
	session.cookie_lifetime = 0
	session.cookie_path = /
	session.cookie_domain =
	session.cookie_httponly =
	session.serialize_handler = php
	session.gc_probability = 1
	session.gc_divisor = 1000
	session.gc_maxlifetime = 1440
	session.bug_compat_42 = Off
	session.bug_compat_warn = Off
	session.referer_check =
	session.cache_limiter = nocache
	session.cache_expire = 180
	session.use_trans_sid = 0
	session.hash_function = 0
	session.hash_bits_per_character = 5
	url_rewriter.tags = "a=href,area=href,frame=src,input=src,form=fakeentry"
	[MSSQL]
	mssql.allow_persistent = On
	mssql.max_persistent = -1
	mssql.max_links = -1
	mssql.min_error_severity = 10
	mssql.min_message_severity = 10
	mssql.compatability_mode = Off
	mssql.secure_connection = Off
	[Assertion]
	[COM]
	[mbstring]
	[gd]
	[exif]
	[Tidy]
	tidy.clean_output = Off
	[soap]
	soap.wsdl_cache_enabled=1
	soap.wsdl_cache_dir="/tmp"
	soap.wsdl_cache_ttl=86400
	soap.wsdl_cache_limit = 5
	[sysvshm]
	[ldap]
	ldap.max_links = -1
	[mcrypt]
	[dba]
	[opcache]

Enable the XSL Extension for PHP
--------------------------------

In your php.ini
 
1. Uncomment the line

.. code-block:: bro

	extension=php_xsl.dll.

2. Set

.. code-block:: bro

	extension_dir = "C:\\php\\ext".

To Confirm:
^^^^^^^^^^^

1. In a test.php page: <?php phpinfo() ?>

2. Run test.php

3. Search for "libxslt Version".

	It should return a version number in a XSL headed table.

Install Graphviz
================

Drop Point:

.. code-block:: bro

	http://www.graphviz.org/Download_windows.php

Current Stable Release:

.. code-block:: bro

	http://www.graphviz.org/pub/graphviz/stable/windows/graphviz-2.30.1.msi

Run the msi file.

Accept the default install location.

Set to Everyone.

Install PEAR
============

Run this from IE:

.. code-block:: shell-session

	http://pear.php.net/go-pear.phar

and save the output to "C:\\php".

Open an elevated command prompt, and navigate to:

.. code-block:: shell-session

	C:\\php

At the command prompt, type:

.. code-block:: shell-session

	php go-pear.phar

and press **Enter**.

Type:

.. code-block:: shell-session

	system

Press **Enter**,

And then press **Enter**.

Configure the Environment Variables
-----------------------------------

Simply double-click:

.. code-block:: shell-session

	C:\\php\\PEAR_ENV.reg

Test it to see if it works.
---------------------------

Close and reopen the elevated command window.

Type pear, and then press Enter. You should see a list of PEAR commands.

Type pear version, and then press Enter.

Here's a listing from my elevated command prompt:
-------------------------------------------------

.. code-block:: shell-session

	Microsoft Windows [Version 6.2.9200]
	(c) 2012 Microsoft Corporation. All rights reserved.
	
	C:\\WINDOWS\\system32>cd \\
	
	C:\\>cd php
	
	C:\\php>php go-pear.phar
	
	Are you installing a system-wide PEAR or a local copy?
	system or local:

I typed system, and the hit Enter.

Below is a suggested file layout for your new PEAR installation.
-----------------------------------------------------------------

To change individual locations, type the number in front of the directory.

Type 'all' to change all of them or simply press Enter to accept these locations.

1. Installation base ($prefix)                   : C:\\php
#. Temporary directory for processing            : C:\\php\\tmp
#. Temporary directory for downloads             : C:\\php\\tmp
#. Binaries directory                            : C:\\php
#. PHP code directory ($php_dir)                 : C:\\php\\pear
#. Documentation directory                       : C:\\php\\docs
#. Data directory                                : C:\\php\\data
#. User-modifiable configuration files directory : C:\\php\\cfg
#. Public Web Files directory                    : C:\\php\\www
#. Tests directory                               : C:\\php\\tests
#. Name of configuration file                    : C:\\WINDOWS\\pear.ini
#. Path to CLI php.exe                           : C:\\php

1-12, 'all' or **Enter** to continue (I pressed **Enter**).

Install Log
-----------

.. code-block:: shell-session

	Beginning install...
	
	Configuration written to C:\\WINDOWS\\pear.ini...
	
	Initialized registry...
	
	Preparing to install...
	
	installing phar://C:/php/go-pear.phar/PEAR/go-pear-tarballs/Archive_Tar-1.3.11.tar...
	installing phar://C:/php/go-pear.phar/PEAR/go-pear-tarballs/Console_Getopt-1.3.1.tar...
	installing phar://C:/php/go-pear.phar/PEAR/go-pear-tarballs/PEAR-1.9.4.tar...
	installing phar://C:/php/go-pear.phar/PEAR/go-pear-tarballs/Structures_Graph-1.0.4.tar...
	installing phar://C:/php/go-pear.phar/PEAR/go-pear-tarballs/XML_Util-1.2.1.tar...
	
	install ok: channel://pear.php.net/Archive_Tar-1.3.11
	install ok: channel://pear.php.net/Console_Getopt-1.3.1
	install ok: channel://pear.php.net/Structures_Graph-1.0.4
	install ok: channel://pear.php.net/XML_Util-1.2.1
	install ok: channel://pear.php.net/PEAR-1.9.4
	
	PEAR: Optional feature webinstaller available (PEAR's web-based installer)
	PEAR: Optional feature gtkinstaller available (PEAR's PHP-GTK-based installer)
	PEAR: Optional feature gtk2installer available (PEAR's PHP-GTK2-based installer)
	PEAR: To install optional features use "pear install pear/PEAR#featurename"
	
	** WARNING! Old version found at C:\\php, please remove it or be sure to use the new c:\\php\\pear.bat command
	
	The 'pear' command is now at your service at c:\\php\\pear.bat
	
	* WINDOWS ENVIRONMENT VARIABLES *
	For convenience, a REG file is available under C:\\phpPEAR_ENV.reg. This file creates ENV variables for the current user. Double-click this file to add it to the current user registry.

Install PhpDocumentor2
**********************

Open an elevated commmand prompt, and type:

.. code-block:: shell-session

	pear channel-discover pear.phpdoc.org
	pear install phpdoc/phpDocumentor-alpha

E.g., Output
============

.. code-block:: shell-session
	
	C:\\>pear channel-discover pear.phpdoc.org
	Adding Channel "pear.phpdoc.org" succeeded
	Discovery of channel "pear.phpdoc.org" succeeded
	
	C:\\>pear install phpdoc/phpDocumentor-alpha
	downloading phpDocumentor-2.0.0a12.tgz ...
	Starting to download phpDocumentor-2.0.0a12.tgz (1,338,503 bytes)
	/........................................................................................................................................................................................................................................................................done: 1,338,503 bytes
	
	install ok: channel://pear.phpdoc.org/phpDocumentor-2.0.0a12

PhpDocumentor2 Installation Details
===================================

The installation directory

.. code-block:: shell-session

	C:\\php\\pear\\phpDocumentor

There is now a file called *phpdoc.bat* in *C:\\php*.

.. Note::
	phpDocumentor supports a whole range of options to configure the output of your documentation.

To Run PhpDocumentor2
=====================

Execute the following command (for the most basic usage).

.. code-block:: shell-session

	C:\\>phpdoc run -h

Usage:
------

.. code-block:: shell-session

	project:run [-t|--target[="..."]] [-f|--filename[="..."]] [-d|--directory[="..."]] [--encoding[="..."]] [-e|--extensions[="..."]] [-i|--ignore[="..."]] [--ignore-tags[="..."]] [--hidden] [--ignore-symlinks] [-m|--markers[="..."]] [--title[="..."]] [--force] [--validate] [--visibility[="..."]] [--defaultpackagename[="..."]] [--sourcecode] [-p|--progressbar] [--template[="..."]] [--parseprivate] 
	
	[-c|--config[="..."]].

Aliases:
^^^^^^^^

.. code-block:: shell-session

	run

Options:
^^^^^^^^

==================== ========== ==============================================================================================================================================================================
Option               Short-form Description
==================== ========== ==============================================================================================================================================================================
--target             -t         Path where to store the generated output
--filename           -f         Comma-separated list of files to parse. The wildcards ? and * are supported (multiple values allowed)
--directory          -f         Comma-separated list of directories to (recursively) parse (multiple values allowed)
--encoding                      Encoding to be used to interpret source files with
--extensions         -e         Comma-separated list of extensions to parse, defaults tophp, php3 and phtml (multiple values allowed)
--ignore             -i         Comma-separated list of file(s) and directories that will be ignored. Wildcards * and ? are supported (multiple values allowed)
--ignore-tags                   Comma-separated list of tags that will be ignored, defaults to none. package, subpackage and ignore may not be ignored. (multiple values allowed)
--hidden                        Set to on to descend into hidden directories (directories starting with '.'), default is on --ignore-symlinks     Ignore symlinks to other files or directories, default is on
--markers            -m         Comma-separated list of markers/tags to filter (default:["TODO","FIXME"]) (multiple values allowed)
--title                         Sets the title for this project; default is the phpDocumentor logo
--force                         Forces a full build of the documentation, does not increment existing documentation
--validate                      Validates every processed file using PHP Lint, costs a lot of performance
--visibility                    Specifies the parse visibility that should be displayed in the documentation (comma seperated e.g. "public,protected")
--defaultpackagename            Name to use for the default package. (default: "Default")
--sourcecode                    Whether to include syntax highlighted source code
--progressbar        -p         Whether to show a progress bar; will automatically quietlogging to stdout
--template                      Name of the template to use (optional) (multiple values allowed)
--parseprivate                  Whether to parse DocBlocks marked with @internal tag
--config             -c         Location of a custom configuration file
==================== ========== ==============================================================================================================================================================================

Help:
^^^^^

**phpDocumentor** creates documentation from PHP source files. The simplest way to use it is:

.. code-block:: shell-session

	$ phpdoc run -d [directory to parse] -t [output directory]

This parses every file ending with .php, .php3 and .phtml in /<directory to parse/> 
and then output a HTML site containing easily readable documentation in /<output directory/>.

**phpDocumentor** looks for a *phpdoc.dist.xml* or *phpdoc.xml* file in your current working directory, 
and use it to *override* the default settings.
In the configuration file can you specify the same settings (and more) as the command line provides.

Other commands
^^^^^^^^^^^^^^

In addition to this command phpDocumentor also supports additional commands:

====================== 
Command
====================== 
help
list
parse
run
transform
project
project:parse
project:run
project:transform
template
template:generate
template:list
template:package
====================== 

You can get a more detailed listing of the commands using the list command, 
and you can get help on a command by prefixing the word help to the command name.

Optionally
==========

Set the environment variable to

.. code-block:: bro

PHPBIN=php.exe

Install PHP_DocBlockGenerator
*****************************

I didn't use this tool, but you might try it next time. It adds DocBlock stubs to source code files.

.. code-block:: html

	http://pear.php.net/package/PHP_DocBlockGenerator

Running phpDocumentor2 from the Command Line

PHP script

.. code-block:: shell-session

	C:\\Users\\Chris\\src\\php_telesign>php.exe C:\\php\\phpdoc.php project:run -dtelesign -tdoc

Batch file

.. code-block:: shell-session

	C:\\Users\\Chris\\src\\php_telesign>phpdoc.bat project:run -d telesign -t doc

or

.. code-block:: shell-session

	C:\\Users\\Chris\\src\\php_telesign\\docs>phpdoc.bat project:run -d ..\\telesign -t doc\\_build\\html

To Configure phpDocumentor2 as an Eclipse External Builder
============================================================

.. code-block:: xml

	?xml version="1.0" encoding="UTF-8" standalone="no"?>
	<launchConfiguration type="org.eclipse.ui.externaltools.ProgramBuilderLaunchConfigurationType">
		<stringAttribute key="org.eclipse.debug.core.ATTR_REFRESH_SCOPE" value="${project}"/>
		<booleanAttribute key="org.eclipse.debug.ui.ATTR_LAUNCH_IN_BACKGROUND" value="false"/>
		<stringAttribute key="org.eclipse.ui.externaltools.ATTR_LOCATION" value="${phpDocumentor2_bat}"/>
		<stringAttribute key="org.eclipse.ui.externaltools.ATTR_RUN_BUILD_KINDS" value="full,incremental,"/>
		<stringAttribute key="org.eclipse.ui.externaltools.ATTR_TOOL_ARGUMENTS" value="run -d telesign -t doc"/>
		<booleanAttribute key="org.eclipse.ui.externaltools.ATTR_TRIGGERS_CONFIGURED" value="true"/>
		<stringAttribute key="org.eclipse.ui.externaltools.ATTR_WORKING_DIRECTORY" value="${workspace_loc:/php_telesign}"/>
	</launchConfiguration>

Creating a Custom phpDocumentor2 Template for TeleSign Branding
***************************************************************

TBD.

Notes
*****

PHP modules are packaged as archives in the format: \\*.phar
=============================================================

To install one, open a command prompt, and run it, like so:

.. code-block:: shell-session

	php C:\\Users\\Chris\\AppData\\Local\\Temp/composer.phar

Registry file to update environment variables
=============================================

Create a reg file with the following contents, and Merge it.

.. code-block:: shell-session

	Windows Registry Editor Version 5.00
	
	[HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment]
	"PHP_PEAR_BIN_DIR"="%PHP_HOME%"
	"PHP_PEAR_DATA_DIR"="%PHP_HOME%\\\data"
	"PHP_PEAR_DOC_DIR"="%PHP_HOME%\\docs"
	"PHP_PEAR_INSTALL_DIR"="%PHP_HOME%\\pear"
	"PHP_PEAR_PHP_BIN"="%PHP_HOME%\\php.exe"
	"PHP_PEAR_SYSCONF_DIR"="%PHP_HOME%\\PHP"
	"PHP_PEAR_TEST_DIR"="%PHP_HOME%\\tests"

Configuration File
******************

The configuration file is

.. code-block:: shell-session

	phpdoc.dist.xml

- and you place it in the working directory.

The Project Working Directory
=============================

To simplify things, I set the working directory to be the directory that Git uses for the project directory.

C:\\Users\\Chris\\src\\php_telesign\\
	
Contents of the Configuration File
==================================

.. code-block:: xml

	<?xml version="1.0" encoding="UTF-8" ?>
	<phpdoc>
		<title>
			<![CDATA[
				<b>The TeleSign PHP SDK</b>
			]]>
		</title>
		<files>
			<file>api.class.php</file>
		</files>
		<parser>
			<default-package-name>php.telesign</default-package-name>
			<target>doc/build/html</target>
		</parser>
		<transformer>
			<target>doc/build/html</target>
		</transformer>
		<logging>
			<level>warn</level>
			<paths>
				<default>{APP_ROOT}/data/log/{DATE}.log</default>
				<errors>{APP_ROOT}/data/log/{DATE}.errors.log</errors>
			</paths>
		</logging>
		<transformations>
			<template name="responsive" />
		</transformations>
	</phpdoc>

Usage
*****

If you've defined a configuration file, then all you have to do to regenerate the docs is run phpdoc from the root directory.

If you haven't defined a configuration file, then you must run phpdoc with arguments, as shown below.

.. code-block:: bro

	phpdoc -(d|f) [SOURCE_PATH] -t [TARGET_PATH]

Options
=======

====== ==============================
Option Description
====== ==============================
-d     Source Directory for input
-f     Single File to input
-t     Target Directory for output
====== ==============================

phpdoc.bat
==========

Revise this batch file so that it makes sense.

.. code-block:: bro

	@echo off

	if "%PHPBIN%" == "" set PHPBIN=%PHP_HOME%\\php.exe
	if "%PHPDOC_PATH%" == "" set PHPDOC_PATH=%SystemDrive%\\phpdoc

	:RUN

	"%PHPBIN%" "%PHPDOC_PATH%\\bin\\phpdoc.php" %*


To invoke it from C:\\phpdoc\\bin
----------------------------------

.. code-block:: bro

	phpdoc -f C:\\Users\\Chris\\src\\php_telesign_sdk\\ts\\telesign.class.php -t C:\\Users\\Chris\\src\\php_telesign_sdk\\doc\\build

To invoke it from C:\\Users\\Chris\\src\\php_telesign_sdk\\ts
=============================================================

.. code-block:: bro

	phpdoc -f telesign.class.php -t ..\\doc\\build
	
	php phpdoc.php -f telesign.class.php -t ..\\doc\\build
	
	php C:\\phpdoc\\bin\\phpdoc.php -f telesign.class.php -t ..\\doc\\build
	
	"C:\\phpdoc\\bin\\phpdoc.php"

Templates
*********

1. Open a Command Window, and navigate to the *doc* directory.

#. Create a new directory called *TeleSignTemplate*.

#. To generate the template skeleton, run the command of the followuing form.

.. code-block:: bro

	phpdoc template:generate -t <target path/> -n <template name/>

	From the doc directory, run the command:	phpdoc template:generate --target="TeleSignTemplate" --name="TeleSignTemplate"

	Results
	
	Generating directory structure
	Generating files
	Finished generating a new template at: TeleSignTemplate\\TeleSignTemplate

	.. Note::
	   When you run phpdoc, it copies your new template folder (and it's contents) into **C:\\phpdoc\\data\\templates**, and that's where it processes your customizations.

DocBlock
********
 
A **DocBlock** is an extended C++-style PHP comment that begins with */\*\** and has an *\** at the beginning of every line. 
DocBlocks precede the element they are documenting. 
Any line within a DocBlock that doesn't begin with a * will be ignored.
 
To document function "foo()", place the DocBlock immediately before the function declaration:

.. code-block:: bro

	
	/**
	 * This is a DocBlock comment
	 */
	function foo()
	{
	}

CheatSheet
**********

PHP programs are a series of PHP statements, executed one at a time. 
Here’s a list of the PHP statements (with syntax) that you use when writing PHP programs.

.. code-block:: bro

	array ( "key" => "value", … );
	
	die("message");
	
	do { block } while (condition);
	
	echo item;
	
	extract($array);
	
	for (startingval; endingval;incremnt) { block }
	
	foreach( $array as $key => $value) { block }
	
	function funcname(value,value,…) { block }
	
	header("Location: URL");
	
	if (condition) { block }
	   elseif (condition) { block }
	   else { block }
	
	number_format(number,decimals);
	
	session_start();
	
	session_destroy();
	
	switch var { case value statements break; … }
	
	unset();
	
	while (condition) { block }

Test
****

Create a new *\*.php* file called hello.php.

.. code-block:: php

	<html>
	 <head>
	  <title>PHP Test</title>
	 </head>
	 <body>
	 <?php
	 	echo '<p>Hello World!</p>';
	 	phpinfo();
	 ?>
	 </body>
	</html>

and place it in the root directory of you local host.

.. code-block:: bro

	C:\\inetpub\\wwwroot\\
	
Then open your web browser, and go to the URL:

.. code-block:: bro

	http://localhost//