Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00%
20 / 20
100.00%
1 / 1
 CRAP
n/a
0 / 0
FastForward\Iterator\debugIterable
100.00%
20 / 20
100.00%
1 / 1
 7
1<?php
2
3declare(strict_types=1);
4
5/**
6 * This file is part of php-fast-forward/iterators.
7 *
8 * This source file is subject to the license that is bundled
9 * with this source code in the file LICENSE.
10 *
11 * @copyright Copyright (c) 2025-2026 Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
12 * @license   https://opensource.org/licenses/MIT MIT License
13 *
14 * @see       https://github.com/php-fast-forward/iterators
15 * @see       https://github.com/php-fast-forward
16 * @see       https://datatracker.ietf.org/doc/html/rfc2119
17 */
18
19namespace FastForward\Iterator;
20
21use Stringable;
22
23/**
24 * Prints a debug representation of an iterable object.
25 *
26 * This function iterates over a `Traversable` object and prints each key-value pair,
27 * along with an optional section title. If no section title is provided, the function
28 * uses the class name of the iterable object.
29 *
30 * ## Example Usage:
31 *
32 * @example
33 * ```php
34 * use FastForward\Iterator\debugIterable;
35 * use ArrayIterator;
36 *
37 * $iterator = new ArrayIterator(['a' => 1, 'b' => 2, 'c' => 3]);
38 *
39 * debugIterable($iterator, 'Example Output');
40 * ```
41 *
42 * **Output:**
43 * ```
44 * === Example Output ===
45 *
46 * Length: 3
47 * Output: [
48 *   "a" => 1,
49 *   "b" => 2,
50 *   0 => 3,
51 * ]
52 * ```
53 *
54 * @param iterable $iterable the iterable object to debug
55 * @param string|null $section an optional title for the output section
56 */
57function debugIterable(iterable $iterable, ?string $section = null): void
58{
59    if (! $section) {
60        $section = $iterable::class;
61    }
62
63    printf(
64        '=== %s ===%s%sLength: %d%sOutput: [%s',
65        $section,
66        \PHP_EOL,
67        \PHP_EOL,
68        \count($iterable),
69        \PHP_EOL,
70        \PHP_EOL
71    );
72
73    foreach ($iterable as $key => $value) {
74        if (\is_string($key)) {
75            $key = \sprintf('"%s"', $key);
76        }
77
78        if (\is_string($value) || $value instanceof Stringable) {
79            $value = \sprintf('"%s"', $value);
80        }
81
82        if (! \is_scalar($value)) {
83            $value = json_encode($value, \JSON_PRETTY_PRINT | \JSON_UNESCAPED_SLASHES | \JSON_UNESCAPED_UNICODE);
84        }
85
86        printf('%s%s => %s,%s', '  ', $key, $value, \PHP_EOL);
87    }
88
89    printf(']%s', \PHP_EOL);
90}