Merge pull request #39 from andreskrey/logging

Preparing for release

Author: andreskrey

CHANGELOG.md

@@ -5,6 +5,7 @@ All notable changes to this project will be documented in this file.
 
 - Added 'data-orig' as an URL source for images
 - Removed 'modal' as a negative property from classes
+- Added option to inject a logger
 - Removed all references to the `data-readability` tags that don't apply anymore to the new structure
 - Merged PR #38 (Missing DOMEntityReference)
 

README.md

@@ -84,6 +84,21 @@ Then you pass this Configuration object to Readability. The following options ar
 - **OriginalURL**: default value `http://fakehost`, original URL from the article used to fix relative URLs.
 - **SummonCthulhu**: default value `false`, remove all `<script>` nodes via regex. This is not ideal as it might break things, but might be the only solution to [libxml problems with unescaped javascript](https://github.com/andreskrey/readability.php#known-issues). If you're not parsing Javascript tutorials, it's recommended to always set this option as `true`.
 
+### Debug log
+
+Logging is optional and you will have to inject your own logger to save all the debugging messages. To do so, use a logger that implements the [PSR-3 logging interface](https://github.com/php-fig/log) and pass it to the configuration object. For example:
+
+```
+// Using monolog
+
+$log = new Logger('Readability');
+$log->pushHandler(new StreamHandler('path/to/my/log.txt'));
+
+$configuration->setLogger($log);
+```
+
+In the log you will find information about the parsed nodes, why they were removed, and why they were considered relevant to the final article.
+
 ## Limitations
 
 Of course the main limitation is PHP. Websites that load the content through lazy loading, AJAX, or any type of javascript fueled call will be ignored (actually, *not ran*) and the resulting text will be incorrect, compared to the readability.js results. All the articles you want to parse with readability.php need to be complete and all the content should be in the HTML already.  
@@ -125,7 +140,7 @@ Self closing tags like `<br />` get automatically expanded to `<br></br`. No way
 
 ## Dependencies
 
-Readability.php has no dependencies to other libraries.
+Readability.php uses the [PSR Log](https://github.com/php-fig/log) interface to define the allowed type of loggers.
 
 ## To-do
 

composer.json

@@ -21,9 +21,13 @@
         "php": ">=5.6.0",
         "ext-dom": "*",
         "ext-xml": "*",
-        "ext-mbstring": "*"
+        "ext-mbstring": "*",
+        "psr/log": "^1.0"
     },
     "require-dev": {
         "phpunit/phpunit": "^5.7"
+    },
+    "suggest": {
+        "monolog/monolog": "Allow logging debug information"
     }
 }

src/Configuration.php

@@ -2,11 +2,17 @@
 
 namespace andreskrey\Readability;
 
+use Psr\Log\LoggerAwareTrait;
+use Psr\Log\LoggerInterface;
+use Psr\Log\NullLogger;
+
 /**
  * Class Configuration.
  */
 class Configuration
 {
+    use LoggerAwareTrait;
+
     /**
      * @var int
      */
@@ -48,6 +54,19 @@ class Configuration
      */
     protected $originalURL = 'http://fakehost';
 
+    /**
+     * @return LoggerInterface
+     */
+    public function getLogger()
+    {
+        // If no logger has been set, just return a null logger
+        if ($this->logger === null) {
+            return new NullLogger();
+        } else {
+            return $this->logger;
+        }
+    }
+
     /**
      * @return int
      */