Skip to content

Commit 8f90527

Browse files
kodeartkodeart
committed
README updated
1 parent 92cdb32 commit 8f90527

1 file changed

Lines changed: 41 additions & 52 deletions

File tree

‎README.md‎

Lines changed: 41 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -5,118 +5,107 @@ A simple message logging library that implements [PSR-3][psr-3]
55
with several log processors. It supports multiple log writers that
66
can be set separately and process messages based on the log level.
77

8-
[![Minimum PHP Version](https://img.shields.io/badge/php-%3E%3D%207.0-8892BF.svg)](https://php.net/)
9-
[![Build Status](https://travis-ci.org/kodedphp/logging.svg?branch=master)](https://travis-ci.org/kodedphp/logging)
10-
[![Coverage Status](https://coveralls.io/repos/github/kodedphp/logging/badge.svg?branch=master)](https://coveralls.io/github/kodedphp/logging?branch=master)
118
[![Latest Stable Version](https://img.shields.io/packagist/v/koded/logging.svg)](https://packagist.org/packages/koded/logging)
9+
[![Build Status](https://travis-ci.org/kodedphp/logging.svg?branch=master)](https://travis-ci.org/kodedphp/logging)
10+
[![Codacy Badge](https://api.codacy.com/project/badge/Coverage/81ffd9cf1725485d8f6fb836617d002d)](https://www.codacy.com/app/kodeart/logging)
11+
[![Codacy Badge](https://api.codacy.com/project/badge/Grade/81ffd9cf1725485d8f6fb836617d002d)](https://www.codacy.com/app/kodeart/logging)
12+
[![Minimum PHP Version](https://img.shields.io/badge/php-%3E%3D%207.1-8892BF.svg)](https://php.net/)
1213
[![Software license](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](LICENSE)
1314

1415

1516
Installation
1617
------------
1718

18-
Use [composer][composer] because it's awesome. Run `composer require koded/logging`,
19-
or set it manually
19+
Use [composer][composer] and run
20+
> `composer require koded/logging`
2021
22+
or add it manually in your current `composer.json`
2123
```json
2224
{
2325
"require": {
24-
"koded/logging": "~1"
26+
"koded/logging": "~2"
2527
}
2628
}
2729
```
30+
2831
Usage
2932
-----
3033

3134
```php
3235
<?php
3336

3437
$settings = [
38+
'deferred' => false,
3539
'loggers' => [
36-
['class' => ErrorLog::class, 'levels' => Log::ERROR],
40+
['class' => Cli::class, 'levels' => Log::ERROR],
3741
['class' => File::class, 'levels' => Log::INFO]
3842
]
3943
];
4044

4145
$log = new Log($settings);
4246

43-
// This message is processed by ErrorLog and File
47+
// This message is processed by Cli and File
4448
$log->alert('The message with {variable}', ['variable' => 'useful info']);
4549

46-
// This message won't be processed by ErrorLog because the level is below ERROR
47-
// but *File* will handle it
50+
// This message won't be processed by Cli
51+
// because it's level is below ERROR,
52+
// but File will handle it
4853
$log->warning("You don't see anything");
49-
5054
```
5155

5256
Configuration
5357
-------------
5458

55-
There are two ways of throwing the log messages
56-
- automatically at the shutdown phase by using the `Log::process()` method somewhere in your bootstrap
57-
(at the very beginning of your project).
58-
**You should do this only once**.
59+
@TODO Fix the text for `register()` and `deferred` flag
5960

60-
```php
61-
<?php
62-
63-
$logger->register();
64-
65-
// or
66-
register_shutdown_function([$logger, 'process']);
67-
68-
// or
69-
register_shutdown_function([new Log($settings), 'process']);
70-
```
61+
| Param | Type | Required | Default | Description |
62+
|-----------:|:------:|:--------:|:----------------|:------------|
63+
| loggers | array | yes | (empty) | An array of log processors. Every processor is defined in array with it's own configuration parameters. See [processor directives](processor-default-directives) |
64+
| dateformat | string | no | "d/m/Y H:i:s.u" | The date format for the log message. Microseconds are prepended by default |
65+
| timezone | string | no | "UTC" | The desired timezone for the log message |
66+
| deferred | bool | no | false | A flag to set the Log instance how to dump messages. Set to TRUE if you want to process all accumulated messages at shutdown time. Otherwise, the default behavior is to process the message immediately after the LoggerInterface method is called |
7167

72-
- calling directly `$logger->process()` if you want immediate log messages.
73-
**This call will dump all accumulated messages and clear the stack**
74-
(after that the logger will be empty)
7568

69+
### Processor default directives
7670

77-
### Log and Processor default directives
78-
79-
Every log processor has it's own set of configuration directives.
71+
Every log processor has it's own set of configuration directives.
8072
The table shows log parameters in the classes.
8173

82-
| Param | Type | Required | Default | Description
83-
|:-----------|:--------|:--------:|:------------|:-----------
84-
| class | string | yes | | The name of the log processor class
85-
| levels | integer | no | -1 | Packed integer for bitwise comparison. See the constants in Logger class
86-
| dateformat | string | no | d/m/Y H:i:s | The datetime format for the log message
87-
| timezone | string | no | UTC | The desired timezone for the datetime log message
74+
| Param | Type | Required | Default | Description |
75+
|:-----------|:--------|:--------:|:--------------|:------------|
76+
| class | string | yes | | The name of the log processor class |
77+
| levels | integer | no | -1 | Packed integer for bitwise comparison. See the constants in Logger class |
8878

8979

9080
### Levels example
9181

92-
The messages are filtered with bitwise operator (as packed integer). Every processor will filter out the messages as
93-
defined in it's **levels** directive.
82+
The messages are filtered with bitwise operator against the `levels` value.
83+
Every processor will filter out the messages as defined in it's **levels** directive.
9484

95-
For instance, to log only WARNING, INFO and ERROR messages set levels to
85+
For instance, to log only WARNING, INFO and ERROR messages, set levels to
9686

9787
```php
98-
<?php
9988

100-
['levels' => Log::WARN | Log::INFO | Log::ERROR, ...]
89+
<?php
90+
[..., ['levels' => Log::WARN | Log::INFO | Log::ERROR, ...]],
10191
```
10292

10393
Tips:
10494
- every processor is configured separately
105-
- if you want to process all log levels, skip the `levels` value
95+
- if you want to process all log levels, skip the `levels` value or set it to -1 (by default)
10696
- if you want to suppress a specific processor, set it's level to 0
10797

10898

10999
Processors
110100
----------
111101

112-
| Class name | Description
113-
|-----------:|:-----------
114-
| ErrorLog | uses the [error_log()][error-log] function to send the message to PHP's logger
115-
| SysLog | will open the system logger and send messages using the [syslog()][syslog] function
116-
| Cli | for CLI applications, it can write the messages in the console
117-
| Memory | will store all messages in an array. Useful for unit tests if the logger is involved
118-
| File | saves the messages on a disk. It's a slow one and should be avoided
119-
| Voided | is here for no particular reason and purpose. It's the fastest one tho :)
102+
| Class name | Description |
103+
|-----------:|:-------------------------------------------------------------------------------------|
104+
| ErrorLog | uses the [error_log()][error-log] function to send the message to PHP's logger |
105+
| SysLog | will open the system logger and send messages using the [syslog()][syslog] function |
106+
| Cli | write the messages in the console (with STDOUT) |
107+
| Memory | will store all messages in an array. Useful for unit tests if the logger is involved |
108+
| File | saves the messages on a disk. **It's a slow one and should be avoided** |
120109

121110

122111
License

0 commit comments

Comments
 (0)