README

A powerful structured logging package for PHP applications. It provides colored console output, structured log formatting, and optional log forwarding via HTTP or WebSockets to a remote LogMachine server.

Why LogMachine?

If you’ve used plain error_log() or even Monolog, you know logs can quickly become hard to scan, messy to parse, and painful to centralize. LogMachine solves this with:

Feature	Why it matters
Color-coded CLI logs	Spot warnings and errors instantly in your terminal.
Structured JSON output	Easy to pipe into ELK, Loki, or any log processor.
Remote forwarding	Ship logs to your log server without extra setup.
Automatic context enrichment	No more boilerplate for `user` and `module`.
PSR-friendly	Works standalone or integrates with Monolog.
Small footprint	No heavy dependencies — drop it in and go.

CLI Output Example (colored):

[2025-08-08 14:32:00 UTC] [DEBUG] Debug message
➢ Log provided by: username@room
[2025-08-08 14:32:01 UTC] [INFO]  User logged in  {"user":"jdoe"}
➢ Log provided by: username@room
[2025-08-08 14:32:02 UTC] [WARNING] API rate limit approaching
➢ Log provided by: username@room
[2025-08-08 14:32:03 UTC] [ERROR]  	Database connection failed  {"host":"localhost"}
➢ Log provided by: username@room

Compatibility

This package is compatible with PHP v8.3.6 and above

📦 Installation

Install via Composer:

composer require bufferpunk/logmachine

or

composer require bufferpunk/logmachine dev-main

or

composer require bufferpunk/logmachine dev-main --ignore-platform-req=ext-mbstring

: Additional steps (Important)

create config directory

mkdir config

create a config file

touch config/logmachine.php

copy paste this to your logmachine.php file, then save:

<?php

return [

    'log_file' => __DIR__ . '/logs/all_logs.log',
    'error_file' => __DIR__ . '/logs/error_logs.log',
    'transport_error_file' => __DIR__ . '/logs/transport-error.log',

    /*
    |--------------------------------------------------------------------------
    | Local Logger Settings
    |--------------------------------------------------------------------------
    | Control how logs are displayed locally in your app (console/file).
    | - "color" => true enables colored log output
    | - "emoji" => true adds emojis per log level
    */
    'local' => [
        'color' => true,
        'emoji' => true,
    ],

    /*
    |--------------------------------------------------------------------------
    | Central Logging Settings
    |--------------------------------------------------------------------------
    | Configure remote log forwarding.
    |
    | - "http_enabled": Set to true to enable HTTP log transport
    | - "url": Central logging server URL (required if http_enabled is true)
    | - "room": Logical room/channel for your logs.
    |   If omitted, LogMachine will auto-generate a unique name.
    | - "user": You can uncomment this section and add your user name
    | - "module": You can edit this to the name of the project yo working on,
    |   The name or your org or anything meaningful.
    | - "headers": Optional extra headers (e.g. auth token)
    | - "timeout" / "connect_timeout": Network timeouts in seconds
    | - "verify_ssl": Whether to validate SSL certificates
    */
    'central' => [
        'http_enabled'    => false,    // can edit: disable by default
        'url'             => 'https://logmachine.bufferpunk.com', // default link
        'room'            => null,    // can edit: I preffer you just add a name
        //'user' => 'Test-user', // can edit: change to your user name (optional but a plus)
        //'module' => 'logmachine-php', // can edit: your module (optional but a plus)
        'headers'         => [
            // 'Authorization' => 'Bearer YOUR_TOKEN_HERE',
        ],
        'timeout'         => 30,
        'connect_timeout' => 10,
        'verify_ssl'      => true,
        'user_agent'      => 'LogMachine-Client/1.0',
    ],

];

🚀 Basic Usage

<?php

require __DIR__ . '/vendor/autoload.php';

use Bufferpunk\Logmachine\LogMachine;

// Load config (example: config/logmachine.php)
$config = require __DIR__ . '/config/logmachine.php';

// Create logger instance
$logger = LogMachine::create($config);

// Log messages
$logger->debug('Debug message');
$logger->info('User logged in', ['user' => 'jdoe']);
$logger->warning('API rate limit approaching');
$logger->error('Database connection failed', ['host' => 'localhost']);
$logger->success('Operation completed successfully!');

Configuration

You can pass the following configuration array when creating the Logger. LogMachine::create($config):

Option	Type	Default	Description
`channel`	`string`	`logmachine`	Logger channel name
`level`	`int`	`DEBUG`	Minimum log level to output (Monolog levels supported)
`log_file`	`string`	`null`	Path to general log file
`error_file`	`string`	`null`	Path to error-only log file
`transport_error_file`	`string`	`null`	Path for transport error logs (e.g., HTTP failures)
`http_retries`	`int`	`2`	Retries for failed HTTP requests
`http_retry_delay`	`int`	`1` second	Delay between HTTP retries
`central`	`array`	`null`	Remote log forwarding config (see below)
`enable_websocket`	`bool`	`false`	Enable WebSocket transport (not yet implemented)

Log Levels

LogMachine supports these log levels

Level	Description
`Debug`	Detailed debug info
`Info`	General application events
`Notice`	Normal but significant conditions
`Warning`	Warnings that require attention
`Error`	Runtime errors
`Critical`	Critical conditions
`Alert`	Immediate action required
`Emergency`	System unusable

Additionally, ColorLogger provides extra methods like:

$logger->success("Task completed!");

📡 Remote Forwarding (Central Logging)

To forward logs to a central log server, configure the central key:

'central' => [
    'room'   => 'my_app_room',   // optional, see note below
    'user'   => 'rezzcode',      // optional
    'module' => 'backend_api',   // optional
],

Note

If no transport is provided, logs are written locally only.

Room Naming Rule

If room is not provided, LogMachine will automatically generate one:

<user>_<module><random_number>

Example: rezzcode_backend23

This ensures every client has a unique room name, even if they skip configuration.

stracture

logmachine-php/
├── LICENSE
├── README.md
├── compos_install.sh
├── composer.json
├── src
│   ├── ColorLogger.php
│   ├── Formatters
│   │   ├── ColoredLineFormatter.php
│   │   └── PlainLineFormatter.php
│   ├── LogMachine.php
│   ├── Traits
│   │   └── ColorfulLoggerTrait.php
│   └── Transports
│       ├── HttpTransport.php
│       └── WebSocketTransport.php
├── public/
│   └── index.php (demo/test endpoint)
├── config/
│   └── logmachine.php
└── test

bufferpunk / logmachine

Maintainers

Package info

Statistics

Security