Rewire TextUI to be a PSR logger, makes generally avaliable

donatj · May 12, 2024 · f877e4b · f877e4b
1 parent d6497dc
commit f877e4b
Show file tree

Hide file tree

Showing 10 changed files with 95 additions and 64 deletions.
diff --git a/DOCS.md b/DOCS.md
@@ -672,10 +672,6 @@ function output(int $depth) : string
 
 ---
 
-### Method: `DocPage->setUI(\donatj\MDDoc\Runner\TextUI $ui)`
-
----
-
 ### Method: DocPage->getChildren
 
 ```php
@@ -872,12 +868,6 @@ function output(int $depth)
 
 ### Method: `ElementInterface->__construct(\donatj\MDDoc\Runner\ImmutableAttributeTree $attributeTree, string $textContent)`
 
-## Class: \donatj\MDDoc\Documentation\Interfaces\UIAwareDocumentationInterface
-
-
-
-### Method: `UIAwareDocumentationInterface->setUI(\donatj\MDDoc\Runner\TextUI $ui)`
-
 ## Class: \donatj\MDDoc\Documentation\PhpFileDocs
 
 ```php
@@ -1455,12 +1445,8 @@ Output an Error before exiting with given error code
 
 ---
 
-### Method: `TextUI->warning(string $text)`
-
----
-
 ### Method: `TextUI->println([ string $text = ''])`
 
 ---
 
-### Method: `TextUI->log(string $text [, bool $timestamp = true])`
+### Method: `TextUI->log($level, $message [, array $context = array()])`
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 [![Latest Stable Version](https://poser.pugx.org/donatj/mddoc/version)](https://packagist.org/packages/donatj/mddoc)
 [![Total Downloads](https://poser.pugx.org/donatj/mddoc/downloads)](https://packagist.org/packages/donatj/mddoc)
 [![License](https://poser.pugx.org/donatj/mddoc/license)](https://packagist.org/packages/donatj/mddoc)
-[![ci.yml](https://github.com/donatj/mddoc/actions/workflows/ci.yml/badge.svg?)](https://github.com/donatj/mddoc/actions/workflows/ci.yml)
+[![ci.yml](https://github.com/donatj/mddoc/actions/workflows/ci.yml/badge.svg)](https://github.com/donatj/mddoc/actions/workflows/ci.yml)
 
 
 A simple, directed markdown documentation generator for PHP projects.
@@ -36,6 +36,7 @@ This is done using a simple, expressive XML syntax. This includes:
 - **donatj/flags**: ^1.5
 - **donatj/mddom**: ^0.2.0
 - **phpdocumentor/reflection**: ~5.2.0
+- **psr/log**: ^1|^2|^3
 - **symfony/polyfill-php80**: ^1.28
 
 ## Examples

diff --git a/composer.json b/composer.json
@@ -10,6 +10,7 @@
 		"donatj/flags": "^1.5",
 		"donatj/mddom": "^0.2.0",
 		"phpdocumentor/reflection": "~5.2.0",
+		"psr/log": "^1|^2|^3",
 		"symfony/polyfill-php80": "^1.28"
 	},
 	"require-dev": {

diff --git a/src/Documentation/DocPage.php b/src/Documentation/DocPage.php
@@ -14,11 +14,12 @@
 use donatj\MDDoc\Exceptions\TargetNotWritableException;
 use donatj\MDDoc\Runner\TextUI;
 use donatj\MDDom\Document;
+use Psr\Log\LoggerAwareInterface;
+use Psr\Log\LoggerAwareTrait;
 
-class DocPage extends AbstractNestedDoc implements UIAwareDocumentationInterface {
+class DocPage extends AbstractNestedDoc implements LoggerAwareInterface {
 
-	/** @var \donatj\MDDoc\Runner\TextUI|null */
-	protected $ui;
+	use LoggerAwareTrait;
 
 	/**
 	 * Filename to output
@@ -57,8 +58,8 @@ public function output( int $depth ) : string {
 			throw new TargetNotWritableException("failed to write to '{$target}'");
 		}
 
-		if( $this->ui ) {
-			$this->ui->log("output '{$target}'");
+		if( $this->logger ) {
+			$this->logger->info("output '{$target}'");
 		}
 
 		return "{$pre_link_text}[{$link_text}]({$link}){$post_link_text}\n\n";
@@ -94,10 +95,6 @@ protected function init() : void {
 		$this->requireOption('target');
 	}
 
-	public function setUI( TextUI $ui ) : void {
-		$this->ui = $ui;
-	}
-
 	public static function tagName() : string {
 		return 'docpage';
 	}

diff --git a/src/Documentation/Interfaces/UIAwareDocumentationInterface.php b/src/Documentation/Interfaces/UIAwareDocumentationInterface.php
diff --git a/src/Documentation/PhpFileDocs.php b/src/Documentation/PhpFileDocs.php
@@ -18,10 +18,15 @@
 use donatj\MDDom\Paragraph;
 use donatj\MDDom\Text as MdText;
 use phpDocumentor\Reflection\DocBlock;
+use phpDocumentor\Reflection\Element;
 use phpDocumentor\Reflection\Php\Function_;
 use phpDocumentor\Reflection\Php\Method;
+use Psr\Log\LoggerAwareInterface;
+use Psr\Log\LoggerAwareTrait;
 
-class PhpFileDocs extends AbstractDocPart implements AutoloaderAware {
+class PhpFileDocs extends AbstractDocPart implements AutoloaderAware, LoggerAwareInterface {
+
+	use LoggerAwareTrait;
 
 	/**
 	 * The file to document
@@ -130,12 +135,12 @@ private function scanSourceFile( string $filename, int $depth ) {
 				$subDocument->appendChild($returnDoc);
 
 				if( $return = current($block->getTagsByName('return')) ) {
-					$returnDoc->appendChild(new Header('Returns:'));
 					if( $return instanceof DocBlock\Tags\InvalidTag ) {
-						drop($filename);
+						$this->logInvalidTag('Invalid @return tag', $func, $filename, $name, $return);
+					} else {
+						$returnDoc->appendChild(new Header('Returns:'));
+						$returnDoc->appendChild(new MdText('- ' . $this->formatType($return->getType(), 'void') . (($returnDescr = (string)$return->getDescription()) ? ' - ' . $returnDescr : '')));
 					}
-
-					$returnDoc->appendChild(new MdText('- ' . $this->formatType($return->getType(), 'void') . (($returnDescr = (string)$return->getDescription()) ? ' - ' . $returnDescr : '')));
 				}
 			}
 		}
@@ -425,15 +430,15 @@ private function scanSourceFile( string $filename, int $depth ) {
 
 					if( !$this->getOption(self::OPT_SKIP_METHOD_RETURNS, true) ) {
 						if( $return = current($firstBlock->getTagsByName('return')) ) {
-							$returnDoc = new DocumentDepth;
-							$subDocument->appendChild($returnDoc);
-
-							$returnDoc->appendChild(new Header('Returns:'));
 							if( $return instanceof DocBlock\Tags\InvalidTag ) {
-								drop($filename);
-							}
+								$this->logInvalidTag('Invalid @return tag', $class, $filename, $name, $return);
+							} else {
+								$returnDoc = new DocumentDepth;
+								$subDocument->appendChild($returnDoc);
 
-							$returnDoc->appendChild(new MdText('- ' . $this->formatType($return->getType(), 'void') . (($returnDescr = (string)$return->getDescription()) ? ' - ' . $returnDescr : '')));
+								$returnDoc->appendChild(new Header('Returns:'));
+								$returnDoc->appendChild(new MdText('- ' . $this->formatType($return->getType(), 'void') . (($returnDescr = (string)$return->getDescription()) ? ' - ' . $returnDescr : '')));
+							}
 						}
 					}
 				} else {
@@ -571,7 +576,7 @@ private function getDocStr( DocBlock $block ) : string {
 
 	private function arrayTrim( array $sv ) : array {
 		$s   = 0;
-		$svn = null;
+		$svn = [];
 		$c   = count($sv);
 		for( $i = 0; $i < $c; $i++ ) {
 			if( !empty($sv[$i]) ) {
@@ -613,4 +618,23 @@ public static function tagName() : string {
 		return 'file';
 	}
 
+	private function logInvalidTag( string $message, Element $element, string $filename, string $name, DocBlock\Tags\InvalidTag $return ) : void {
+		$ctx = [
+			'item' => $element->getFqsen(),
+			'call' => $name,
+			'file' => $filename,
+		];
+
+		$ex = $return->getException();
+		if( $ex ) {
+			$ctx['message'] = $ex->getMessage();
+		}
+
+		if( $this->logger ) {
+			$this->logger->notice($message, $ctx);
+		} else {
+			throw new \RuntimeException($message);
+		}
+	}
+
 }
diff --git a/src/Documentation/RecursiveDirectory.php b/src/Documentation/RecursiveDirectory.php
@@ -9,8 +9,12 @@
 use donatj\MDDoc\Autoloaders\Interfaces\AutoloaderInterface;
 use donatj\MDDoc\Documentation\Interfaces\AutoloaderAware;
 use donatj\MDDom\Document;
+use Psr\Log\LoggerAwareInterface;
+use Psr\Log\LoggerAwareTrait;
 
-class RecursiveDirectory extends AbstractNestedDoc implements AutoloaderAware {
+class RecursiveDirectory extends AbstractNestedDoc implements AutoloaderAware, LoggerAwareInterface {
+
+	use LoggerAwareTrait;
 
 	/**
 	 * The directory to recursively search for files to document
@@ -41,6 +45,9 @@ public function output( int $depth ) : Document {
 			$class = new PhpFileDocs(
 				$this->getAttributeTree()->withAttr([ self::OPT_NAME => (string)$file ])
 			);
+			if( $this->logger ) {
+				$class->setLogger($this->logger);
+			}
 			$this->addChildren($class);
 		}
 

diff --git a/src/ElementFactory.php b/src/ElementFactory.php
@@ -7,6 +7,7 @@
 use donatj\MDDoc\Exceptions\ConfigException;
 use donatj\MDDoc\Runner\ImmutableAttributeTree;
 use donatj\MDDoc\Runner\TextUI;
+use Psr\Log\LoggerAwareInterface;
 
 /**
  * Links XML Tags to their Given Documentation Generator
@@ -70,8 +71,8 @@ public function makeFromTag(
 
 			if( $element::tagName() === $tagName ) {
 				$element = new $element($attributeTree, $textContent);
-				if( $element instanceof UIAwareDocumentationInterface ) {
-					$element->setUI($this->ui);
+				if($element instanceof LoggerAwareInterface) {
+					$element->setLogger($this->ui);
 				}
 
 				return $element;

diff --git a/src/MDDoc.php b/src/MDDoc.php
@@ -49,10 +49,9 @@ public function __construct( array $args ) {
 
 		$currMen = number_format(memory_get_usage() / 1048576, 2);
 		$peakMem = number_format(memory_get_peak_usage() / 1048576, 2);
-		$time = number_format( microtime(true) - $start, 3);
+		$time    = number_format(microtime(true) - $start, 3);
 
-		$ui->log('', false);
-		$ui->log("[{$currMen}mb]{$peakMem}mb peak mem - {$time}s exec time", false);
+		$ui->debug("[{$currMen}mb]{$peakMem}mb peak mem - {$time}s exec time");
 	}
 
 	private function init( array $args, TextUI $ui ) : string {

diff --git a/src/Runner/TextUI.php b/src/Runner/TextUI.php
@@ -3,8 +3,13 @@
 namespace donatj\MDDoc\Runner;
 
 use CLI\Style;
+use Psr\Log\LoggerInterface;
+use Psr\Log\LoggerTrait;
+use Psr\Log\LogLevel;
 
-class TextUI {
+class TextUI implements LoggerInterface {
+
+	use LoggerTrait;
 
 	/** @var resource */
 	private $STDERR;
@@ -49,21 +54,42 @@ public function dropError( string $text, int $code = 1, ?string $additional = nu
 		die($code);
 	}
 
-	public function warning( string $text ) : void {
-		fwrite($this->STDERR, $this->getScript() . ": " . Style::yellow($text) . PHP_EOL);
-	}
-
 	public function println( string $text = '' ) : void {
 		fwrite($this->STDOUT, $text . PHP_EOL);
 	}
 
-	public function log( string $text, bool $timestamp = true ) : void {
-		if( $timestamp ) {
-			fwrite($this->STDERR, date('c '));
+	public function log( $level, $message, array $context = array() ) : void {
+		fwrite($this->STDERR, date('c '));
+
+		switch($level)  {
+			case LogLevel::DEBUG:
+				fwrite($this->STDERR, Style::cyan('DEBUG '));
+				break;
+			case LogLevel::INFO:
+				fwrite($this->STDERR, Style::green('INFO '));
+				break;
+			case LogLevel::NOTICE:
+				fwrite($this->STDERR, Style::blue('NOTICE '));
+				break;
+			case LogLevel::WARNING:
+				fwrite($this->STDERR, Style::yellow('WARNING '));
+				break;
+			case LogLevel::CRITICAL:
+			case LogLevel::ALERT:
+			case LogLevel::EMERGENCY:
+			case LogLevel::ERROR:
+				fwrite($this->STDERR, Style::red(strtoupper("{$level} ")));
+				break;
+			default:
+				fwrite($this->STDERR, "{$level} ");
 		}
 
-		fwrite($this->STDERR, $text);
+		fwrite($this->STDERR, $message);
 		fwrite($this->STDERR, PHP_EOL);
+
+		foreach( $context as $key => $value ) {
+			fwrite($this->STDERR, "  {$key}: {$value}" . PHP_EOL);
+		}
 	}
 
 	private function getScript() : string {