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:
And included in this document like this:
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:
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>
Here is how these are specified in dexy.yaml
:
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:
Then, we can talk about just the head
section in the HTML:
Or the assign-variables
section:
And then the section where we compare the variables:
Here is the source of how these items were included in this document:
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:
In this way we can show the php:
And the resulting HTML:
Here’s how we included each of these in this document:
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:
Image may be NSFW.
Clik here to view.