Start Simple

Include a code block in rst by adding something like this:


.. code-block:: php


Your code must then be indented, and the style persists until you “undent” again. There is pretty extensive language/syntax support since it is built on pygments, so you can use most language names instead of the php there.

Line Numbers and PHP Tags

In order to make the PHP syntax highlight work, your code must include a <?php tag. But this is very bad news if you only have 13 lines total to fit your example in! I usually start with something like this:


.. code-block:: php
:startinline: true
:linenos: true


This removes the need for the opening tag, and also adds line numbers to the code sample. This is especially helpful for presentations where the screen may be too far away for you to point at!

Including External Files

For some things, it’s neater to keep the code samples in separate files – I also like this approach since it keeps the code separate and I can run it and edit it, then just include it in my presentation.


.. code-block:: php
:linenos: true
:include: code/api/public/index.php


This brings in the named file, and also enables line numbers.

Including Sections From External Files

Currently I’m working on a presentation that pulls in smaller sections from an actual working codebase rather than having its own examples. rst can handle starting and stopping at specific points in the file.

The rst document looks like this:


.. code-block:: php
:startinline: true
:linenos: true
:linenos_offset: true
:include: code/api/public/index.php
:start-after: // start events list
:end-before: // end events list

Meanwhile, the PHP itself looks more like this:

<?php

// start setup
require "../vendor/autoload.php";
spl_autoload_register(function($classname) {
    include __DIR__ . "/../lib/" . $classname . ".php";
});

$app = new \Slim\Slim();

$container = new \Pimple\Container();
$container&#91;'db'&#93; = function ($c) {
    return new PDO("mysql:host=localhost;dbname=joindin", "joindin", "joindin");
};
$app->config('container', $container);
// end setup

// start view setup
$app->view(new View());
$app->response->headers->set("Content-Type", "application/json");
// end view setup

// start events list
$app->get('/events', function () use ($app) {
    $db = $app->config('container')['db'];
    $data = array();

    $model = new EventModel($db);
    $data['events'] = $model->getSomeEvents();

    $app->render("foo.php", array("mydata" => $data));
});
// end events list

...

With the comments in the code, I can use them as the start/stop mechanisms for my talks – very useful indeed!