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