Initial xentral_oss_20.3.c9ffacf

classes/Components/Logger/docs/Logger.md

@@ -0,0 +1,136 @@
+# Usage
+
+## dependency injection via LoggerAwareTrait
+
+For logging inside your services, `use` the `Xentral\Components\Logger\LoggerAwareTrait`.
+A logger instance gets injected into your service on creation. No need to put the Logger in the constructor!
+Inside the class access the logger via `$this->logger`.
+
+Example:
+```php
+use Xentral\Components\Logger\LoggerAwareTrait;
+
+class MyService
+{
+    use LoggerAwareTrait;
+
+    public function __construct($myDependency1, $myDependency2)
+    {/*...*/}   
+
+    public function myMethod()
+    {
+        $this->logger->debug('This is my debug message.');
+        $this->logger->error('This is my error message.');
+    }
+}
+```
+
+**IMPORTANT**: This works only for objects created by the service container. For all other uses get a logger 
+instance from the service container: `$container->get('logger')`.
+
+## Log Levels
+
+#### EMERGENCY
+An emergency error should lead to customer calling the support for "emergency problem".
+- immediate action required
+- data loss is imminent
+- software is no more able to run
+- only skilled system administrator or our support can resolve the problem
+
+**"The last call for help before the application dies."**
+
+#### ALERT
+Use alert in cases where an administrator would want notification by email or sms.
+- less severe than emergency
+- problem is persistent
+- system administrator can resolve the problem
+- e.g. cannot connect database
+- e.g. userdata runs out of memory
+
+**"Hey Sysadmin, you must fix this! Otherwise, some/many people are not able to work."**
+
+#### CRITICAL
+Unhandled/unknown errors and errors that make a piece of software stop working.
+Ideally all CRITICALs should be turned into ERRORs over time.
+- component or dependency missing
+- unhandled exception (exception error page)
+- single page/module/cronjob unable to work persistently
+
+**"Something about this module is broken persistently - developer's attention required."**
+
+#### ERROR
+Catchable Error that will not break the application.
+Error log messages should give the developer a hint where to search for a problem.
+- temporary issue
+- error response from another API
+- error that could be resolved by the user
+- an error log message could occur alongside an "error" message on screen
+- might resolve after page reload
+
+**"I want at least this information in the log when an Error gets reported."**
+
+#### WARNING
+Exceptional occurrences that are not errors.
+- things that are not yet but can become problems in the future
+- using fallback scenario becaus of incomplete configuration
+- low performance
+- a warning log messag could occur alongside a "warning" message on screen
+
+**"It works that way, but it's not ideal - you should chage that."**
+
+#### NOTICE
+Notable events that let you understand a user's intention.
+- no technical detail or dumps!
+- max. one per user action
+- a cronjob started/finished
+- e.g. "User XY created a new lead."
+
+**"What was the user trying to do before the application crashed."**
+
+#### INFO
+Common events that describe a user's intention more detailed.
+- more verbose form of NOTICE.
+
+**"Might be helpful to reproduce the user's exact actions."**
+
+#### DEBUG
+Detailed debug information.
+- retrace the code line by line if needed
+- variable dumps
+- technical information
+
+**"I don't want to debug their production system, so I tell them to turn on DEBUG level and send me the log."**
+
+## Exceptions
+
+You can log an Exception with the complete description and stack-trace by passing it with the `'exception'`
+Key in the `context` parameter.
+The keyword `'exception'` is reserved and may only be used for Exceptions or other Throwables.
+
+Example:
+```php
+try {
+    //code
+} catch (Exception $e) {
+    $this->logger->error('An Exception was thrown.', ['exception' => $e]);
+}
+```
+
+## Message Variables
+
+You can use Variables in your Message and pass the values in the `context` array.
+The variable names must match an array key exactly (case-sensitive).
+Variable names may contain characters `A-Z a-z 0-9 _ and .` and must be enclosed by curly braces `{}`.   
+
+Example:
+```php
+$this->logger->info('{username} created ticket {ticketnr}', ['username' => $userName, 'ticketnr' => $ticketNr]);
+```
+
+## Dump
+
+Information that is passed in the context array and is not used as a message variable will appear in the `dump` section
+of the log entry. 
+If an `exception` is passed in the context array **only** the exception will appear in the dump and no other values.
+
+**IMPORTANT**: Do not leak sensitive data or passwords in the dump!