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

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:

PHP_HOME=%SystemDrive%\\php

Path it.

Here’s my current Path Statement:
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:

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:

[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
extension=php_xsl.dll.
  1. Set
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:

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

Current Stable Release:

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:

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

and save the output to “C:\php”.

Open an elevated command prompt, and navigate to:

C:\\php

At the command prompt, type:

php go-pear.phar

and press Enter.

Type:

system

Press Enter,

And then press Enter.

Configure the Environment Variables

Simply double-click:

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:

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
  2. Temporary directory for processing : C:\php\tmp
  3. Temporary directory for downloads : C:\php\tmp
  4. Binaries directory : C:\php
  5. PHP code directory ($php_dir) : C:\php\pear
  6. Documentation directory : C:\php\docs
  7. Data directory : C:\php\data
  8. User-modifiable configuration files directory : C:\php\cfg
  9. Public Web Files directory : C:\php\www
  10. Tests directory : C:\php\tests
  11. Name of configuration file : C:\WINDOWS\pear.ini
  12. Path to CLI php.exe : C:\php

1-12, ‘all’ or Enter to continue (I pressed Enter).

Install Log

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:

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

E.g., Output

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

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).

C:\\>phpdoc run -h

Usage:

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:
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:

$ 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





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.


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





Running phpDocumentor2 from the Command Line


PHP script


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





Batch file


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





or


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


?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:


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.


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


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


<?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.


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.


@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


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


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.
    2. 

  2. Create a new directory called TeleSignTemplate.
    3. 

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



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:


/**
 * 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.


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.


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


C:\\inetpub\\wwwroot\\





Then open your web browser, and go to the URL:


http://localhost//