Entry.php

<?php

/**
 * This file is part of the DebugPHP package.
 *
 * (c) Leon Schmidt <kontakt@callmeleon.de>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 *
 * @see https://github.com/CallMeLeon167/debugphp
 */

declare(strict_types=1);

namespace DebugPHP;

/**
 * Represents a single debug entry sent to the dashboard.
 *
 * Instances are created by {@see Debug::send()} and returned to allow
 * fluent method chaining for setting color and type:
 *
 *     Debug::send($query, 'SQL')->color('blue')->type('sql');
 *
 * This class is not intended to be instantiated directly.
 */
final class Entry
{
    /**
     * List of valid color names accepted by the dashboard.
     *
     * @var list<string>
     */
    private const VALID_COLORS = [
        'red',
        'blue',
        'green',
        'orange',
        'purple',
        'gray',
    ];

    /**
     * Absolute path to the DebugPHP package source directory.
     */
    private const PACKAGE_DIR = __DIR__;

    /**
     * Maximum recursion depth for buildTyped().
     * Prevents infinite loops on circular references.
     */
    private const MAX_DEPTH = 10;

    /**
     * The HTTP client used to send data to the server.
     */
    private Client $client;

    /**
     * The current session token.
     */
    private string $session;

    /**
     * The request lifecycle ID generated by Debug::init().
     */
    private string $requestId;

    /**
     * The raw debug data provided by the user.
     */
    private mixed $data;

    /**
     * A descriptive label for categorizing this entry (e.g. "SQL", "Error").
     */
    private string $label;

    /**
     * The display color for this entry in the dashboard.
     */
    private string $color;

    /**
     * The type/category of this entry (e.g. "info", "sql", "error", "timer").
     */
    private string $type;

    /**
     * The source file where Debug::send() was called.
     */
    private string $file;

    /**
     * The directory path of the source file.
     */
    private string $path;

    /**
     * The line number where Debug::send() was called.
     */
    private int $line;

    /**
     * Whether the entry has been dispatched to the server.
     */
    private bool $hasDispatched = false;

    /**
     * Creates a new debug entry and marks it for sending.
     *
     * The entry is NOT immediately dispatched. Instead, it will be sent
     * automatically when the object is destroyed (via __destruct) or when
     * send() is called explicitly.
     *
     * The source file and line number are automatically resolved from
     * the call stack using {@see resolveCaller()}.
     *
     * @param Client $client    The HTTP client instance.
     * @param string $session   The current session token.
     * @param string $requestId The request lifecycle ID from Debug::init().
     * @param mixed  $data      The debug data to send.
     * @param string $label     A descriptive label for this entry.
     */
    public function __construct(Client $client, string $session, string $requestId, mixed $data, string $label = '')
    {
        $this->client    = $client;
        $this->session   = $session;
        $this->requestId = $requestId;
        $this->data      = $data;
        $this->label     = $label;
        $this->color     = 'gray';
        $this->type      = 'info';

        $caller     = $this->resolveCaller();
        $this->file = $caller['file'];
        $this->path = $caller['path'];
        $this->line = $caller['line'];
    }

    /**
     * Sets the display color for this entry in the dashboard.
     *
     * Available colors: red, blue, green, orange, purple, gray.
     * Invalid color names are silently ignored.
     *
     * @param string $color The color name to apply.
     *
     * @return $this For method chaining.
     */
    public function color(string $color): self
    {
        if (in_array($color, self::VALID_COLORS, true)) {
            $this->color = $color;
        }

        return $this;
    }

    /**
     * Sets the type/category for this entry in the dashboard.
     *
     * Common types: info, sql, error, success, cache, timer.
     * Custom types are allowed and will be displayed as-is.
     *
     * @param string $type The type name to apply.
     *
     * @return $this For method chaining.
     */
    public function type(string $type): self
    {
        $this->type = $type;

        return $this;
    }

    /**
     * Explicitly sends the entry to the server immediately.
     *
     * Normally you don't need to call this - the entry will be sent
     * automatically when the object is destroyed. Use this method only
     * if you need to ensure the entry is sent at a specific point.
     *
     * @return $this For method chaining.
     */
    public function send(): self
    {
        $this->dispatch();
        return $this;
    }

    /**
     * Destructor - automatically sends the entry when the object is destroyed.
     *
     * This ensures that chained method calls only result in a single HTTP
     * request, sent after all modifications are complete.
     */
    public function __destruct()
    {
        $this->dispatch();
    }

    /**
     * Sends the current entry payload to the DebugPHP server.
     *
     * Only sends once - subsequent calls are ignored to prevent duplicate
     * requests from both __destruct and explicit send() calls.
     */
    private function dispatch(): void
    {
        if ($this->hasDispatched) {
            return;
        }

        $this->hasDispatched = true;

        $data = $this->type === 'table'
            ? $this->data
            : $this->buildTyped($this->data);

        $this->client->send('/api/debug', [
            'session'    => $this->session,
            'request_id' => $this->requestId,
            'data'       => $data,
            'label'      => $this->label,
            'color'      => $this->color,
            'type'       => $this->type,
            'origin'     => [
                'file' => $this->file,
                'path' => $this->path,
                'line' => $this->line,
            ],
            'timestamp'  => microtime(true),
        ]);
    }

    /**
     * Converts a PHP value into a typed descriptor array for transmission.
     *
     * Produces a recursive structure that preserves PHP-native type information
     * (including class names for objects and string lengths), which the dashboard
     * renders in a var_dump-style format rather than plain JSON.
     *
     * Supported types:
     *   null, bool, int, float, string, array, object, Throwable, resource
     *
     * @param mixed $value The value to convert.
     * @param int   $depth Current recursion depth (internal use only).
     *
     * @return array<string, mixed> The typed descriptor.
     */
    private function buildTyped(mixed $value, int $depth = 0): array
    {
        if ($depth >= self::MAX_DEPTH) {
            return ['type' => 'truncated'];
        }

        if ($value === null) {
            return ['type' => 'null'];
        }

        if (is_bool($value)) {
            return ['type' => 'bool', 'value' => $value];
        }

        if (is_int($value)) {
            return ['type' => 'int', 'value' => $value];
        }

        if (is_float($value)) {
            return ['type' => 'float', 'value' => $value];
        }

        if (is_string($value)) {
            return ['type' => 'string', 'length' => strlen($value), 'value' => $value];
        }

        if (is_resource($value)) {
            return ['type' => 'resource', 'value' => get_resource_type($value)];
        }

        if ($value instanceof \Throwable) {
            return $this->buildTypedThrowable($value, $depth);
        }

        if (is_array($value)) {
            $items = [];

            foreach ($value as $k => $v) {
                $items[] = ['key' => $k, 'value' => $this->buildTyped($v, $depth + 1)];
            }

            return ['type' => 'array', 'length' => count($value), 'value' => $items];
        }

        if (is_object($value)) {
            $props = [];

            foreach ((array) $value as $propName => $propValue) {
                $cleanKey = (string) preg_replace('/^\0[^\0]*\0/', '', $propName);
                $props[]  = ['key' => $cleanKey, 'value' => $this->buildTyped($propValue, $depth + 1)];
            }

            return [
                'type'   => 'object',
                'class'  => $value::class,
                'length' => count($props),
                'value'  => $props,
            ];
        }

        return ['type' => 'unknown', 'value' => $value];
    }

    /**
     * Builds a typed descriptor for a Throwable instance.
     *
     * Extracts message, code, file, line, and a condensed stack trace
     * (file:line pairs only, to keep the payload lean).
     *
     * @param \Throwable $throwable The exception or error to describe.
     * @param int        $depth     Current recursion depth.
     *
     * @return array<string, mixed> The typed descriptor.
     */
    private function buildTypedThrowable(\Throwable $throwable, int $depth): array
    {
        $traceStrings = array_map(
            static fn(array $frame): string => ($frame['file'] ?? 'unknown') . ':' . ($frame['line'] ?? 0),
            $throwable->getTrace(),
        );

        return [
            'type'  => 'exception',
            'class' => $throwable::class,
            'value' => [
                ['key' => 'message', 'value' => $this->buildTyped($throwable->getMessage(), $depth + 1)],
                ['key' => 'code',    'value' => $this->buildTyped($throwable->getCode(), $depth + 1)],
                ['key' => 'file',    'value' => $this->buildTyped($throwable->getFile(), $depth + 1)],
                ['key' => 'line',    'value' => $this->buildTyped($throwable->getLine(), $depth + 1)],
                ['key' => 'trace',   'value' => $this->buildTyped($traceStrings, $depth + 1)],
            ],
        ];
    }

    /**
     * Resolves the original file and line number where the Debug call was made.
     *
     * Walks up the debug backtrace and returns the first frame whose file
     * is located outside the DebugPHP package source directory. This makes
     * the resolver work correctly regardless of which public Debug method
     * was used.
     *
     * @return array{file: string, path: string, line: int} The resolved file basename, path, and line number.
     */
    private function resolveCaller(): array
    {
        $trace = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS);

        foreach ($trace as $frame) {
            $fullpath = $frame['file'] ?? '';

            if ($fullpath === '') {
                continue;
            }

            if (str_starts_with($fullpath, self::PACKAGE_DIR)) {
                continue;
            }

            return [
                'file' => basename($fullpath),
                'path' => dirname($fullpath),
                'line' => $frame['line'] ?? 0,
            ];
        }

        return [
            'file' => 'unknown',
            'path' => 'unknown',
            'line' => 0,
        ];
    }
}