3 * A handler for processor instructions.
5 namespace Masterminds\HTML5;
8 * Provide an processor to handle embedded instructions.
10 * XML defines a mechanism for inserting instructions (like PHP) into a
11 * document. These are called "Processor Instructions." The HTML5 parser
12 * provides an opportunity to handle these processor instructions during
13 * the tree-building phase (before the DOM is constructed), which makes
14 * it possible to alter the document as it is being created.
16 * One could, for example, use this mechanism to execute well-formed PHP
17 * code embedded inside of an HTML5 document.
19 interface InstructionProcessor
23 * Process an individual processing instruction.
25 * The process() function is responsible for doing the following:
26 * - Determining whether $name is an instruction type it can handle.
27 * - Determining what to do with the data passed in.
28 * - Making any subsequent modifications to the DOM by modifying the
29 * DOMElement or its attached DOM tree.
31 * @param DOMElement $element
32 * The parent element for the current processing instruction.
34 * The instruction's name. E.g. `<?php` has the name `php`.
36 * All of the data between the opening and closing PI marks.
37 * @return DOMElement The element that should be considered "Current". This may just be
38 * the element passed in, but if the processor added more elements,
39 * it may choose to reset the current element to one of the elements
40 * it created. (When in doubt, return the element passed in.)
42 public function process(\DOMElement $element, $name, $data);