khalyomede/syslog

Log into your Syslog destination

v1.0.0 2018-03-31 14:57 UTC

Requires

• php: >=7.0.0
• khalyomede/prototype: 1.*
• khalyomede/syslog-interface: 1.*
• psr/log: 1.*

Requires (Dev)

• phpspec/phpspec: 4.*

MIT

• khalyomede

README

Log into your Syslog destination.

$log->host('some.vendor.com')
  ->port(92883)
  ->facility(22)
  ->source('my.company.io')
  ->device('website')
  ->processus('price-index');

$log->debug('page loaded in 3.840 s');

Summary

• Prerequistes
• Installation
• Examples of uses
• Methods definitions
• Prototype ready

Prerequistes

• PHP version >= 7.0.0
• Socket extension enabled (php_sockets.dll on windows or php_sockets.so on Linux distributions)
• A log server that accepts UDP packet messages (as this library send the log through UDP)

Installation

In your project folder:

composer require khalyomede/syslog:1.*

Examples of uses

All the examples can be found in the /example folder.

• Example 1: logging into your log destination
• Example 2: templatize your message for logging
• Example 3: use a generic method for logging
• Example 4: templatize when using the generic logging
• Example 5: force the date before logging
• Example 6: specify an indentifier for your next logs

Example 1: logging into your log destination

use Khalyomede\Syslog;

$log = new Syslog;

$log->host('log.test.com')
  ->port(12345)
  ->facility(22)
  ->source('test.test.com')
  ->device('test-website')
  ->processus('test-home');

$log->debug("user created in 5ms");

Example 2: templatize your message for logging

use Khalyomede\Syslog;

$log = new Syslog;

$log->host('log.test.com')
  ->port(12345)
  ->facility(22)
  ->source('test.test.com')
  ->device('test-website')
  ->processus('test-home');

$message = "user {username} created successfuly";

$log->info($message, ['username' => 'johndoe']);

Example 3: use a generic method for logging

use Khalyomede\Syslog;
use Psr\Log\LogLevel;

$log = new Syslog;

$log->host('log.test.com')
  ->port(12345)
  ->facility(22)
  ->source('test.test.com')
  ->device('test-website')
  ->processus('test-home');

$log->log(LogLevel::ERROR, "the user could not be created because: this username already exists");

If you do not want to pass through the class constants of LogLevel, you can provide a string instead:

$log->log('error' 'the user could not be created because: this username already exists');

Beware that the informational severity string equivalent is info.

Example 4: templatize when using the generic logging

use Khalyomede\Syslog;
use Psr\Log\LogLevel;

$log = new Syslog;

$log->host('log.test.com')
  ->port(12345)
  ->facility(22)
  ->source('test.test.com')
  ->device('test-website')
  ->processus('test-home');

$message = "user {username} created successfuly";

$log->log(LogLevel::ERROR, $message, ['username' => 'johndoe']);

Example 5: force the date before logging

use Khalyomede\Syslog;

$log = new Syslog;

$log->host('log.test.com')
  ->port(12345)
  ->facility(22)
  ->source('test.test.com')
  ->device('test-website')
  ->processus('test-home')
  ->date(new DateTime('2017-11-29 04:34:09', new DateTimeZone('Europe/Paris')));

$log->emergency('detected forbidden access to database');

Example 6: specify an indentifier for your next logs

use Khalyomede\Syslog;

$log = new Syslog;

$log->host('log.test.com')
  ->port(12345)
  ->facility(22)
  ->source('test.test.com')
  ->device('test-website')
  ->processus('test-home')
  ->identifier('AZXT6');

$log->debug("database optimized in 33.09 s.");

The identifier will stick to your next logs. If you would like to clear it at a point, you can use:

$log->deleteIdentifier();

It returns an instance of Khalyomede\Syslog so you can chain it with any other method.

Methods definitions

• alert
• critical
• date
• debug
• deleteIdentifier
• device
• emergency
• error
• facility
• host
• identifier
• info
• log
• notice
• port
• processus
• source
• warning

alert

Sends a message to the log destination with an alert severity.

public function alert(string $message, array $context = []): Syslog

Note

The keys of the context should respect the following format: lower case, numbers, with underscores and periods only.

Exception

InvalidArgumentException:

• If the message is empty
• If the context does not contains an array of key-pairs values
• If one of the context keys is not properly formated

LogicException:

• If one of the following properties are not filled: host, post, source, device, processus

RuntimeException:

• If the socket creation failed
• If the message could not be sent through the socket connection

critical

Sends a message to the log destination with a critical severity.

public function critical(string $message, array $context = []): Syslog

Note

The keys of the context should respect the following format: lower case, numbers, with underscores and periods only.

Exception

InvalidArgumentException:

• If the message is empty
• If the context does not contains an array of key-pairs values
• If one of the context keys is not properly formated

LogicException:

• If one of the following properties are not filled: host, post, source, device, processus

RuntimeException:

• If the socket creation failed
• If the message could not be sent through the socket connection

date

Force the log to be timestamped to a specific date.

public function date(DateTime $date): Syslog

Note

If you do not call this method at each log call, the date will be set to the time at which you call the sysloger.

debug

Sends a message to the log destination with a debug severity.

public function debug(string $message, array $context = []): Syslog

Note

The keys of the context should respect the following format: lower case, numbers, with underscores and periods only.

Exception

InvalidArgumentException:

• If the message is empty
• If the context does not contains an array of key-pairs values
• If one of the context keys is not properly formated

LogicException:

• If one of the following properties are not filled: host, post, source, device, processus

RuntimeException:

• If the socket creation failed
• If the message could not be sent through the socket connection

deleteIdentifier

Reset the identifier to its empty value.

public function deleteIdentifier(): Syslog

device

Set the name of the device that is sending the log. For more information, see the definition of this attribute on the Syslog RFC5424 documentation.

public function device(string $device): Syslog

emergency

Sends a message to the log destination with an emergency severity.

public function emergency(string $message, array $context = []): Syslog

Note

The keys of the context should respect the following format: lower case, numbers, with underscores and periods only.

Exception

InvalidArgumentException:

• If the message is empty
• If the context does not contains an array of key-pairs values
• If one of the context keys is not properly formated

LogicException:

• If one of the following properties are not filled: host, post, source, device, processus

RuntimeException:

• If the socket creation failed
• If the message could not be sent through the socket connection

error

Sends a message to the log destination with an error severity.

public function error(string $message, array $context = []): Syslog

Note

The keys of the context should respect the following format: lower case, numbers, with underscores and periods only.

Exception

InvalidArgumentException:

• If the message is empty
• If the context does not contains an array of key-pairs values
• If one of the context keys is not properly formated

LogicException:

• If one of the following properties are not filled: host, post, source, device, processus

RuntimeException:

• If the socket creation failed
• If the message could not be sent through the socket connection

facility

Set the target plateform. For more information, see the definition of this attribute on the Syslog RFC5424 documentation.

public function facility(int $facility): Syslog

host

Set the target log destination host.

public function host(string $host): Syslog

Note

The value should be an IP or a valid domain.

identifier

Set an optional identifier to group your logs.

public function source(string $source): Syslog

info

Sends a message to the log destination with an info severity.

public function info(string $message, array $context = []): Syslog

Note

The keys of the context should respect the following format: lower case, numbers, with underscores and periods only.

Exception

InvalidArgumentException:

• If the message is empty
• If the context does not contains an array of key-pairs values
• If one of the context keys is not properly formated

LogicException:

• If one of the following properties are not filled: host, post, source, device, processus

RuntimeException:

• If the socket creation failed
• If the message could not be sent through the socket connection

log

Log using an opt-in severity parameter. This has the same effect than any other others severity logging methods.

public function log(string $level, string $message, array $context = []): Syslog

Note

The keys of the context should respect the following format: lower case, numbers, with underscores and periods only.

Exception

InvalidArgumentException:

• If the severity is empty
• If the severity is not one of the following: emergency, alert, critical, error, warning, notice, info, debug
• If the message is empty
• If the context does not contains an array of key-pairs values
• If one of the context keys is not properly formated

LogicException:

• If one of the following properties are not filled: host, post, source, device, processus

RuntimeException:

• If the socket creation failed
• If the message could not be sent through the socket connection

notice

Sends a message to the log destination with a notice severity.

public function notice(string $message, array $context = []): Syslog

Note

The keys of the context should respect the following format: lower case, numbers, with underscores and periods only.

Exception

InvalidArgumentException:

• If the message is empty
• If the context does not contains an array of key-pairs values
• If one of the context keys is not properly formated

LogicException:

• If one of the following properties are not filled: host, post, source, device, processus

RuntimeException:

• If the socket creation failed
• If the message could not be sent through the socket connection

port

Set the port of the log destination server address.

public function port(int $port): Syslog

processus

Set the original processus that is responsible for this log. For more information, see the definition of this attribute on the Syslog RFC5424 documentation.

public function processus(string $processus): Syslog

source

Set the original server that generated this log. For more information, see the definition of this attribute on the Syslog RFC5424 documentation.

public function source(string $source): Syslog

warning

Sends a message to the log destination with a warning severity.

public function warning(string $message, array $context = []): Syslog

Note

The keys of the context should respect the following format: lower case, numbers, with underscores and periods only.

Exception

InvalidArgumentException:

• If the message is empty
• If the context does not contains an array of key-pairs values
• If one of the context keys is not properly formated

LogicException:

• If one of the following properties are not filled: host, post, source, device, processus

RuntimeException:

• If the socket creation failed
• If the message could not be sent through the socket connection

Prototype ready

This class lets you extend its functionality to your needs without having to dive into the source code. For example:

use Khalyomede\Syslog;

$log = new Syslog;

$log->prototype('oneHourAgo', function() {
  $this->date->sub(new DateInterval('PT1H'));

  return $this;
});

$log->host('log.test.com')
  ->port(12345)
  ->facility(22)
  ->source('test.test.com')
  ->device('test-website')
  ->processus('test-home')
  ->date(new DateTime)
  ->oneHourAgo();

$log->info('test');

For more information, check khalyomede/prototype documentation.