[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4  * @package   s9e\TextFormatter
   5  * @copyright Copyright (c) 2010-2022 The s9e authors
   6  * @license   http://www.opensource.org/licenses/mit-license.php The MIT License
   7  */
   8  namespace s9e\TextFormatter\Plugins;
   9  
  10  use InvalidArgumentException;
  11  use RuntimeException;
  12  use s9e\TextFormatter\Configurator;
  13  use s9e\TextFormatter\Configurator\ConfigProvider;
  14  use s9e\TextFormatter\Configurator\Helpers\ConfigHelper;
  15  use s9e\TextFormatter\Configurator\JavaScript\Code;
  16  use s9e\TextFormatter\Configurator\Validators\AttributeName;
  17  use s9e\TextFormatter\Configurator\Validators\TagName;
  18  
  19  abstract class ConfiguratorBase implements ConfigProvider
  20  {
  21      /**
  22      * @var Configurator
  23      */
  24      protected $configurator;
  25  
  26      /**
  27      * @var mixed Ignored if FALSE. Otherwise, this plugin's parser will only be executed if this
  28      *            string is present in the original text
  29      */
  30      protected $quickMatch = false;
  31  
  32      /**
  33      * @var integer Maximum amount of matches to process - used by the parser when running the global
  34      *              regexp
  35      */
  36      protected $regexpLimit = 50000;
  37  
  38      /**
  39      * @param Configurator $configurator
  40      * @param array        $overrideProps Properties of the plugin will be overwritten with those
  41      */
  42  	final public function __construct(Configurator $configurator, array $overrideProps = [])
  43      {
  44          $this->configurator = $configurator;
  45  
  46          foreach ($overrideProps as $k => $v)
  47          {
  48              $methodName = 'set' . ucfirst($k);
  49  
  50              if (method_exists($this, $methodName))
  51              {
  52                  $this->$methodName($v);
  53              }
  54              elseif (property_exists($this, $k))
  55              {
  56                  $this->$k = $v;
  57              }
  58              else
  59              {
  60                  throw new RuntimeException("Unknown property '" . $k . "'");
  61              }
  62          }
  63  
  64          $this->setUp();
  65      }
  66  
  67      /**
  68      * Executed by this plugin's constructor
  69      */
  70  	protected function setUp()
  71      {
  72      }
  73  
  74      /**
  75      * Finalize this plugin's configuration
  76      *
  77      * Executed by the configurator whenever the tags' config must be in a usable state:
  78      *  - before the parser's config is generated
  79      *  - before the renderer's stylesheet is generated
  80      *  - before HTML5 rules are generated
  81      *
  82      * As such, this method may be called multiple times during configuration
  83      */
  84  	public function finalize()
  85      {
  86      }
  87  
  88      /**
  89      * @return array|null This plugin's config, or NULL to disable this plugin
  90      */
  91  	public function asConfig()
  92      {
  93          $properties = get_object_vars($this);
  94          unset($properties['configurator']);
  95  
  96          return ConfigHelper::toArray($properties);
  97      }
  98  
  99      /**
 100      * Return a list of base properties meant to be added to asConfig()'s return
 101      *
 102      * NOTE: this final method exists so that the plugin's configuration can always specify those
 103      *       base properties, even if they're omitted from asConfig(). Going forward, this ensure
 104      *       that new base properties added to ConfiguratorBase appear in the plugin's config without
 105      *       having to update every plugin
 106      *
 107      * @return array
 108      */
 109  	final public function getBaseProperties()
 110      {
 111          $config = [
 112              'className'   => preg_replace('/Configurator$/', 'Parser', get_class($this)),
 113              'quickMatch'  => $this->quickMatch,
 114              'regexpLimit' => $this->regexpLimit
 115          ];
 116  
 117          $js = $this->getJSParser();
 118          if (isset($js))
 119          {
 120              $config['js'] = new Code($js);
 121          }
 122  
 123          return $config;
 124      }
 125  
 126      /**
 127      * Return additional hints used in the JavaScript parser
 128      *
 129      * @return array Hint names and values
 130      */
 131  	public function getJSHints()
 132      {
 133          return [];
 134      }
 135  
 136      /**
 137      * Return this plugin's JavaScript parser
 138      *
 139      * This is the base implementation, meant to be overridden by custom plugins. By default it
 140      * returns the Parser.js file from stock plugins' directory, if available
 141      *
 142      * @return string|null JavaScript source, or NULL if no JS parser is available
 143      */
 144  	public function getJSParser()
 145      {
 146          $className = get_class($this);
 147          if (strpos($className, 's9e\\TextFormatter\\Plugins\\') === 0)
 148          {
 149              $p = explode('\\', $className);
 150              $pluginName = $p[3];
 151  
 152              $filepath = __DIR__ . '/' . $pluginName . '/Parser.js';
 153              if (file_exists($filepath))
 154              {
 155                  return file_get_contents($filepath);
 156              }
 157          }
 158  
 159          return null;
 160      }
 161  
 162      /**
 163      * Return the tag associated with this plugin, if applicable
 164      *
 165      * @return \s9e\TextFormatter\Configurator\Items\Tag
 166      */
 167  	public function getTag()
 168      {
 169          if (!isset($this->tagName))
 170          {
 171              throw new RuntimeException('No tag associated with this plugin');
 172          }
 173  
 174          return $this->configurator->tags[$this->tagName];
 175      }
 176  
 177      //==========================================================================
 178      // Setters
 179      //==========================================================================
 180  
 181      /**
 182      * Disable quickMatch
 183      *
 184      * @return void
 185      */
 186  	public function disableQuickMatch()
 187      {
 188          $this->quickMatch = false;
 189      }
 190  
 191      /**
 192      * Set $this->attrName with given attribute name, normalized
 193      *
 194      * @param  string $attrName New attribute name
 195      * @return void
 196      */
 197  	protected function setAttrName($attrName)
 198      {
 199          if (!property_exists($this, 'attrName'))
 200          {
 201              throw new RuntimeException("Unknown property 'attrName'");
 202          }
 203  
 204          $this->attrName = AttributeName::normalize($attrName);
 205      }
 206  
 207      /**
 208      * Set the quickMatch string
 209      *
 210      * @param  string $quickMatch
 211      * @return void
 212      */
 213  	public function setQuickMatch($quickMatch)
 214      {
 215          if (!is_string($quickMatch))
 216          {
 217              throw new InvalidArgumentException('quickMatch must be a string');
 218          }
 219  
 220          $this->quickMatch = $quickMatch;
 221      }
 222  
 223      /**
 224      * Set the maximum number of regexp matches
 225      *
 226      * @param  integer $limit
 227      * @return void
 228      */
 229  	public function setRegexpLimit($limit)
 230      {
 231          $limit = (int) $limit;
 232  
 233          if ($limit < 1)
 234          {
 235              throw new InvalidArgumentException('regexpLimit must be a number greater than 0');
 236          }
 237  
 238          $this->regexpLimit = $limit;
 239      }
 240  
 241      /**
 242      * Set $this->tagName with given tag name, normalized
 243      *
 244      * @param  string $tagName New tag name
 245      * @return void
 246      */
 247  	protected function setTagName($tagName)
 248      {
 249          if (!property_exists($this, 'tagName'))
 250          {
 251              throw new RuntimeException("Unknown property 'tagName'");
 252          }
 253  
 254          $this->tagName = TagName::normalize($tagName);
 255      }
 256  }