Mailcode\Mailcode_Parser_Safeguard

Complexity

Total Complexity

46

Size/Duplication

Total Lines	505
Duplicated Lines	0 %

Importance

Changes	12
Bugs	0	Features	1

26 Methods

Rating	Name	Duplication	Size	Complexity
A	getOriginalString()	0	3	1
A	getDelimiter()	0	3	1
A	setDelimiter()	0	14	2
A	__construct()	0	4	1
A	makeSafe()	0	5	1
A	makeSafePartial()	0	13	2
A	getFormatter()	0	3	1
A	hasPlaceholders()	0	5	1
A	isValid()	0	3	1
A	getPlaceholderByID()	0	19	3
A	getCollection()	0	10	2
A	getPlaceholderByString()	0	19	3
A	requireValidCollection()	0	15	2
A	makeWholePartial()	0	6	1
A	getPlaceholders()	0	23	3
A	selectHTMLHighlightingFormatter()	0	10	2
A	getReplaces()	0	4	1
A	makeHighlightedPartial()	0	6	1
A	getPlaceholderStrings()	0	17	3
A	restore()	0	27	6
A	selectSingleLinesFormatter()	0	10	2
A	makeWhole()	0	6	1
A	makeHighlighted()	0	6	1
A	selectFormatter()	0	19	2
A	isPlaceholder()	0	5	1
A	exceptionWrongFormatter()	0	9	1

<?php
/**
 * File containing the {@see Mailcode_Parser_Safeguard} class.
 *
 * @package Mailcode
 * @subpackage Parser
 * @see Mailcode_Parser_Safeguard
 */

declare(strict_types=1);

namespace Mailcode;

/**
 * Command safeguarder: used to replace the mailcode commands
 * in a string with placeholders, to allow safe text transformation
 * and filtering operations on strings, without risking to break 
 * any of the contained commands (if any).
 * 
 * Usage:
 * 
 * <pre>
 * $safeguard = Mailcode::create()->createSafeguard($sourceString);
 * 
 * // replace all commands with placeholders
 * $workString = $safeguard->makeSafe();
 * 
 * // dome something with the work string - filtering, parsing...
 * 
 * // restore all command placeholders
 * $resultString = $safeguard->makeWhole($workString);
 * </pre>
 * 
 * Note that by default, the placeholders are delimited with
 * two underscores, e.g. <code>__PCH0001__</code>. If the text
 * transformations include replacing or modifying underscores,
 * you should use a different delimiter:
 * 
 * <pre>
 * $safeguard = Mailcode::create()->createSafeguard($sourceString);
 * 
 * // change the delimiter to %%. Can be any arbitrary string.
 * $safeguard->setDelimiter('%%');
 * </pre>
 *
 * @package Mailcode
 * @subpackage Parser
 * @author Sebastian Mordziol <s.mordziol@mistralys.eu>
 */
class Mailcode_Parser_Safeguard
{
    const ERROR_INVALID_COMMANDS = 47801;
    
    const ERROR_COMMAND_PLACEHOLDER_MISSING = 47802;
    
    const ERROR_EMPTY_DELIMITER = 47803;
    
    const ERROR_PLACEHOLDER_NOT_FOUND = 47804;
    
    const ERROR_UNKNOWN_FORMATTER = 47805;
    
    const ERROR_NOT_A_SINGLE_LINES_FORMATTER = 47806;
    
   /**
    * @var Mailcode_Parser
    */
    protected $parser;
    
   /**
    * @var Mailcode_Collection
    */
    protected $commands;
    
   /**
    * @var string
    */
    protected $originalString;
    
   /**
    * @var Mailcode_Collection
    */
    protected $collection;
    
   /**
    * Counter for the placeholders, global for all placeholders.
    * @var integer
    */
    private static $counter = 0;
    
   /**
    * @var Mailcode_Parser_Safeguard_Placeholder[]
    */
    protected $placeholders;
    
   /**
    * @var string
    */
    protected $delimiter = '__';
    
   /**
    * @var string[]|NULL
    */
    protected $placeholderStrings;
    
   /**
    * @var Mailcode_Parser_Safeguard_Formatter
    */
    protected $formatter;
    
    public function __construct(Mailcode_Parser $parser, string $subject)
    {
        $this->parser = $parser;
        $this->originalString = $subject;
    }
    
   /**
    * Retrieves the string the safeguard was created for.
    * 
    * @return string
    */
    public function getOriginalString() : string
    {
        return $this->originalString;
    }
    
   /**
    * Sets the delimiter character sequence used to prepend
    * and append to the placeholders.
    * 
    * The delimiter's default is "__" (two underscores).
    * 
    * @param string $delimiter
    * @return Mailcode_Parser_Safeguard
    */
    public function setDelimiter(string $delimiter) : Mailcode_Parser_Safeguard
    {
        if(empty($delimiter))
        {
            throw new Mailcode_Exception(
                'Empty delimiter',
                'Delimiters may not be empty.',
                self::ERROR_EMPTY_DELIMITER
            );
        }
        
        $this->delimiter = $delimiter;
        
        return $this;
    }
    
    public function getDelimiter() : string
    {
        return $this->delimiter;
    }
    
   /**
    * Retrieves the safe string in which all commands have been replaced
    * by placeholder strings.
    *
    * @return string
    * @throws Mailcode_Exception 
    *
    * @see Mailcode_Parser_Safeguard::ERROR_INVALID_COMMANDS
    */
    public function makeSafe() : string
    {
        $this->requireValidCollection();
        
        return $this->makeSafePartial();
    }
    
   /**
    * Like makeSafe(), but allows partial (invalid) commands: use this
    * if the subject string may contain only part of the whole set of
    * commands. 
    * 
    * Example: parsing a text with an opening if statement, without the 
    * matching end statement.
    * 
    * @return string
    */
    public function makeSafePartial() : string
    {
        $replaces = $this->getReplaces();
        
        $safe = str_replace(array_values($replaces), array_keys($replaces), $this->originalString);

        // If a formatter has been selected, let it modify the string.
        if(isset($this->formatter))
        {
            $safe = $this->formatter->format($safe);
        }
        
        return $safe;
    }
    
    public function getFormatter() : ?Mailcode_Parser_Safeguard_Formatter
    {
        return $this->formatter;
    }
    
    public function selectFormatter(string $formatterID) : Mailcode_Parser_Safeguard_Formatter
    {
        $class = 'Mailcode\Mailcode_Parser_Safeguard_Formatter_'.$formatterID;
        
        if(class_exists($class))
        {
            $this->formatter = new $class($this);
            
            return $this->formatter;
        }
        
        throw new Mailcode_Exception(
            'Unknown safeguard formatter.',
            sprintf(
                'The formatter [%s] does not exist, could not find class [%s].',
                $formatterID,
                $class
            ),
            self::ERROR_UNKNOWN_FORMATTER
        );
    }
    
    public function selectHTMLHighlightingFormatter() : Mailcode_Parser_Safeguard_Formatter_HTMLHighlighting
    {
        $formatter = $this->selectFormatter('HTMLHighlighting');
        
        if($formatter instanceof Mailcode_Parser_Safeguard_Formatter_HTMLHighlighting)

$formatter is always a sub-type of Mailcode\Mailcode_Parser_Safeguard_Formatter_HTMLHighlighting.

        {
            return $formatter;
        }
        
        throw $this->exceptionWrongFormatter(Mailcode_Parser_Safeguard_Formatter_HTMLHighlighting::class);
    }
    
   /**
    * Enables the formatter that ensures that all commands that
    * @return Mailcode_Parser_Safeguard_Formatter_SingleLines
    */
    public function selectSingleLinesFormatter() : Mailcode_Parser_Safeguard_Formatter_SingleLines
    {
        $formatter = $this->selectFormatter('SingleLines');
        
        if($formatter instanceof Mailcode_Parser_Safeguard_Formatter_SingleLines)

$formatter is always a sub-type of Mailcode\Mailcode_Parser_Safeguard_Formatter_SingleLines.

        {
            return $formatter;
        }
        
        throw $this->exceptionWrongFormatter(Mailcode_Parser_Safeguard_Formatter_SingleLines::class);
    }
    
    private function exceptionWrongFormatter(string $expectedClass) : Mailcode_Exception
    {
        return new Mailcode_Exception(
            'Not the expected formatter',
            sprintf(
                'The formatter is not an instance of [%s].',
                $expectedClass
            ),
            self::ERROR_NOT_A_SINGLE_LINES_FORMATTER
        );
    }
    
   /**
    * Retrieves an associative array with pairs of
    * [placeholder string => replacement text]. 
    * 
    * @param bool $highlighted
    * @return string[]string
    */
    protected function getReplaces(bool $highlighted=false, bool $normalize=false) : array
    {
        $restorer = new Mailcode_Parser_Safeguard_Restorer($this, $highlighted, $normalize);
        return $restorer->getReplaces();
    }
    
   /**
    * Retrieves all placeholders that have to be added to
    * the subject text.
    * 
    * @return \Mailcode\Mailcode_Parser_Safeguard_Placeholder[]
    */
    public function getPlaceholders()
    {
        if(isset($this->placeholders))
        {
            return $this->placeholders;
        }
        
        $this->placeholders = array();
        
        $cmds = $this->getCollection()->getGroupedByHash();
        
        foreach($cmds as $command)
        {
            self::$counter++;
            
            $this->placeholders[] = new Mailcode_Parser_Safeguard_Placeholder(
                self::$counter,
                $command,
                $this
            );
        }

        return $this->placeholders;
    }
    
    protected function restore(string $string, bool $partial=false, bool $highlighted=false) : string
    {
        if(!$partial)
        {
            $this->requireValidCollection();
        }
        
        $replaces = $this->getReplaces($highlighted, true);
        
        $placeholderStrings = array_keys($replaces);
        
        foreach($placeholderStrings as $search)
        {
            if(!$partial && !$highlighted && !strstr($string, $search))
            {
                throw new Mailcode_Exception(
                    'Command placeholder not found',
                    sprintf(
                        'A placeholder for a command could not be found in the string to restore: [%s].',
                        $search
                    ),
                    self::ERROR_COMMAND_PLACEHOLDER_MISSING
                );
            }
        }
        
        return str_replace($placeholderStrings, array_values($replaces), $string);
    }
    
   /**
    * Makes the string whole again after transforming or filtering it,
    * by replacing the command placeholders with the original commands.
    *
    * @param string $string
    * @return string
    * @throws Mailcode_Exception
    *
    * @see Mailcode_Parser_Safeguard::ERROR_INVALID_COMMANDS
    * @see Mailcode_Parser_Safeguard::ERROR_COMMAND_PLACEHOLDER_MISSING
    */
    public function makeWhole(string $string) : string
    {
        return $this->restore(
            $string, 
            false, // partial? 
            false // highlight?
        );
    }
    
   /**
    * Like `makeWhole()`, but ignores missing command placeholders.
    *
    * @param string $string
    * @return string
    * @throws Mailcode_Exception
    *
    * @see Mailcode_Parser_Safeguard::ERROR_INVALID_COMMANDS
    */
    public function makeWholePartial(string $string) : string
    {
        return $this->restore(
            $string,
            true, // partial?
            false // highlight?
        );
    }

   /**
    * Like `makeWhole()`, but replaces the commands with a syntax
    * highlighted version, meant for human readable texts only.
    * 
    * Note: the commands lose their functionality (They cannot be 
    * parsed from that string again).
    *
    * @param string $string
    * @return string
    * @throws Mailcode_Exception
    *
    * @see Mailcode_Parser_Safeguard::ERROR_INVALID_COMMANDS
    * @see Mailcode_Parser_Safeguard::ERROR_COMMAND_PLACEHOLDER_MISSING
    */
    public function makeHighlighted(string $string) : string
    {
        return $this->restore(
            $string, 
            false, // partial? 
            true // highlighted?
        );
    }
    
   /**
    * Like `makeHighlighted()`, but ignores missing command placeholders.
    * 
    * @param string $string
    * @return string
    * @throws Mailcode_Exception
    *
    * @see Mailcode_Parser_Safeguard::ERROR_INVALID_COMMANDS
    */
    public function makeHighlightedPartial(string $string) : string
    {
        return $this->restore(
            $string, 
            true, // partial? 
            true // highlight?
        );
    }
    
   /**
    * Retrieves the commands collection contained in the string.
    * 
    * @return Mailcode_Collection
    */
    public function getCollection() : Mailcode_Collection
    {
        if(isset($this->collection))
        {
            return $this->collection;
        }
        
        $this->collection = $this->parser->parseString($this->originalString);
        
        return $this->collection;
    }
    
    public function isValid() : bool
    {
        return $this->getCollection()->isValid();
    }
    
   /**
    * @throws Mailcode_Exception
    * 
    * @see Mailcode_Parser_Safeguard::ERROR_INVALID_COMMANDS
    */
    protected function requireValidCollection() : void
    {
        if($this->getCollection()->isValid())
        {
            return;
        }
        
        throw new Mailcode_Exception(
            'Cannot safeguard invalid commands',
            sprintf(
                'The collection contains invalid commands. Safeguarding is only allowed with valid commands.'.
                'Source string: [%s]',
                $this->originalString
            ),
            self::ERROR_INVALID_COMMANDS
        );
    }
    
   /**
    * Retrieves a list of all placeholder IDs used in the text.
    * 
    * @return string[]
    */
    public function getPlaceholderStrings() : array
    {
        if(is_array($this->placeholderStrings))
        {
            return $this->placeholderStrings;
        }
        
        $placeholders = $this->getPlaceholders();
        
        $this->placeholderStrings = array();
        
        foreach($placeholders as $placeholder)
        {
            $this->placeholderStrings[] = $placeholder->getReplacementText();
        }
        
        return $this->placeholderStrings;
    }
    
    public function isPlaceholder(string $subject) : bool
    {
        $ids = $this->getPlaceholderStrings();
        
        return in_array($subject, $ids);
    }
    
   /**
    * Retrieves a placeholder instance by its ID.
    * 
    * @param int $id
    * @throws Mailcode_Exception If the placeholder was not found.
    * @return Mailcode_Parser_Safeguard_Placeholder
    */
    public function getPlaceholderByID(int $id) : Mailcode_Parser_Safeguard_Placeholder
    {
        $placeholders = $this->getPlaceholders();
        
        foreach($placeholders as $placeholder)
        {
            if($placeholder->getID() === $id)
            {
                return $placeholder;
            }
        }
        
        throw new Mailcode_Exception(
            'No such safeguard placeholder.',
            sprintf(
                'The placeholder ID [%s] is not present in the safeguard instance.',
                $id
            ),
            self::ERROR_PLACEHOLDER_NOT_FOUND
        );
    }
    
   /**
    * Retrieves a placeholder instance by its replacement text.
    * 
    * @param string $string
    * @throws Mailcode_Exception
    * @return Mailcode_Parser_Safeguard_Placeholder
    */
    public function getPlaceholderByString(string $string) : Mailcode_Parser_Safeguard_Placeholder
    {
        $placeholders = $this->getPlaceholders();
        
        foreach($placeholders as $placeholder)
        {
            if($placeholder->getReplacementText() === $string)
            {
                return $placeholder;
            }
        }
        
        throw new Mailcode_Exception(
            'No such safeguard placeholder.',
            sprintf(
                'The placeholder replacement string [%s] is not present in the safeguard instance.',
                $string
            ),
            self::ERROR_PLACEHOLDER_NOT_FOUND
        );
    }
    
    public function hasPlaceholders() : bool
    {
        $placeholders = $this->getPlaceholders();
        
        return !empty($placeholders);
    }
}