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:

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

mkdir config

touch config/logmachine.php

<?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' => [
        'url'             => 'https://logmachine.org', // default
		'default_format' => true, // you can change this to false

        /** HTTP transport **/
        'http_enabled' => false, // set to true to send logs via HTTP POST

        /** WebSocket / Socket.IO transport **/
        'websocket_enabled' => false, // set to true to stream logs over Socket.IO
        'socketio_path' => 'api/socket.io', // Socket.IO server path (default)

        'room'            => null,    // can edit: You can add your room name here.
        //'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)
		/**
			don't add your api key here; instead, add it to a .env file with the name
			lm_auth_token, or if you do, add this file to a .gitignore file.
		**/
		'auth' => 'your-optional-token',
        'headers' => [], // extra headers for the WebSocket handshake / HTTP requests
        '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):

Log Levels

LogMachine supports these log levels

• 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