php-censor/docs/en/logging.md

Setting up Logging
==================

Basics
------

The PHP Censor codebase makes use of the [PSR3](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md) logging standard. By default we use [Monolog](https://github.com/Seldaek/monolog) to handle the actual work implementing this standard.

How to Setup Logging (For people running a PHP Censor instance)
---------------------------------------------------------------

The only step required to activate logging is to create a file in the root directory called loggerconfig.php with content like the following:

```php
<?php
return [
    /** Loggers attached to every command */
    "_" => function () {
        return [
            new \Monolog\Handler\StreamHandler('path/to/log', \Monolog\Logger::ERROR),
        ];
    }
];
```
This file should return an array of key value pairs. Each key tells PHP Censor which command to attach the logger to (the underscore is a special value which matches all commands). For each command an array of [Monolog](https://github.com/Seldaek/monolog) handlers should be returned. In the example above we've used one that simply writes to the file system but in practise this could be any handler written for monolog.

Once this file is created all plugins and core PHP Censor functionality should start writing to the configured handlers. 

How to write to the Log (For people creating a new plugin)
----------------------------------------------------------

### Using the plugin constructor to get a logger directly

For plugin creators the simplest way to get hold of an error logger is to add a parameter to the constructor and typehint on 'Psr\Log\LoggerInterface'. The code that loads your plugin will automatically inject the logger when it sees this. For example:
```php
class ExampleLoggingPlugin implements \PHPCensor\Plugin
{
    protected $log;

    public function __construct(Psr\Log\LoggerInterface $log)
    {
        $this->log = $log;
    }

    public function execute()
    {
        $this->log->notice("You'll notice this in the log");
    }
}
```

### Using convenience methods provided by the Builder
Your plugin can also call a couple of messages on the Builder object:

logSuccess()
logFailure()
log()

All calls will get piped through to the appropriate logger.