Cleanup and refactoring (#14)

devanych · samdark · web-flow · commit 24585355bda5 · 2020-12-24T17:35:16.000+03:00
* Change Psalm level from 3 to 2
* Fix phpunit config
* Fix .gitignore
* Remove tests/bootstrap.php
* Update composer.json
* Add config
* Refactoring SyslogTarget
* Add description to readme
* Fix phpdoc

Co-authored-by: Alexander Makarov &lt;sam@rmcreative.ru&gt;
diff --git a/.gitignore b/.gitignore
@@ -1,27 +1,31 @@
-# IDE & OS files
+# phpstorm project files
 .idea
+
+# netbeans project files
 nbproject
+
+# zend studio for eclipse project files
 .buildpath
 .project
 .settings
-*.sublime-project
-*.sublime-workspace
+
+# windows thumbnail cache
 Thumbs.db
-.DS_Store
 
 # composer vendor dir
 /vendor
 
+/composer.lock
+
 # composer itself is not needed
 composer.phar
-composer.lock
+
+# Mac DS_Store Files
+.DS_Store
 
 # phpunit itself is not needed
 phpunit.phar
 # local phpunit config
 /phpunit.xml
 # phpunit cache
 .phpunit.result.cache
-
-# tests runtime
-/runtime
diff --git a/README.md b/README.md
@@ -6,10 +6,6 @@
     <br>
 </p>
 
-This library provides the Syslog target for the [yiisoft/log] library.
-
-[yiisoft/log]: https://github.com/yiisoft/log
-
 [![Latest Stable Version](https://poser.pugx.org/yiisoft/log-target-syslog/v/stable.png)](https://packagist.org/packages/yiisoft/log-target-syslog)
 [![Total Downloads](https://poser.pugx.org/yiisoft/log-target-syslog/downloads.png)](https://packagist.org/packages/yiisoft/log-target-syslog)
 [![Build status](https://github.com/yiisoft/log-target-syslog/workflows/build/badge.svg)](https://github.com/yiisoft/log-target-syslog/actions?query=workflow%3Abuild)
@@ -19,6 +15,47 @@ This library provides the Syslog target for the [yiisoft/log] library.
 [![static analysis](https://github.com/yiisoft/log-target-syslog/workflows/static%20analysis/badge.svg)](https://github.com/yiisoft/log-target-syslog/actions?query=workflow%3A%22static+analysis%22)
 [![type-coverage](https://shepherd.dev/github/yiisoft/log-target-syslog/coverage.svg)](https://shepherd.dev/github/yiisoft/log-target-syslog)
 
+This package provides the Syslog target for the [yiisoft/log](https://github.com/yiisoft/log) library.
+
+## Installation
+
+The package could be installed with composer:
+
+```
+composer install yiisoft/log-target-syslog
+```
+
+## General usage
+
+Creating a target:
+
+```php
+use Yiisoft\Log\Target\Syslog\SyslogTarget;
+
+$syslogTarget = new SyslogTarget($identity, $options, $facility);
+```
+
+- `$identity (string)` - The `openlog()` identity.
+- `$options (int)` - The `openlog()` options. Defaults to `LOG_ODELAY | LOG_PID`.
+- `$facility (int)` - The `openlog()` facility. Defaults to `LOG_USER`.
+
+For more information, see the description of the [`openlog()`](https://www.php.net/openlog) function.
+
+Creating a logger:
+
+```php
+$logger = new \Yiisoft\Log\Logger([$syslogTarget]);
+```
+
+For a description of using the logger, see the [yiisoft/log](https://github.com/yiisoft/log) package.
+
+For use in the [Yii framework](http://www.yiiframework.com/), see the configuration files:
+
+- [`config/common.php`](https://github.com/yiisoft/log-target-syslog/blob/master/config/common.php)
+- [`config/params.php`](https://github.com/yiisoft/log-target-syslog/blob/master/config/params.php)
+
+See [Yii guide to logging](https://github.com/yiisoft/docs/blob/master/guide/en/runtime/logging.md) for more info.
+
 ### Unit testing
 
 The package is tested with [PHPUnit](https://phpunit.de/). To run tests:
diff --git a/composer.json b/composer.json
@@ -22,10 +22,10 @@
     "prefer-stable": true,
     "require": {
         "php": "^7.4|^8.0",
-        "psr/log": "^1.1",
         "yiisoft/log": "^3.0@dev"
     },
     "require-dev": {
+        "php-mock/php-mock-phpunit": "^2.6",
         "phpunit/phpunit": "^9.4",
         "roave/infection-static-analysis-plugin": "^1.5",
         "spatie/phpunit-watcher": "^1.23",
@@ -44,6 +44,10 @@
     "extra": {
         "branch-alias": {
             "dev-master": "3.0.x-dev"
+        },
+        "config-plugin": {
+            "common": "config/common.php",
+            "params": "config/params.php"
         }
     },
     "config": {
diff --git a/config/common.php b/config/common.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+use Psr\Log\LoggerInterface;
+use Yiisoft\Aliases\Aliases;
+use Yiisoft\Log\Logger;
+use Yiisoft\Log\Target\Syslog\SyslogTarget;
+
+/* @var $params array */
+
+return [
+    LoggerInterface::class => static fn (SyslogTarget $syslogTarget) => new Logger([$syslogTarget]),
+
+    SyslogTarget::class => static fn (Aliases $aliases) => new SyslogTarget(
+        $aliases->get($params['yiisoft/log-target-syslog']['syslogTarget']['identity']),
+    ),
+];
diff --git a/config/params.php b/config/params.php
@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+return [
+    'yiisoft/log-target-syslog' => [
+        'syslogTarget' => [
+            'identity' => 'app',
+        ],
+    ],
+];
diff --git a/phpunit.xml.dist b/phpunit.xml.dist
@@ -1,27 +1,30 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit bootstrap="./tests/bootstrap.php"
-    backupGlobals="true"
-    colors="true"
-    verbose="true"
-    failOnRisky="true"
-    failOnWarning="true"
-    convertErrorsToExceptions="true"
-    convertNoticesToExceptions="true"
-    convertWarningsToExceptions="true"
-    stopOnFailure="false">
+
+<phpunit bootstrap="vendor/autoload.php"
+         colors="true"
+         verbose="true"
+         failOnRisky="true"
+         failOnWarning="true"
+         convertErrorsToExceptions="true"
+         convertNoticesToExceptions="true"
+         convertWarningsToExceptions="true"
+         stopOnFailure="false"
+         executionOrder="default"
+         resolveDependencies="true"
+>
+    <php>
+        <ini name="error_reporting" value="-1"/>
+    </php>
+
     <testsuites>
         <testsuite name="Yii Log - Syslog Target tests">
             <directory>./tests</directory>
         </testsuite>
     </testsuites>
 
-    <filter>
-        <whitelist>
-            <directory>./</directory>
-            <exclude>
-                <directory>./tests</directory>
-                <directory>./vendor</directory>
-            </exclude>
-        </whitelist>
-    </filter>
+    <coverage>
+        <include>
+            <directory>./src</directory>
+        </include>
+    </coverage>
 </phpunit>
diff --git a/psalm.xml b/psalm.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0"?>
 <psalm
-    errorLevel="3"
+    errorLevel="2"
     resolveFromConfigFile="true"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns="https://getpsalm.org/schema/config"
diff --git a/src/SyslogTarget.php b/src/SyslogTarget.php
@@ -9,36 +9,51 @@
 use Yiisoft\Log\Message;
 use Yiisoft\Log\Target;
 
+use const LOG_ALERT;
+use const LOG_CRIT;
+use const LOG_DEBUG;
+use const LOG_EMERG;
+use const LOG_ERR;
+use const LOG_INFO;
+use const LOG_NOTICE;
+use const LOG_ODELAY;
+use const LOG_PID;
+use const LOG_USER;
+use const LOG_WARNING;
+
 /**
  * SyslogTarget writes log to syslog.
  */
-class SyslogTarget extends Target
+final class SyslogTarget extends Target
 {
     /**
-     * @var string syslog identity
+     * @var string The string that is prefixed to each message.
+     *
+     * @see https://www.php.net/openlog
      */
     private string $identity;
 
     /**
-     * @var int syslog facility.
-     */
-    private int $facility = LOG_USER;
-
-    /**
-     * @var int openlog options. This is a bitfield passed as the `$option` parameter to [openlog()](http://php.net/openlog).
+     * @var int Bit options to be used when generating a log message.
+     *
      * Defaults to `LOG_ODELAY | LOG_PID`.
      *
-     * @see http://php.net/openlog for available options.
+     * @see https://www.php.net/openlog
      */
-    private int $options = LOG_ODELAY | LOG_PID;
+    private int $options;
 
     /**
-     * @var bool Whether the message format was previously set.
+     * @var int Used to specify what type of program is logging the message. This allows you to specify (in your
+     * machine's syslog configuration) how messages coming from different facilities will be handled.
+     *
+     * Defaults to `LOG_USER`.
+     *
+     * @see https://www.php.net/openlog
      */
-    private bool $isMessageFormatSet = false;
+    private int $facility;
 
     /**
-     * @var array syslog levels
+     * @var array Syslog levels.
      */
     private array $syslogLevels = [
         LogLevel::EMERGENCY => LOG_EMERG,
@@ -51,47 +66,38 @@ class SyslogTarget extends Target
         LogLevel::DEBUG => LOG_DEBUG,
     ];
 
-    public function setIdentity(string $identity): self
+    /**
+     * @param string $identity The string that is prefixed to each message.
+     * @param int $options Bit options to be used when generating a log message.
+     * @param int $facility Used to specify what type of program is logging the message. This allows you to specify (in your
+     * machine's syslog configuration) how messages coming from different facilities will be handled.
+     */
+    public function __construct(string $identity, int $options = LOG_ODELAY | LOG_PID, int $facility = LOG_USER)
     {
         $this->identity = $identity;
-        return $this;
-    }
-
-    public function setFacility(int $facility): self
-    {
-        $this->facility = $facility;
-        return $this;
-    }
-
-    public function setOptions(int $options): self
-    {
         $this->options = $options;
-        return $this;
-    }
+        $this->facility = $facility;
+        parent::__construct();
 
-    public function setFormat(callable $format): Target
-    {
-        $this->isMessageFormatSet = true;
-        return parent::setFormat($format);
+        $this->setFormat(static function (Message $message) {
+            return "[{$message->level()}][{$message->context('category', '')}] {$message->message()}";
+        });
     }
 
     /**
      * Writes log messages to syslog.
-     * Starting from version 2.0.14, this method throws RuntimeException in case the log can not be exported.
      *
-     * @throws RuntimeException
+     * @see https://www.php.net/openlog
+     * @see https://www.php.net/syslog
+     * @see https://www.php.net/closelog
+     *
+     * @throws RuntimeException If unable to export log through system log.
      */
-    public function export(): void
+    protected function export(): void
     {
         $formattedMessages = $this->getFormattedMessages();
         openlog($this->identity, $this->options, $this->facility);
 
-        if (!$this->isMessageFormatSet) {
-            $this->setFormat(static function (Message $message) {
-                return "[{$message->level()}][{$message->context('category', '')}] {$message->message()}";
-            });
-        }
-
         foreach ($this->getMessages() as $key => $message) {
             if (syslog($this->syslogLevels[$message->level()], $formattedMessages[$key]) === false) {
                 throw new RuntimeException('Unable to export log through system log.');
diff --git a/tests/SyslogTargetTest.php b/tests/SyslogTargetTest.php
diff --git a/tests/bootstrap.php b/tests/bootstrap.php
