annotate vendor/masterminds/html5/src/HTML5/InstructionProcessor.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 129ea1e6d783
children
rev   line source
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. `&lt;?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 }