PhD - PHP DocBook

About PhD

PhD is PHP's DocBook rendering system which is used to convert the PHP Manual into different output formats.

Requirements

PHP 8.0+
DOM, libXML2, XMLReader and SQLite3.

Rendering the PHP Documentation Sources

To render the PHP documentation, you will need to clone the documentation source files, doc-base and PhD.

To get the PHP documentation sources, clone them from the official GitHub repositories. To clone the English documentation:

$ git clone https://github.com/php/doc-en en

List of languages/repositories

Brazilian Portugues (doc-pt_br)
Chinese(Simplified) (doc-zh)
English (doc-en)
French (doc-fr)
German (doc-de)
Italian (doc-it)
Japanese (doc-ja)
Polish (doc-pl)
Romanian (doc-ro)
Russian (doc-ru)
Spanish (doc-es)
Turkish (doc-tr)
Ukrainian (doc-uk)

To check the documentation and combine it into one file, you need to clone PHP's doc-base repository

$ git clone https://github.com/php/doc-base

and run configure.php

$ php doc-base/configure.php

which will generate a .manual.xml file in the doc-base directory.

To render the documentation in xhtml format into the default ./output/ directory:

$ php phd/render.php -d doc-base/.manual.xml -P PHP -f xhtml

PhD's rendering options

Let's take a closer look at PhD and see what capabilities are available to us.

$ php phd/render.php --help
PhD version: 1.1.12
Copyright(c) 2007-2024 The PHP Documentation Group

    -v
    --verbose <int>            Adjusts the verbosity level
    -f <formatname>
    --format <formatname>      The build format to use
    -P <packagename>
    --package <packagename>    The package to use
    -I
    --noindex                  Do not index before rendering but load from cache
                                (default: false)
    -M
    --memoryindex              Do not save indexing into a file, store it in memory.
                                (default: false)
    -r
    --forceindex               Force re-indexing under all circumstances
                                (default: false)
    -t
    --notoc                    Do not rewrite TOC before rendering but load from
                                cache (default: false)
    -d <filename>
    --docbook <filename>       The Docbook file to render from
    -x
    --xinclude                 Process XML Inclusions (XInclude)
                                (default: false)
    -p <id[=bool]>
    --partial <id[=bool]>      The ID to render, optionally skipping its children
                                chunks (default to true; render children)
    -s <id[=bool]>
    --skip <id[=bool]>         The ID to skip, optionally skipping its children
                                chunks (default to true; skip children)
    -l
    --list                     Print out the supported packages and formats
    -o <directory>
    --output <directory>       The output directory (default: .)
    -F filename
    --outputfilename filename  Filename to use when writing standalone formats
                                (default: <packagename>-<formatname>.<formatext>)
    -L <language>
    --lang <language>          The language of the source file (used by the CHM
                                theme). (default: en)
    -c <bool>
    --color <bool>             Enable color output when output is to a terminal
                                (default: true)
    -C <filename>
    --css <filename>           Link for an external CSS file.
    -g <classname>
    --highlighter <classname>  Use custom source code highlighting php class
    -V
    --version                  Print the PhD version information
    -h
    --help                     This help
    -e <extension>
    --ext <extension>          The alternative filename extension to use,
                                including the dot. Use 'false' for no extension.
    -S <bool>
    --saveconfig <bool>        Save the generated config (default: false).

    -Q
    --quit                     Don't run the build. Use with --saveconfig to
                                just save the config.
    -k
    --packagedir               Use an external package directory.

As you can see, there are plenty of options to look into in PhD. The most important options are those which allow you to select a format and package to output your documentation to.

$ php phd/render.php --list
Supported packages:
        Generic
                xhtml
                bigxhtml
                manpage
        IDE
                xml
                funclist
                json
                php
                phpstub
        PEAR
                xhtml
                bigxhtml
                php
                chm
                tocfeed
        PHP
                xhtml
                bigxhtml
                php
                howto
                manpage
                pdf
                bigpdf
                kdevelop
                chm
                tocfeed
                epub
                enhancedchm

To select a format and package, you must use the -f [formatName] and -P [packageName] options.

E.g.: to generate the documentation in the same format used on php.net, use the PHP package's php format.

$ php phd/render.php -d .manual.xml -P PHP -f php

Syntax highlighting

Part of the documentation of programming languages is source code examples. PhD is able to colorize the source code of many types of source code with the help of highlighters.

To utilize syntax highlighting, your opening <programlisting> tags need a role attribute describing the type of source code. Examples are php, html and python.

NOTE: PhD currently only highlights the code if it is embedded in a CDATA section.

<programlisting role="php"><![CDATA[
<?php
echo "Hello world!";
?>
]]></programlisting>

By default, PhD uses the source code highlighter that is built into PHP itself which is only able to highlight PHP code.

If your documentation contains other types of source code or markup, you can write a custom syntax highlighter.

Writing a custom syntax highlighter

A syntax highlighter for PhD is nothing more than a simple PHP class that has two methods: factory and highlight.

factory is static, takes the format name (i.e. pdf, xhtml, troff) as its only parameter and returns the highlighter instance object for the given format. The method is called for each output format the documentation is rendered to.

highlight takes three parameters: text, role and format. It is called whenever a piece of source code needs to be highlighted and expects the highlighted source code to be returned in the format of the current rendering format.

Take a look at the provided highlighters, phpdotnet\phd\Highlighter, phpdotnet\phd\Highlighter_GeSHi and phpdotnet\phd\Highlighter_GeSHi11x. They will serve as good examples on how to implement your own highlighter.

Once you wrote your custom source code highlighting class, it's time to try it out.

php / phd