Examples

Documenting PHP with Dexy

August 30, 2013   ·   By   ·   No Comments   ·   Posted in Examples

I just received a question about how to use Dexy to document procedural (non-OOP) PHP code. Here are some ways of using dexy to document PHP. These examples assume you already have familiarity with the contents of the Getting Started part of the guide.

Displaying Complete Files

Let’s take a simple example of an HTML file with embedded PHP:

<html>
<!-- @section "head" -->
<head>
<title>PHP Example</title>
</head>
<!-- @end -->
<?php

// examples taken from http://www.php.net/manual/en and modified

/// "assign-variables"
$b = $a = 5;
$a++;

/// "compare"
if ($a > $b) {
  echo "<p>a ($a) is bigger than b ($b)</p>";
  $b = $a;
}
/// @end
?>

<!-- @section "display-variables" -->
<?php
    echo "The value of a is $a."
?>

<!-- @end -->

</html>

We’ll use this example file in the subsequent examples. In order to display it above we used the pyg filter to apply syntax highlighting. This was specified in the dexy.yaml file as follows:

    - example.php|pyg:
        - pyg: { lexer: 'html+php' }

And included in this document like this:

{{ d["example.php|pyg"] }}

For more information, see the documentation page for dexy’s pyg filter.

Executing PHP

We can use dexy’s php filter to run this file through a php interpreter and see the result:

<html>
<!-- @section "head" -->
<head>
<title>PHP Example</title>
</head>
<!-- @end -->
<p>a (6) is bigger than b (5)</p>
<!-- @section "display-variables" -->
The value of a is 6.
<!-- @end -->

</html>

That was the contents displayed using a pre tag:

<pre>
{{ d["example.php|php"] | e }}
</pre>

We can also display the results with syntax highlighting:

<html>
<!-- @section "head" -->
<head>
<title>PHP Example</title>
</head>
<!-- @end -->
<p>a (6) is bigger than b (5)</p>
<!-- @section "display-variables" -->
The value of a is 6.
<!-- @end -->

</html>

{{ d["example.php|php|pyg"] }}

Here is how these are specified in dexy.yaml:

    - example.php|php
    - example.php|php|pyg:
        - pyg: { lexer: 'html' }

The contents of the resulting HTML file could also be displayed in HTML documentation using an iframe. This is done a lot in the Getting Started guide.

Sections of Files

To document what is going on in a file, we really need to be able to isolate sections of a file to discuss what is happening in that small section. We can do this using the idio filter in dexy, and fortunately this filter has recently been redone to support HTML-style comments as well as comments used in most programming languages, so you can mix and match these within an embedded PHP file. (You probably noticed these comments in the PHP file above.)

In the dexy.yaml file, we apply the idio filter to our php example file:

    - example.php|idio:
        - idio: { lexer: 'php', lexer-args: { startinline: True } }

Then, we can talk about just the head section in the HTML:

<head>
<title>PHP Example</title>
</head>

Or the assign-variables section:

$b = $a = 5;
$a++;

And then the section where we compare the variables:

if ($a > $b) {
  echo "<p>a ($a) is bigger than b ($b)</p>";
  $b = $a;
}

Here is the source of how these items were included in this document:

{{ d["example.php|idio"]["head"] }}
{{ d["example.php|idio"]["assign-variables"] }}
{{ d["example.php|idio"]["compare"] }}

HTML-style comments will be preserved as your php passes through the php filter (just be careful to leave a blank line after each closing ?>), so that you can also apply the idio filter to the output from the php filter:

    - example.php|php|idio:
        - idio: { lexer: 'html' }

In this way we can show the php:

<?php
    echo "The value of a is $a."
?>

And the resulting HTML:

The value of a is 6.

Here’s how we included each of these in this document:

{{ d["example.php|idio"]["display-variables"] }}
{{ d["example.php|php|idio"]["display-variables"] }}

Syntax Highlighting Sections

You might have noticed that the syntax highlighting wasn’t applied to the HTML content in the previous section, and we had to pass some custom arguments to the lexer to make things work for the PHP content. The PHP syntax highlighter in pygments is stateful and keeps track of whether it is in a HTML or PHP region of the source code file. However, because we pass our source code in in sections, the lexer isn’t able to keep track of the state.

This should be a solvable problem and you can track progress on it here, but for now you’ll have to tweak the settings if you want syntax highlighting, and please feel free to get in touch if you need help getting the output you want.

Deployment, Screenshots and Integration Testing

An additional approach which you can take to documenting PHP projects is to start a server locally (or on a virtual machine either locally or in the cloud) and run a headless web browser against that server to take screenshots and make assertions about the displayed content.

This approach is applicable to any web application, regardless of the underlying technology. It also allows you to document JavaScript components of your application. (You can also use the same pyg and idio filters to document JavaScript source files.)

The quickstart section of the Dexy Guide contains an example of bash scripts which start a local server, casper.js scripts which interact with the application running on that server, and then take screenshots and make assertions about the state of the application, as well as documentation which incorporates all these elements.

For example, here is a fully automated full-page screenshot of the polls app from the Django tutorial:

automated screenshot from Django tutorial polls app

Submit a Comment