{"id":21493482,"url":"https://github.com/northrook/logger","last_synced_at":"2025-07-24T00:04:36.767Z","repository":{"id":225206797,"uuid":"765299633","full_name":"northrook/logger","owner":"northrook","description":"PSR-3 compliant logger","archived":false,"fork":false,"pushed_at":"2025-06-17T11:38:13.000Z","size":70,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-18T07:13:19.502Z","etag":null,"topics":["composer-package","logging","php","psr-3"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/northrook.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-02-29T16:50:42.000Z","updated_at":"2025-06-17T21:33:09.000Z","dependencies_parsed_at":"2024-02-29T20:05:34.463Z","dependency_job_id":"03faa8b7-f10f-4063-8349-3855102afb14","html_url":"https://github.com/northrook/logger","commit_stats":null,"previous_names":["northrook/logger"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/northrook/logger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/northrook%2Flogger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/northrook%2Flogger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/northrook%2Flogger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/northrook%2Flogger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/northrook","download_url":"https://codeload.github.com/northrook/logger/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/northrook%2Flogger/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266770280,"owners_count":23981536,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["composer-package","logging","php","psr-3"],"created_at":"2024-11-23T15:43:01.739Z","updated_at":"2025-07-24T00:04:35.872Z","avatar_url":"https://github.com/northrook.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Logger\n\n[PSR-3 compliant](https://www.php-fig.org/psr/psr-3/) logging implementation, for easy global logging.\n\nThe package provides two key classes:\n\n```php\nNorthrook\\Logger();     // a PSR-3 compliant logger.\nNorthrook\\Logger\\Log(); // a static accessor to any PSR-3 compliant logger. \n```\n\nThe goal of this package is to provide easy logging across your PHP application,\nespecially in scenarios where dependency injection may be cumbersome or impractical.\n\nUsing the static `Log` class, you can easily log directly to a `LoggerInterface` instance.\n\nThink of it as a _facade_ or _proxy_ to a `LoggerInterface` instance.\n\nIf you are a stickler for OOP, you can just use the `Logger` class directly.\n\n## Installation\n\nInstall the latest version with composer:\n\n```bash\ncomposer require northrook/logger\n```\n\n## Basic Usage\n\nThe `Log` class is a static accessor to a set `LoggerInterface`..\n\n```php\nuse Northrook\\Logger\\Log;\n\nLog::info( 'Hello World!' );\n```\n\nWhen any of the `Log` methods are called, the logger will instantiate a new `Logger` object if it has not been instantiated yet.\n\nThe included `Logger` will be the default.\n\n### Assigning a Logger\n\nYou can manually assign a `LoggerInterface` using `Log::setLogger()`:\n\n```php\nuse Northrook\\Logger\\Log;\n\nLog::setLogger( \n    logger: new Logger(), // LoggerInterface\n    import: true,         // bool - default: true\n);\n```\n\nIf `setLogger` is provided a `Northrook\\Logger` instance, it will import any log entries any previous `LoggerInterface`.\n\nIf you want to just override the current `LoggerInterface` without importing, pass `false` as the second argument:\n\n```php\nLog::setLogger( \n    logger: new Logger(), \n    import: false, \n);\n```\n\nThis is useful when you need to instantiate an arbitrary `LoggerInterface` earlier in your code,\nand later use the included `Northrook\\Logger` class.\n\nThe `Log` will act as a proxy to the `LoggerInterface` instance, using the included `Northrook\\Logger` class is not required at all.\n\n## Log - Static Accessor\n\nIt provides all the PSR-3 methods, with a few extras.\n\nThe arbitrary `log()` is replaced by the `Log::entry()` method.\n\n### Logging Exceptions\n\nThe `Log` class provides a method to easily log exceptions:\n\n```php\nuse Northrook\\Logger\\Log;\n\ntry {\n    $variable = \\file_get_contents( 'data.json' );\n} catch( \\Exception $exception ) {\n    Log::exception( \n        $exception,   // required\n        level: null,  // optional\n        message: null // optional\n        context: [],  // optional\n     );\n}\n\n// logged as:\n0 =\u003e 'warning',\n1 =\u003e 'ile_get_contents(data.json): Failed to open stream: No such file or directory',\n2 =\u003e [ 'exception' =\u003e $exception ],\n\n```\n\nIt will parse the exception and log it accordingly.\n\nIt will not overwrite the `$level` or `$message` if they are provided.\n\nThe `$context['exception']` will be set to the provided `$$exception`.\n\n### Precision Timestamps\n\nWhen setting a `LoggerInterfacing` using `Log::setLogger()`, you can pass a `bool $precision` argument, setting the static `$enablePrecision` property.\n\n\u003e[!IMPORTANT]\n\u003e The default value is `true`.\n\u003e It is recommended to set this value according to your environment, as it can be expensive in production. \n\nWhen `Log::setLogger()` is first called, a static `int` will be assigned to the `hrtime(true)`. This is used to calculate the `DeltaMs` and `OffsetMs` values.\n\nEach `Log::entry()` has the `?bool $precision` argument, which is `null` by default, using the static `$enablePrecision` property.\n\nUse this to set `$precision` for the current `Log::entry()` call.\n\n```php\nuse Northrook\\Logger\\Log;\n\nLog::setLogger( \n    logger: new Logger(), \n    import: true, \n    precision: true, // default: true\n);\n\n// enable precision for the current entry\nLog::entry( 'Hello World!', precision: true );\n\n// disable precision for the current entry\nLog::entry( 'Hello World!', precision: false );\n```\n\nEntries logged with `$precision` will have the following keys added to the `$context` array:\n```php\n'precision' =\u003e [\n    \"hrTime\" =\u003e 330531205286100 // The hrtime at the time of the log entry\n    \"hrDelta\" =\u003e 1081000        // The difference the current entry and first `Log::entry()` call\n    \"DeltaMs\" =\u003e \"1.08ms\"       // Time since initial `Log::setLogger()` call in milliseconds\n    \"OffsetMs\" =\u003e \"0.0079ms\"    // Time since the previous `Log::entry( .. precision: true )` call in milliseconds\n]\n```\n\n## Logger\n\nThe provided `Logger` class is a PSR-3 compliant logger, extending the `Psr\\Log\\AbstractLogger`, implementing the `Psr\\Log\\LoggerInterface` interface.\n\nIt provides access to all the PSR-3 methods, and is a drop-in replacement for any `Psr\\Log\\LoggerInterface` instance.\n\nIn addition, it a few simple methods for managing log entries:\n\n```php\n$logger = new Northrook\\Logger();\n\n$logger-\u003elog( ... )          // log an entry using the PSR-3 standard\n$logger-\u003ehasLogs() : bool    // check if there are any log entries\n$logger-\u003egetLogs() : array   // get all log entries, without manipulating them\n$logger-\u003ecleanLogs() : array // get all log entries, and clear them\n$logger-\u003eclear()             // clear all log entries, without getting them\n$logger-\u003ecount() : int       // count all log entries\n$logger-\u003eimport( $logger )   // import log entries from another LoggerInterface\n$logger-\u003eprintLogs() : array // get an array of each entry as a human-readable string\n```\n\nThe `printLogs()` method is useful for quickly printing all log entries.\n\nIt will **not** prefix a timestamp by default. Pass `true` as the first argument to prefix the timestamp.\n\n```php\n// example:\n$logger-\u003eentries = [ \n    0 =\u003e 'warning',\n    1 =\u003e 'ile_get_contents(data.json): Failed to open stream: No such file or directory',\n    2 =\u003e [ 'exception' =\u003e $exception ],\n];\n\n// default:\n0 =\u003e 'Warning: file_get_contents(data.json): Failed to open stream: No such file or directory'\n\n// with timestamp:\n0 =\u003e '[2024-06-20T06:47:47+00:00] Warning: file_get_contents(data.json): Failed to open stream: No such file or directory'\n\n```\n\nIf the Logger is destroyed without first calling `cleanLogs()`, the `printLogs()` method will print the logs to the PHP error log.\n\n## License\n\nLicensed under the [MIT Licence](LICENSE), and is free to use in any project.\n\n### Credits\n\n[BufferingLogger](https://github.com/symfony/error-handler/blob/master/BufferingLogger.php) - Nicolas Grekas \u003cp@tchwork.com\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnorthrook%2Flogger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnorthrook%2Flogger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnorthrook%2Flogger/lists"}