PHPackages lucinda/logging - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Logging & Monitoring](/categories/logging) 4. / 5. lucinda/logging ActiveLibrary[Logging & Monitoring](/categories/logging) lucinda/logging =============== High-performance API performing logging for PHP applications into files or SysLog v4.1.2(3y ago)023.7k23MITPHPPHP ^8.1 Since Nov 7Pushed 3y ago1 watchersCompare [ Source](https://github.com/aherne/php-logging-api)[ Packagist](https://packagist.org/packages/lucinda/logging)[ Docs](https://github.com/aherne/php-logging-api)[ RSS](/packages/lucinda-logging/feed)WikiDiscussions master Synced 1mo ago READMEChangelogDependencies (1)Versions (41)Used By (3) Logging API =========== [](#logging-api) Table of contents: - [About](#about) - [Configuration](#configuration) - [Binding Points](#binding-points) - [Logging](#logging) - [Installation](#installation) - [Unit Tests](#unit-tests) - [Reference Guide](#reference-guide) - [Specifications](#specifications) - [How Are Log Lines Formatted](#how-are-log-lines-formatted) - [How to Bind a Custom Logger](#how-to-bind-a-custom-logger) About ----- [](#about) This API is a **skeleton** (requires [binding](#binding-points) by developers) logging system built on principles of simplicity and flexibility. Unlike Monolog, the industry standard in our days, it brings no tangible performance penalties and has near-zero learning curve just by keeping complexity to a minimum while offering you the ability to extend functionalities. [![diagram](https://camo.githubusercontent.com/003af36acecf810d1069a4834dec40637f5d558e72a04a8cf40becddc886a948/68747470733a2f2f7777772e6c7563696e64612d6672616d65776f726b2e636f6d2f6c6f6767696e672d6170692e737667)](https://camo.githubusercontent.com/003af36acecf810d1069a4834dec40637f5d558e72a04a8cf40becddc886a948/68747470733a2f2f7777772e6c7563696e64612d6672616d65776f726b2e636f6d2f6c6f6767696e672d6170692e737667) The whole idea of logging is reduced to just three steps: - **[configuration](#configuration)**: setting up an XML file where one or more loggers are set for each development environment - **[binding points](#binding-points)**: binding user-defined components defined in XML/code to API prototypes in order to gain necessary abilities - **[logging](#logging)**: creating a [Wrapper](https://github.com/aherne/php-logging-api/blob/master/src/Wrapper.php) instance based on above XML and using it to log API is fully PSR-4 compliant, only requiring PHP8.1+ interpreter and SimpleXML extension. To quickly see how it works, check: - **[installation](#installation)**: describes how to install API on your computer, in light of steps above - **[unit tests](#unit-tests)**: API has 100% Unit Test coverage, using [UnitTest API](https://github.com/aherne/unit-testing) instead of PHPUnit for greater flexibility - **[example](https://github.com/aherne/php-logging-api/blob/master/tests/WrapperTest.php)**: shows a deep example of API functionality based on unit test for [Wrapper](https://github.com/aherne/php-logging-api/blob/master/src/Wrapper.php) All classes inside belong to **Lucinda\\Logging** namespace! Configuration ------------- [](#configuration) To configure this API you must have a XML with a **loggers** tags inside: ``` ... ... ``` Where: - **loggers**: (mandatory) holds global logging policies. - {ENVIRONMENT}: name of development environment (to be replaced with "local", "dev", "live", etc) - **logger**: stores configuration settings for a single logger (eg: file logger) - *class*: (mandatory) full class name of [AbstractLoggerWrapper](https://github.com/aherne/php-logging-api/blob/master/src/AbstractLoggerWrapper.php) implementation, encapsulating respective logger configuration. Available values: - [Lucinda\\Logging\\Driver\\File\\Wrapper](https://github.com/aherne/php-logging-api/blob/master/drivers/File/Wrapper.php): use this if you want to log to files - [Lucinda\\Logging\\Driver\\SysLog\\Wrapper](https://github.com/aherne/php-logging-api/blob/master/drivers/SysLog/Wrapper.php): use this if you want to log to syslog - any user-defined PSR-4 compliant PHP class (incl. namespace) instance for your own custom logger (see: [How to bind a new logger](#how-to-bind-a-new-logger)) - {OPTIONS}: a list of extra attributes necessary to configure respective logger identified by *class* above: - *application*: (mandatory if [Driver\\SysLog\\Wrapper](https://github.com/aherne/php-logging-api/blob/master/drivers/SysLog/Wrapper.php)) value that identifies your site against other syslog lines. Eg: "mySite" - *format*: (mandatory if [Driver\\SysLog\\Wrapper](https://github.com/aherne/php-logging-api/blob/master/drivers/SysLog/Wrapper.php) or [Driver\\File\\Wrapper](https://github.com/aherne/php-logging-api/blob/master/drivers/File/Wrapper.php)) controls what will be displayed in log line (see: [How log lines are formatted](#how-log-lines-are-formatted)). Eg: "%d %v %e %f %l %m %u %i %a" - *path*: (mandatory if [Driver\\File\\Wrapper](https://github.com/aherne/php-logging-api/blob/master/drivers/File/Wrapper.php)) base name of file in which log is saved. Eg: "messages" - *rotation*: (optional if [Driver\\File\\Wrapper](https://github.com/aherne/php-logging-api/blob/master/drivers/File/Wrapper.php)) date algorithm to rotate log above. Eg: "Y-m-d" - any other: if a custom logger is used. Their values are available from argument of **setLogger** method CLASS will need to implement. (see: [How to bind a new logger](#how-to-bind-a-new-logger)) Example: ``` ``` Binding Points -------------- [](#binding-points) In order to remain flexible and achieve highest performance, API takes no more assumptions than those absolutely required! It offers developers instead an ability to bind to its prototypes via XML: XML Attribute @ TagClass PrototypeAbility Gained[class @ logger](#configuration)[AbstractLoggerWrapper](https://github.com/aherne/php-logging-api/blob/master/src/AbstractLoggerWrapper.php)Registers a loggerAPI already has following [AbstractLoggerWrapper](https://github.com/aherne/php-logging-api/blob/master/src/AbstractLoggerWrapper.php) implementation embedded: - [Lucinda\\Logging\\Driver\\File\\Wrapper](https://github.com/aherne/php-logging-api/blob/master/drivers/File/Wrapper.php): for logging to a rotating file on disk - [Lucinda\\Logging\\Driver\\SysLog\\Wrapper](https://github.com/aherne/php-logging-api/blob/master/drivers/SysLog/Wrapper.php): for logging on syslog But developers can bind their own (check: [How to Bind a Custom Logger](#how-to-bind-a-custom-logger)) Logging ------- [](#logging) Now that XML is configured, you can get a logger to save and use later on whenever needed by querying [Wrapper](https://github.com/aherne/php-logging-api/blob/master/src/Wrapper.php): ``` $object = new Lucinda\Logging\Wrapper(simplexml_load_file(XML_FILE_NAME), DEVELOPMENT_ENVIRONMENT); $logger = $object->getLogger(); ``` Logger returned is a [Logger](#interface-logger) that hides complexity of logger(s) underneath through a common interface centered on logging operations. Each [Logger](#interface-logger) must have a [AbstractLoggerWrapper](https://github.com/aherne/php-logging-api/blob/master/src/AbstractLoggerWrapper.php) whose job is to generate it based on info in XML. **NOTE**: because XML parsing is somewhat costly, it is recommended to save $logger somewhere and reuse it throughout application lifecycle. Installation ------------ [](#installation) First choose a folder where API will be installed then write this command there using console: ``` composer require lucinda/logging ``` Then create a *configuration.xml* file holding configuration settings (see [configuration](#configuration) above) and a *index.php* file (see [logging](#logging) above) in project root with following code: ``` require(__DIR__."/vendor/autoload.php"); $object = new Lucinda\Logging\Wrapper(simplexml_load_file("configuration.xml"), "local"); $logger = $object->getLogger(); $logger->info("test"); ``` Above has logged a "test" message with LOG\_INFO priority in messages\_\_YYYY-MM-DD.log file if same **loggers** tag as in example above is used. Unit Tests ---------- [](#unit-tests) For tests and examples, check following files/folders in API sources: - [test.php](https://github.com/aherne/php-logging-api/blob/master/test.php): runs unit tests in console - [unit-tests.xml](https://github.com/aherne/php-logging-api/blob/master/unit-tests.xml): sets up unit tests and mocks "loggers" tag - [tests](https://github.com/aherne/php-logging-api/tree/v3.0.0/tests): unit tests for classes from [src](https://github.com/aherne/php-logging-api/tree/v3.0.0/src) folder - [tests\_drivers](https://github.com/aherne/php-logging-api/tree/v3.0.0/tests_drivers): unit tests for classes from [drivers](https://github.com/aherne/php-logging-api/tree/v3.0.0/drivers) folder **NOTE**: on first run only, test.php will fail on syslog tests but from that moment on it will consistently pass Reference Guide --------------- [](#reference-guide) ### Interface Logger [](#interface-logger) [Logger](https://github.com/aherne/php-logging-api/blob/master/src/Logger.php) interface provides blueprints for level-oriented logging using following methods: MethodArgumentsReturnsDescriptionemergency[\\Throwable](https://www.php.net/manual/en/class.throwable.php) $exceptionvoidlogs a [\\Throwable](https://www.php.net/manual/en/class.throwable.php) using LOG\_ALERT priorityalert[\\Throwable](https://www.php.net/manual/en/class.throwable.php) $exceptionvoidlogs a [\\Throwable](https://www.php.net/manual/en/class.throwable.php) using LOG\_CRIT prioritycritical[\\Throwable](https://www.php.net/manual/en/class.throwable.php) $exceptionvoidlogs a [\\Throwable](https://www.php.net/manual/en/class.throwable.php) using LOG\_ERR priorityerror[\\Throwable](https://www.php.net/manual/en/class.throwable.php) $exceptionvoidlogs a [\\Throwable](https://www.php.net/manual/en/class.throwable.php) using LOG\_WARNING prioritywarningstring $messagevoidlogs a string using LOG\_WARNING prioritynoticestring $messagevoidlogs a string using LOG\_NOTICE prioritydebugstring $messagevoidlogs a string using LOG\_DEBUG priorityinfostring $messagevoidlogs a string using LOG\_INFO priorityUsage example: ### Abstract Class LoggerWrapper [](#abstract-class-loggerwrapper) [AbstractLoggerWrapper](https://github.com/aherne/php-logging-api/blob/master/src/AbstractLoggerWrapper.php) abstract class implements conversion of data in XML to a [Logger](#interface-logger) instance via following public methods: MethodArgumentsReturnsDescription\_\_constructSimpleXMLElement $xmlvoidReads XML and delegates to setLogger methodgetLoggervoid[Logger](#interface-logger)Gets [Logger](#interface-logger) generated based on XMLand following prototype method that needs to be implemented by developers: MethodArgumentsReturnsDescriptionsetLoggerSimpleXMLElement $xmlvoidReads XML and generates a [Logger](#interface-logger) objectUsage example: Specifications -------------- [](#specifications) Some guides helping developers to get the best of this API: - [How Are Log Lines Formatted](#how-are-log-lines-formatted) - [How to Bind a Custom Logger](#how-to-bind-a-custom-logger) ### How are log lines formatted [](#how-are-log-lines-formatted) As one can see above, [logger](#configuration) tags whose *class* is [Driver\\File\\Wrapper](https://github.com/aherne/php-logging-api/blob/master/drivers/File/Wrapper.php) and [Driver\\SysLog\\Wrapper](https://github.com/aherne/php-logging-api/blob/master/drivers/SysLog/Wrapper.php) support a *format* attribute whose value can be a concatenation of: - **%d**: current date using Y-m-d H:i:s format. - **%v**: syslog priority level constant value matching to Logger method called. - **%e**: name of thrown exception class () - **%f**: absolute location of file that logged message or threw a Throwable - **%l**: line in file above where message was logged or Throwable/Exception was thrown - **%m**: value of logged message or Throwable message - **%e**: class name of Throwable, if log origin was a Throwable - **%u**: value of URL when logging occurred, if available (value of $\_SERVER\["REQUEST\_URI"\]) - **%a**: value of USER AGENT header when logging occurred, if available (value of $\_SERVER\["HTTP\_USER\_AGENT"\]) - **%i**: value of IP when logging occurred, if available (value of $\_SERVER\["REMOTE\_ADDR"\]) Example: ``` ``` ### How to bind a custom logger [](#how-to-bind-a-custom-logger) Let us assume you want to bind a new SQL logger to this API. First you need to implement the logger itself, which must extend [Logger](#interface-logger) and implement its required **log** method: ``` class SQLLogger extends Lucinda\Logging\Logger { private $schema; private $table; public function __construct(string $schema, string $table) { $this->schema = $schema; $this->table = $table; } protected function log($info, int $level): void { // log in sql database based on schema, table, info and level } } ``` Now you need to bind logger above to XML configuration. To do so you must create another class extending [AbstractLoggerWrapper](https://github.com/aherne/php-logging-api/blob/master/src/AbstractLoggerWrapper.php) and implement its required **setLogger** method: ``` class SQLLoggerWrapper extends Lucinda\Logging\AbstractLoggerWrapper { protected function setLogger(\SimpleXMLElement $xml): Lucinda\Logging\Logger { $schema = (string) $xml["schema"]; $table = (string) $xml["table; return new SQLLogger($schema, $table); } } ``` In that case if "psr-4" attribute in composer.json associates "Lucinda\\Project\\" with "src/" folder then SQLLoggerWrapper must be placed in *src/Loggers* folder then you finally need to bind it to XML: ``` ``` ### Health Score 40 — FairBetter than 88% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity25 Limited adoption so far Community13 Small or concentrated contributor base Maturity84 Battle-tested with a long release history Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~43 days Recently: every ~9 days Total 40 Last Release 1423d ago Major Versions v2.0.6 → v3.0.02019-11-24 v2.0.x-dev → v3.0.6.12020-01-23 v3.2.1 → v4.0.02021-12-28 v3.2.2 → v4.0.x-dev2022-01-09 v3.2.3 → v4.0.42022-03-19 PHP version history (3 changes)v3.0.0PHP ^7.1 v4.0.0PHP ^8.1 v3.2.2PHP ^7.1|^8.0 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/3382770?v=4)[Lucian Gabriel Popescu](/maintainers/aherne)[@aherne](https://github.com/aherne) --- Top Contributors [![aherne](https://avatars.githubusercontent.com/u/3382770?v=4)](https://github.com/aherne "aherne (42 commits)") --- Tags loggingfilessyslogloggers ### Embed Badge ![Health badge](/badges/lucinda-logging/health.svg) ``` [![Health](https://phpackages.com/badges/lucinda-logging/health.svg)](https://phpackages.com/packages/lucinda-logging) ``` ### Alternatives [monolog/monolog Sends your logs to files, sockets, inboxes, databases and various web services 21.4k964.9M7.0k](/packages/monolog-monolog)[symfony/monolog-bundle Symfony MonologBundle 2.9k249.1M1.6k](/packages/symfony-monolog-bundle)[itsgoingd/clockwork php dev tools in your browser 5.9k27.6M94](/packages/itsgoingd-clockwork)[sentry/sentry PHP SDK for Sentry (http://sentry.io) 1.9k227.1M273](/packages/sentry-sentry)[sentry/sentry-laravel Laravel SDK for Sentry (https://sentry.io) 1.3k114.3M154](/packages/sentry-sentry-laravel)[sentry/sentry-symfony Symfony integration for Sentry (http://getsentry.com) 73661.4M66](/packages/sentry-sentry-symfony) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)