khalyomede/syslog

Log into your Syslog destination

Syslog

, _(*1)

Log into your Syslog destination., _(*2)

$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:, _(*3)

composer require khalyomede/syslog:1.*

Examples of uses

All the examples can be found in the /example folder., _(*4)

• 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:, _(*5)

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

Beware that the informational severity string equivalent is info., _(*6)

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:, _(*7)

$log->deleteIdentifier();

It returns an instance of Khalyomede\Syslog so you can chain it with any other method., _(*8)

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., _(*9)

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

Note, _(*10)

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

Exception, _(*12)

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, _(*13)

LogicException: - If one of the following properties are not filled: host, post, source, device, processus, _(*14)

RuntimeException: - If the socket creation failed - If the message could not be sent through the socket connection, _(*15)

critical

Sends a message to the log destination with a critical severity., _(*16)

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

Note, _(*17)

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

Exception, _(*19)

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, _(*20)

LogicException: - If one of the following properties are not filled: host, post, source, device, processus, _(*21)

RuntimeException: - If the socket creation failed - If the message could not be sent through the socket connection, _(*22)

date

Force the log to be timestamped to a specific date., _(*23)

public function date(DateTime $date): Syslog

Note, _(*24)

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., _(*25)

debug

Sends a message to the log destination with a debug severity., _(*26)

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

Note, _(*27)

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

Exception, _(*29)

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, _(*30)

LogicException: - If one of the following properties are not filled: host, post, source, device, processus, _(*31)

RuntimeException: - If the socket creation failed - If the message could not be sent through the socket connection, _(*32)

deleteIdentifier

Reset the identifier to its empty value., _(*33)

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., _(*34)

public function device(string $device): Syslog

emergency

Sends a message to the log destination with an emergency severity., _(*35)

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

Note, _(*36)

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

Exception, _(*38)

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, _(*39)

LogicException: - If one of the following properties are not filled: host, post, source, device, processus, _(*40)

RuntimeException: - If the socket creation failed - If the message could not be sent through the socket connection, _(*41)

error

Sends a message to the log destination with an error severity., _(*42)

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

Note, _(*43)

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

Exception, _(*45)

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, _(*46)

LogicException: - If one of the following properties are not filled: host, post, source, device, processus, _(*47)

RuntimeException: - If the socket creation failed - If the message could not be sent through the socket connection, _(*48)

facility

Set the target plateform. For more information, see the definition of this attribute on the Syslog RFC5424 documentation., _(*49)

public function facility(int $facility): Syslog

host

Set the target log destination host., _(*50)

public function host(string $host): Syslog

Note, _(*51)

The value should be an IP or a valid domain., _(*52)

identifier

Set an optional identifier to group your logs., _(*53)

public function source(string $source): Syslog

info

Sends a message to the log destination with an info severity., _(*54)

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

Note, _(*55)

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

Exception, _(*57)

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, _(*58)

LogicException: - If one of the following properties are not filled: host, post, source, device, processus, _(*59)

RuntimeException: - If the socket creation failed - If the message could not be sent through the socket connection, _(*60)

log

Log using an opt-in severity parameter. This has the same effect than any other others severity logging methods., _(*61)

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

Note, _(*62)

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

Exception, _(*64)

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, _(*65)

LogicException: - If one of the following properties are not filled: host, post, source, device, processus, _(*66)

RuntimeException: - If the socket creation failed - If the message could not be sent through the socket connection, _(*67)

notice

Sends a message to the log destination with a notice severity., _(*68)

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

Note, _(*69)

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

Exception, _(*71)

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, _(*72)

LogicException: - If one of the following properties are not filled: host, post, source, device, processus, _(*73)

RuntimeException: - If the socket creation failed - If the message could not be sent through the socket connection, _(*74)

port

Set the port of the log destination server address., _(*75)

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., _(*76)

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., _(*77)

public function source(string $source): Syslog

warning

Sends a message to the log destination with a warning severity., _(*78)

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

Note, _(*79)

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

Exception, _(*81)

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, _(*82)

LogicException: - If one of the following properties are not filled: host, post, source, device, processus, _(*83)

RuntimeException: - If the socket creation failed - If the message could not be sent through the socket connection, _(*84)

Prototype ready

This class lets you extend its functionality to your needs without having to dive into the source code. For example:, _(*85)

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., _(*86)