src/HTML5/InstructionProcessor.php


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

<?php
/**
 * A handler for processor instructions.
 */
namespace Masterminds\HTML5;

/**
 * Provide an processor to handle embedded instructions.
 *
 * XML defines a mechanism for inserting instructions (like PHP) into a
 * document. These are called "Processor Instructions." The HTML5 parser
 * provides an opportunity to handle these processor instructions during
 * the tree-building phase (before the DOM is constructed), which makes
 * it possible to alter the document as it is being created.
 *
 * One could, for example, use this mechanism to execute well-formed PHP
 * code embedded inside of an HTML5 document.
 */
interface InstructionProcessor
{

    /**
     * Process an individual processing instruction.
     *
     * The process() function is responsible for doing the following:
     * - Determining whether $name is an instruction type it can handle.
     * - Determining what to do with the data passed in.
     * - Making any subsequent modifications to the DOM by modifying the
     * DOMElement or its attached DOM tree.
     *
     * @param DOMElement $element
     *            The parent element for the current processing instruction.
     * @param string $name
     *            The instruction's name. E.g. `&lt;?php` has the name `php`.
     * @param string $data
     *            All of the data between the opening and closing PI marks.
     * @return DOMElement The element that should be considered "Current". This may just be
     *         the element passed in, but if the processor added more elements,
     *         it may choose to reset the current element to one of the elements
     *         it created. (When in doubt, return the element passed in.)
     */
    public function process(\DOMElement $element, $name, $data);
}