michaelschiemer/src/Framework/ExceptionHandling/ValueObjects/StackTrace.php

<?php

declare(strict_types=1);

namespace App\Framework\ExceptionHandling\ValueObjects;

use IteratorAggregate;
use Countable;
use Throwable;

/**
 * Stack Trace Collection für strukturierte Stack Trace Darstellung
 *
 * Enthält eine Sammlung von StackItems und bietet Formatierungsmethoden
 * für HTML, Console und JSON-Ausgabe.
 */
final readonly class StackTrace implements IteratorAggregate, Countable
{
    /**
     * @param StackItem[] $items
     */
    public function __construct(
        private array $items
    ) {
    }

    /**
     * Erstellt StackTrace aus Throwable
     */
    public static function fromThrowable(Throwable $exception): self
    {
        $items = [];
        $trace = $exception->getTrace();

        foreach ($trace as $frame) {
            $items[] = StackItem::fromArray($frame);
        }

        return new self($items);
    }

    /**
     * Begrenzt Anzahl der Frames
     */
    public function limit(int $maxFrames): self
    {
        return new self(array_slice($this->items, 0, $maxFrames));
    }

    /**
     * Formatiert für HTML-Ausgabe
     */
    public function formatForHtml(): string
    {
        $lines = [];
        foreach ($this->items as $index => $item) {
            $formatted = sprintf(
                '#%d %s',
                $index,
                htmlspecialchars($item->formatForDisplay(), ENT_QUOTES | ENT_HTML5, 'UTF-8')
            );
            $lines[] = $formatted;
        }

        return implode("\n", $lines);
    }

    /**
     * Formatiert für Console-Ausgabe
     */
    public function formatForConsole(): string
    {
        $lines = [];
        foreach ($this->items as $index => $item) {
            $lines[] = sprintf(
                '#%d %s',
                $index,
                $item->formatForDisplay()
            );
        }

        return implode("\n", $lines);
    }

    /**
     * Konvertiert zu Array für JSON-Serialisierung
     *
     * @return array<int, array<string, mixed>>
     */
    public function toArray(): array
    {
        return array_map(
            fn(StackItem $item) => $item->toArray(),
            $this->items
        );
    }

    /**
     * Gibt alle StackItems zurück
     *
     * @return StackItem[]
     */
    public function getItems(): array
    {
        return $this->items;
    }

    public function getIterator(): \Traversable
    {
        return new \ArrayIterator($this->items);
    }

    public function count(): int
    {
        return count($this->items);
    }
}