<?php
/**
 * TraceCode Class
 *
 * @version     1.0.0
 * @package     bplan-base/globals
 * @subpackage  Logging
 * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
 * @copyright   Copyright (C) 2025, 2026 bplan-solutions GmbH & Co. KG <https://www.bplan-solutions.de/>
 * /Δ\
 */

namespace BplanBase\Globals\Logging;


use Stringable;


/**
 * Captures a trace code generated by AppLog methods.
 *
 * Because PHP does not support pass-by-reference via named parameters, this
 * object acts as a mutable handle: AppLog sets the value internally via
 * set(), and the caller reads it via get() or casts it to string.
 *
 * @version     1.0.0 / 2026-04-22
 * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
 */
class TraceCode implements Stringable
{


    /* +++ TRAITS +++ ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ */


    /* +++ CLASS CONSTANTS +++ ++++++++++++++++++++++++++++++++++++++++++++++++ */


    /* +++ OBJECT MEMBERS +++ +++++++++++++++++++++++++++++++++++++++++++++++++ */


    /**
     * @var     string|null
     */
    private ?string $_value = null;


    /* +++ CLASS MEMBERS +++ ++++++++++++++++++++++++++++++++++++++++++++++++++ */


    /* +++ OBJECT METHODS +++ ++++++++++++++++++++++++++++++++++++++++++++++++ */


    /**
     * @return      string
     */
    public function __toString(): string
    {
        return $this->_value ?? '';

    } // __toString()


    /**
     * @return      string|null
     */
    public function get(): string|null
    {
        return $this->_value;

    } // get()


    /**
     * @return      bool
     */
    public function isSet(): bool
    {
        return $this->_value !== null;

    } // isSet()


    /**
     * Called by AppLog to store the generated trace code.
     *
     * @param       string $value
     *
     * @return      void
     */
    public function set(string $value): void
    {
        $this->_value = $value;

    } // set()


    /* +++ CLASS METHODS +++ ++++++++++++++++++++++++++++++++++++++++++++++++++ */


    /**
     * Creates a new instance, ready to capture a trace code from AppLog.
     *
     * @return      static
     */
    public static function capture(): static
    {
        return new static();

    } // capture()


} // class TraceCode {}
