README

The Lllog Component is designed to record system execution logs according to user-defined specifications. Every time the component is called, a log entry is recorded, creating a historical record of all desired steps.

Note: The component now supports a multi-tenant setup using a dedicated tenant field, and it distinguishes between a summary (stored in the log field) and detailed data (stored in the data field).

Overview

There are two ways to use Lllog: the simplified mode and the advanced mode. Both start by initializing the object and setting initial configuration parameters.

Base Configuration

$log = new Logger(levels: Logger::ALL);

// Set context parameters:
$log->setApp('VirtualStore');            // Defines the application name
$log->setModule('products');             // Defines the module where logging occurs
$log->setAuthor('Leonidas');             // Sets the user responsible for the logs
$log->setTenant('OrganizationName');     // Sets the tenant/organization for the logs

Field Descriptions

app: Indicates the application name. If the log is from an application called “Virtual Store,” set the app attribute to VirtualStore. Example:
```
$log->setApp('VirtualStore');
```
module: Denotes the module where the log is recorded (e.g., products, orders). Example:
```
$log->setModule('products');
```
author: Specifies the user name or identifier who is using the system. Example:
```
$log->setAuthor('Leonidas');
```
tenant: A new dedicated field to clearly indicate the organization or tenant context of the log. Example:
```
$log->setTenant('OrganizationName');
```

Usage Modes

Simplified Mode

In this mode, you make a single call to record a log entry. The logging methods available are: info(), success(), error(), warning(), and debug().

Each of these methods uses the following parameters:

$log->[info|success|error|warning|debug](
    ?string $summary,       // The short summary or title of the log (stored in the "log" field)
    ?string $details,       // Detailed content or the full history (stored in the "data" field)
    ?string $key,           // An identifier (such as an ID or reference)
    bool|string $expire,    // Expiration period of the log. Boolean values: true for 14 days (P14D), false for 3 months (P3M) or a DateInterval string.
    ?array $jsonData,       // A JSON array of additional data, useful for reports
    ?string $alias          // An alias to mark the entry, useful in historical reports
)

summary: Represents the log’s short title or identifier. (Previously this was named $log.) Default Value: If not provided in a new insert, a default value such as “Log entry” is automatically used.
details: Contains the detailed log information and accumulates entries via calls to step().
key: An optional identifier for associating the log with a specific entity.
expire: Indicates how long the log should remain valid.
jsonData: Stores additional JSON data for reporting purposes.
alias: Acts as a checkpoint or alias for fixed historical log entries (which do not expire).

Example:

$log->info(
    'Calculating for order',  // summary
    'Detailed information about order calculation', // details
    null,                       // key
    true,                       // expire (true means 14 days)
    ['orderId' => 1234],        // jsonData
    'orderCalculation'          // alias
);

Advanced Mode

In advanced usage, you first record a log, capture its object, and then apply further modifications:

Recording a Log Entry:

$info = $log->key('365984')->info('Order Processing', 'Initial details');

Modifying the Log Entry:
- step(): Adds more detailed information to the log (appending to the "data" field). Example:
```
$info->step('Additional info appended later');
```
- changeStatus(): Alters the log type (e.g., from INFO to SUCCESS). Example:
```
$info->changeStatus(Logger::SUCCESS)->step('Order processed successfully');
```
- expire(): Adjusts the expiration setting for the log entry. Example:
```
$info->expire('P1M'); // Set a 1-month expiration period
```
- Setters with AutoUpdate Option: Methods like setKey(), setAlias(), and setJsonData() now accept an optional second parameter (autoUpdate, default true) that lets you decide if the change should be persisted immediately. Example:
```
$log->setTenant('OrganizationName', false)
    ->setKey('365984', false)
    ->setAlias('orderAlias', false);
$info = $log->info('Initial Summary', 'Initial Details');
```

Note: In advanced mode, always conclude the chain with one of the recording methods (info(), success(), error(), warning(), or debug()). This final call triggers the insertion of the log entry.

Legacy Interface

To ensure backward compatibility, the component provides a legacy trait that maps older method names to the new implementations. If your code still uses the legacy names, include the trait in your Logger class:

use LlLog\Traits\LegacyLoggerInterfaceTrait;

The trait defines methods such as:

stash($stash = true) → calls step($stash)
changeStatus(string $status) → calls setStatus($status)
key(string $key) → calls setKey($key)
alias(string $alias) → calls setAlias($alias)
jsonData(array $jsonData) → calls setJsonData($jsonData)
setLeveis(string|array $levels) → calls setLevels($levels)

This ensures that legacy code continues to work while you transition to the new interface.

Detailed Field Descriptions

summary: The short title or identifier of the log (now stored in the log field). This is a one-line text that identifies the log entry.
details: The complete and accumulating content of the log (stored in the data field). This field is updated via methods like step() to reflect the full history of the log.
AutoUpdate in Setters: When using setter methods like setTenant(), setKey(), setAlias(), or setJsonData(), an optional parameter (autoUpdate, defaulting to true) controls whether the change is immediately persisted or only updates the internal state.
Expiration: The expire parameter accepts either a boolean value—with true setting a 14-day expiration, false a 3-month expiration—or a custom expiration interval specified in DateInterval format.

Example Usage

Below is a comprehensive example that demonstrates both the simplified and advanced usages of the Logger:

// Basic Initialization:
$logger = new Logger(levels: Logger::ALL);
$logger->setTenant('OrganizationName');
$logger->setApp('CashBack');
$logger->setModule('rewardByOrder');
$logger->setAuthor('SystemUser');
// Optionally, set a default summary message (if none is provided during log creation)
$logger->setDefaultMessage('Log entry');

// Simplified Mode:
$logger->info('Calculating for order');

// Advanced Mode with additional steps:
$logger->stash('Stashing initial step');
$info = $logger->key('365984')->info('Order Processing', 'Initial details of the process');
$info->step('Additional detail appended later');
$info->changeStatus(Logger::SUCCESS)->step('Order processed successfully');

Additional Points

Summary vs. Details: The summary is stored in the log field and represents a short, identifying message. The detailed history of steps is stored in the data field.
Default Summary: For new log entries, if no summary is provided, a default message (e.g., "Log entry") is used automatically.
Legacy Methods: The legacy methods are maintained through a dedicated trait, ensuring that older codebases remain compatible with the new Logger functionality.

lliure / lllog

Maintainers

Details