[FEATURE] Add support for PSR/Log

- Add PSR/Log as dependency
- Add a new SimpleLogger
- Use the NullLogger per default

Helps with #461

Signed-off-by: Daniel Ziegenberg <[email protected]>

Author: ziegenberg

Diff for: CHANGELOG.md

@@ -6,6 +6,8 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 ## x.y.z
 
 ### Added
+
+- Add support for PSR/Log with a new `SimpleLogger` and use `NullLogger` per default (#596)
 - Support arithmetic operators in CSS function arguments (#607)
 - Add support for inserting an item in a CSS list (#545)
 - Add a class diagram to the README (#482)

Diff for: composer.json

@@ -24,7 +24,8 @@
     ],
     "require": {
         "php": ">=7.2.0",
-        "ext-iconv": "*"
+        "ext-iconv": "*",
+        "psr/log": "*"
     },
     "require-dev": {
         "codacy/coverage": "^1.4.3",

Diff for: src/CSSList/CSSList.php

@@ -23,14 +23,21 @@
 use Sabberworm\CSS\Value\URL;
 use Sabberworm\CSS\Value\Value;
 
+use Psr\Log\LoggerInterface;
+use Psr\Log\LoggerAwareInterface;
+use Psr\Log\LoggerAwareTrait;
+use Psr\Log\NullLogger;
+
 /**
  * This is the most generic container available. It can contain `DeclarationBlock`s (rule sets with a selector),
  * `RuleSet`s as well as other `CSSList` objects.
  *
  * It can also contain `Import` and `Charset` objects stemming from at-rules.
  */
-abstract class CSSList implements Renderable, Commentable
+abstract class CSSList implements Renderable, Commentable, LoggerAwareInterface
 {
+    use LoggerAwareTrait;
+
     /**
      * @var array<array-key, Comment>
      */
@@ -51,6 +58,8 @@ abstract class CSSList implements Renderable, Commentable
      */
     public function __construct($iLineNo = 0)
     {
+        $this->logger = new NullLogger();
+
         $this->aComments = [];
         $this->aContents = [];
         $this->iLineNo = $iLineNo;
@@ -60,7 +69,7 @@ public function __construct($iLineNo = 0)
      * @throws UnexpectedTokenException
      * @throws SourceException
      */
-    public static function parseList(ParserState $oParserState, CSSList $oList): void
+    public static function parseList(ParserState $oParserState, CSSList $oList, ?LoggerInterface $logger = null): void
     {
         $bIsRoot = $oList instanceof Document;
         if (is_string($oParserState)) {
@@ -372,6 +381,10 @@ public function removeDeclarationBlockBySelector($mSelector, $bRemoveAll = false
         foreach ($mSelector as $iKey => &$mSel) {
             if (!($mSel instanceof Selector)) {
                 if (!Selector::isValid($mSel)) {
+                    $this->logger->error(
+                        'Selector did not match {rx}.',
+                        ['rx' => Selector::SELECTOR_VALIDATION_RX]
+                    );
                     throw new UnexpectedTokenException(
                         "Selector did not match '" . Selector::SELECTOR_VALIDATION_RX . "'.",
                         $mSel,

Diff for: src/CSSList/Document.php

@@ -10,6 +10,9 @@
 use Sabberworm\CSS\RuleSet\RuleSet;
 use Sabberworm\CSS\Value\Value;
 
+use Psr\Log\LoggerInterface;
+use Psr\Log\NullLogger;
+
 /**
  * This class represents the root of a parsed CSS file. It contains all top-level CSS contents: mostly declaration
  * blocks, but also any at-rules encountered (`Import` and `Charset`).
@@ -27,10 +30,10 @@ public function __construct($iLineNo = 0)
     /**
      * @throws SourceException
      */
-    public static function parse(ParserState $oParserState): Document
+    public static function parse(ParserState $oParserState, ?LoggerInterface $logger = null): Document
     {
         $oDocument = new Document($oParserState->currentLine());
-        CSSList::parseList($oParserState, $oDocument);
+        CSSList::parseList($oParserState, $oDocument, $logger ?? new NullLogger());
         return $oDocument;
     }
 

Diff for: src/OutputFormat.php

@@ -2,14 +2,20 @@
 
 namespace Sabberworm\CSS;
 
+use Psr\Log\LoggerAwareInterface;
+use Psr\Log\LoggerAwareTrait;
+use Psr\Log\NullLogger;
+
 /**
  * Class OutputFormat
  *
  * @method OutputFormat setSemicolonAfterLastRule(bool $bSemicolonAfterLastRule) Set whether semicolons are added after
  *     last rule.
  */
-class OutputFormat
+class OutputFormat implements LoggerAwareInterface
 {
+    use LoggerAwareTrait;
+
     /**
      * Value format: `"` means double-quote, `'` means single-quote
      *
@@ -165,7 +171,10 @@ class OutputFormat
      */
     private $iIndentationLevel = 0;
 
-    public function __construct() {}
+    public function __construct()
+    {
+        $this->logger = new NullLogger();
+    }
 
     /**
      * @param string $sName
@@ -237,6 +246,7 @@ public function __call($sMethodName, array $aArguments)
         } elseif (method_exists(OutputFormatter::class, $sMethodName)) {
             return call_user_func_array([$this->getFormatter(), $sMethodName], $aArguments);
         } else {
+            $this->logger->error('Unknown OutputFormat method called: {method}', ['method' => $sMethodName]);
             throw new \Exception('Unknown OutputFormat method called: ' . $sMethodName);
         }
     }

Diff for: src/Parser.php

@@ -6,11 +6,17 @@
 use Sabberworm\CSS\Parsing\ParserState;
 use Sabberworm\CSS\Parsing\SourceException;
 
+use Psr\Log\LoggerAwareInterface;
+use Psr\Log\LoggerAwareTrait;
+use Psr\Log\NullLogger;
+
 /**
  * This class parses CSS from text into a data structure.
  */
-class Parser
+class Parser implements LoggerAwareInterface
 {
+    use LoggerAwareTrait;
+
     /**
      * @var ParserState
      */
@@ -23,6 +29,8 @@ class Parser
      */
     public function __construct($sText, Settings $oParserSettings = null, $iLineNo = 1)
     {
+        $this->logger = new NullLogger();
+
         if ($oParserSettings === null) {
             $oParserSettings = Settings::create();
         }
@@ -55,6 +63,6 @@ public function getCharset(): void
      */
     public function parse(): Document
     {
-        return Document::parse($this->oParserState);
+        return Document::parse($this->oParserState, $this->logger);
     }
 }

Diff for: src/Parsing/ParserState.php

@@ -6,8 +6,14 @@
 use Sabberworm\CSS\Parsing\Anchor;
 use Sabberworm\CSS\Settings;
 
-class ParserState
+use Psr\Log\LoggerAwareInterface;
+use Psr\Log\LoggerAwareTrait;
+use Psr\Log\NullLogger;
+
+class ParserState implements LoggerAwareInterface
 {
+    use LoggerAwareTrait;
+
     /**
      * @var null
      *
@@ -58,6 +64,8 @@ class ParserState
      */
     public function __construct($sText, Settings $oParserSettings, $iLineNo = 1)
     {
+        $this->logger = new NullLogger();
+
         $this->oParserSettings = $oParserSettings;
         $this->sText = $sText;
         $this->iCurrentPosition = 0;
@@ -137,10 +145,12 @@ public function setPosition($iPosition): void
     public function parseIdentifier($bIgnoreCase = true)
     {
         if ($this->isEnd()) {
+            $this->logger->error('Unexpected end of file while parsing identifier at line {line}', ['line' => $this->iLineNo]);
             throw new UnexpectedEOFException('', '', 'identifier', $this->iLineNo);
         }
         $sResult = $this->parseCharacter(true);
         if ($sResult === null) {
+            $this->logger->error('Unexpected token while parsing identifier at line {line}', ['line' => $this->iLineNo]);
             throw new UnexpectedTokenException($sResult, $this->peek(5), 'identifier', $this->iLineNo);
         }
         $sCharacter = null;
@@ -287,13 +297,15 @@ public function consume($mValue = 1): string
             $iLineCount = substr_count($mValue, "\n");
             $iLength = $this->strlen($mValue);
             if (!$this->streql($this->substr($this->iCurrentPosition, $iLength), $mValue)) {
+                $this->logger->error('Unexpected token "{token}" at line {line}', ['token' => $mValue, 'line' => $this->iLineNo]);
                 throw new UnexpectedTokenException($mValue, $this->peek(max($iLength, 5)), $this->iLineNo);
             }
             $this->iLineNo += $iLineCount;
             $this->iCurrentPosition += $this->strlen($mValue);
             return $mValue;
         } else {
             if ($this->iCurrentPosition + $mValue > $this->iLength) {
+                $this->logger->error('Unexpected end of file while consuming {count} chars at line {line}', ['count' => $mValue, 'line' => $this->iLineNo]);
                 throw new UnexpectedEOFException($mValue, $this->peek(5), 'count', $this->iLineNo);
             }
             $sResult = $this->substr($this->iCurrentPosition, $mValue);
@@ -318,6 +330,14 @@ public function consumeExpression($mExpression, $iMaxLength = null): string
         if (preg_match($mExpression, $sInput, $aMatches, PREG_OFFSET_CAPTURE) === 1) {
             return $this->consume($aMatches[0][0]);
         }
+        $this->logger->error(
+            'Unexpected expression "{token}" instead of {expression} at line {line}',
+            [
+                'token' => $this->peek(5),
+                'expression' => $mExpression,
+                'line' => $this->iLineNo,
+                ]
+        );
         throw new UnexpectedTokenException($mExpression, $this->peek(5), 'expression', $this->iLineNo);
     }
 
@@ -391,6 +411,10 @@ public function consumeUntil($aEnd, $bIncludeEnd = false, $consumeEnd = false, a
         }
 
         $this->iCurrentPosition = $start;
+        $this->logger->error(
+            'Unexpected end of file while searching for one of "{end}" at line {line}',
+            ['end' => implode('","', $aEnd), 'line' => $this->iLineNo]
+        );
         throw new UnexpectedEOFException(
             'One of ("' . implode('","', $aEnd) . '")',
             $this->peek(5),

Diff for: src/RuleSet/DeclarationBlock.php

@@ -104,6 +104,10 @@ public function setSelectors($mSelector, $oList = null): void
             if (!($mSelector instanceof Selector)) {
                 if ($oList === null || !($oList instanceof KeyFrame)) {
                     if (!Selector::isValid($mSelector)) {
+                        $this->logger->error(
+                            "Selector did not match '{regexp}'. Found: '{selector}'",
+                            ['regexp' => Selector::SELECTOR_VALIDATION_RX, 'selector' => $mSelector]
+                        );
                         throw new UnexpectedTokenException(
                             "Selector did not match '" . Selector::SELECTOR_VALIDATION_RX . "'.",
                             $mSelector,
@@ -113,6 +117,10 @@ public function setSelectors($mSelector, $oList = null): void
                     $this->aSelectors[$iKey] = new Selector($mSelector);
                 } else {
                     if (!KeyframeSelector::isValid($mSelector)) {
+                        $this->logger->error(
+                            "Selector did not match '{regexp}'. Found: '{selector}'",
+                            ['regexp' => KeyframeSelector::SELECTOR_VALIDATION_RX, 'selector' => $mSelector]
+                        );
                         throw new UnexpectedTokenException(
                             "Selector did not match '" . KeyframeSelector::SELECTOR_VALIDATION_RX . "'.",
                             $mSelector,
@@ -790,6 +798,7 @@ public function render(OutputFormat $oOutputFormat): string
         $sResult = $oOutputFormat->comments($this);
         if (count($this->aSelectors) === 0) {
             // If all the selectors have been removed, this declaration block becomes invalid
+            $this->logger->error("Attempt to print declaration block with missing selector at line {line}", ["line" => $this->iLineNo]);
             throw new OutputException("Attempt to print declaration block with missing selector", $this->iLineNo);
         }
         $sResult .= $oOutputFormat->sBeforeDeclarationBlock;

Diff for: src/RuleSet/RuleSet.php

@@ -11,6 +11,10 @@
 use Sabberworm\CSS\Renderable;
 use Sabberworm\CSS\Rule\Rule;
 
+use Psr\Log\LoggerAwareInterface;
+use Psr\Log\LoggerAwareTrait;
+use Psr\Log\NullLogger;
+
 /**
  * This class is a container for individual 'Rule's.
  *
@@ -20,8 +24,10 @@
  * If you want to manipulate a `RuleSet`, use the methods `addRule(Rule $rule)`, `getRules()` and `removeRule($rule)`
  * (which accepts either a `Rule` or a rule name; optionally suffixed by a dash to remove all related rules).
  */
-abstract class RuleSet implements Renderable, Commentable
+abstract class RuleSet implements Renderable, Commentable, LoggerAwareInterface
 {
+    use LoggerAwareTrait;
+
     /**
      * @var array<string, Rule>
      */
@@ -42,6 +48,8 @@ abstract class RuleSet implements Renderable, Commentable
      */
     public function __construct($iLineNo = 0)
     {
+        $this->logger = new NullLogger();
+
         $this->aRules = [];
         $this->iLineNo = $iLineNo;
         $this->aComments = [];

Diff for: src/SimpleLogger.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Sabberworm\CSS;
+
+use Psr\Log\AbstractLogger;
+
+/**
+ * This class provides a simple logging facility.
+ */
+class SimpleLogger extends AbstractLogger
+{
+
+    public function log($level, $message, array $context = []): void
+    {
+        echo self::interpolate($message, $context) . PHP_EOL;
+    }
+
+    /**
+     * Interpolates context values into the message placeholders.
+     */
+    private function interpolate(string $message, array $context = []): string
+    {
+        // build a replacement array with braces around the context keys
+        $replace = [];
+        foreach ($context as $key => $val) {
+            // check that the value can be cast to string
+            if (!is_array($val) && (!is_object($val) || method_exists($val, '__toString'))) {
+                $replace['{' . $key . '}'] = $val;
+            }
+        }
+
+        // interpolate replacement values into the message and return
+        return strtr($message, $replace);
+    }
+
+}

Diff for: src/Value/Value.php

@@ -9,12 +9,18 @@
 use Sabberworm\CSS\Value\CSSFunction;
 use Sabberworm\CSS\Renderable;
 
+use Psr\Log\LoggerAwareInterface;
+use Psr\Log\LoggerAwareTrait;
+use Psr\Log\NullLogger;
+
 /**
  * Abstract base class for specific classes of CSS values: `Size`, `Color`, `CSSString` and `URL`, and another
  * abstract subclass `ValueList`.
  */
-abstract class Value implements Renderable
+abstract class Value implements Renderable, LoggerAwareInterface
 {
+    use LoggerAwareTrait;
+
     /**
      * @var int
      */
@@ -25,6 +31,7 @@ abstract class Value implements Renderable
      */
     public function __construct($iLineNo = 0)
     {
+        $this->logger = new NullLogger();
         $this->iLineNo = $iLineNo;
     }