sebastianbergmann/exporter

Provides the functionality to export PHP variables for visualization

Hi!

I am Sebastian Bergmann. If you develop software using the PHP programming language then you may have come across my name. I am the creator and maintainer of PHPUnit as well as many other libraries and tools that are commonly used.

---

👷 Check out what I'm currently working on

• sebastianbergmann/csv-parser - Library for type-safe parsing of CSV files (1 day ago)
• sebastianbergmann/phpunit - The PHP Unit Testing framework. (2 days ago)
• sebastianbergmann/phpunit-documentation-english - English Documentation for PHPUnit (1 week ago)
• sebastianbergmann/raytracer - Code written while reading the book "The Ray Tracer Challenge: A Test-Driven Guide to Your First 3D Renderer" by Jamis Buck. (1 month ago)
• sebastianbergmann/phpunit-website - https://phpunit.de/ (1 month ago)
• sebastianbergmann/cli-parser - Library for parsing CLI options (1 month ago)
• sebastianbergmann/exporter - Provides the functionality to export PHP variables for visualization (1 month ago)
• sebastianbergmann/code-unit - Collection of value objects that represent the PHP code units (1 month ago)
• sebastianbergmann/recursion-context - Provides functionality to recursively process PHP variables (1 month ago)
• sebastianbergmann/foal - Tool to find lines eliminated by OpCache's bytecode optimizer (1 month ago)

---

🔭 Latest releases I've contributed to

• sebastianbergmann/phpunit (11.1.3, 1 week ago) - The PHP Unit Testing framework.
• sebastianbergmann/foal (0.3.0, 1 month ago) - Tool to find lines eliminated by OpCache's bytecode optimizer
• sebastianbergmann/environment (7.1.0, 1 month ago) - Provides functionality that helps writing PHP code that has runtime-specific execution paths
• sebastianbergmann/php-code-coverage (11.0.3, 1 month ago) - Library that provides collection, processing, and rendering functionality for PHP code coverage information.
• sebastianbergmann/csv-parser (1.0.0, 1 month ago) - Library for type-safe parsing of CSV files
• phar-io/manifest (2.0.4, 2 months ago) - Component for reading phar.io manifest information from a PHP Archive (PHAR)
• theseer/tokenizer (1.2.3, 2 months ago) - A small library for converting tokenized PHP source code into XML (and potentially other formats)
• templado/engine (4.2.5, 2 months ago) - A pragmatic approach to templating for PHP 8.2+

---

📫 How to reach me

• Email: [email protected]
• Fediverse: @[email protected]

exporter's Issues

Fix issues identified by Psalm that are currently ignored (baseline)

HHVM Compatibility

Known issues:

• SplObjectStorage gives different output, as it's just a regular object in HHVM
• Recursive data structures fail: facebook/hhvm#1667

`Exporter::toArray()` changes `SplObjectStorage` index

Q	A
PHPUnit version	10.3.3
PHP version	8.1.23
Installation Method	Composer

Summary

When using the --log-events-text or --log-events-verbose-text options, the Assert::assertInstanceOf() method changes the SplObjectStorage index.

Removing the Assert::assertInstanceOf() call or calling SplObjectStorage::rewind() after the Assert::assertInstanceOf() call fixes the issue.

Current behavior

$ vendor/bin/phpunit --no-configuration --do-not-cache-result tests/ObjectStorageTest.php 
PHPUnit 10.3.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.1.23

.                                                                   1 / 1 (100%)

Time: 00:00.003, Memory: 8.00 MB

OK (1 test, 2 assertions)

$ vendor/bin/phpunit --no-configuration --do-not-cache-result --no-progress --log-events-text php://stdout tests/ObjectStorageTest.php
PHPUnit 10.3.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.1.23

PHPUnit Started (PHPUnit 10.3.3 using PHP 8.1.23 (cli) on Linux)
Test Runner Configured
Test Suite Loaded (1 test)
Event Facade Sealed
Test Runner Started
Test Suite Sorted
Test Runner Execution Started (1 test)
Test Suite Started (ObjectStorageTest, 1 test)
Test Preparation Started (ObjectStorageTest::testOne)
Test Prepared (ObjectStorageTest::testOne)
Assertion Succeeded (Constraint: is an instance of class SplObjectStorage, Value: SplObjectStorage Object sebastianbergmann/phpunit#405 (
    'Object sebastianbergmann/phpunit#97' => Array &0 (
        'obj' => stdClass Object sebastianbergmann/phpunit#97 ()
        'inf' => null
    )
))
Test Errored (ObjectStorageTest::testOne)
Called current() on invalid iterator
Test Finished (ObjectStorageTest::testOne)
Test Suite Finished (ObjectStorageTest, 1 test)
Test Runner Execution Finished
Test Runner Finished
Time: 00:00.007, Memory: 8.00 MB

There was 1 error:

1) ObjectStorageTest::testOne
RuntimeException: Called current() on invalid iterator

/redacted/tests/ObjectStorageTest.php:11

ERRORS!
Tests: 1, Assertions: 1, Errors: 1.
PHPUnit Finished (Shell Exit Code: 2)

How to reproduce

<?php
declare(strict_types=1);
final class ObjectStorageTest extends PHPUnit\Framework\TestCase
{
    public function testOne(): void
    {
        $objectStorage = new SplObjectStorage();
        $object = new stdClass();
        $objectStorage->attach($object);
        $this->assertInstanceOf(SplObjectStorage::class, $objectStorage);
        $this->assertSame($object, $objectStorage->current());
    }
}

Expected behavior

The Assert::assertInstanceOf() method should not change the SplObjectStorage index.

Should be equals to:

<?php
declare(strict_types=1);
final class ObjectStorageTest extends PHPUnit\Framework\TestCase
{
    public function testOne(): void
    {
        $objectStorage = new SplObjectStorage();
        $object = new stdClass();
        $objectStorage->attach($object);
        $this->assertInstanceOf(SplObjectStorage::class, $objectStorage);
        $objectStorage->rewind();
        $this->assertSame($object, $objectStorage->current());
    }
}

$ vendor/bin/phpunit --no-configuration --do-not-cache-result --no-progress --log-events-text php://stdout tests/ObjectStorageTest.php
PHPUnit 10.3.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.1.23

PHPUnit Started (PHPUnit 10.3.3 using PHP 8.1.23 (cli) on Linux)
Test Runner Configured
Test Suite Loaded (1 test)
Event Facade Sealed
Test Runner Started
Test Suite Sorted
Test Runner Execution Started (1 test)
Test Suite Started (ObjectStorageTest, 1 test)
Test Preparation Started (ObjectStorageTest::testOne)
Test Prepared (ObjectStorageTest::testOne)
Assertion Succeeded (Constraint: is an instance of class SplObjectStorage, Value: SplObjectStorage Object sebastianbergmann/phpunit#405 (
    'Object sebastianbergmann/phpunit#97' => Array &0 (
        'obj' => stdClass Object sebastianbergmann/phpunit#97 ()
        'inf' => null
    )
))
Assertion Succeeded (Constraint: is identical to an object of class "stdClass", Value: stdClass Object sebastianbergmann/phpunit#97 ())
Test Passed (ObjectStorageTest::testOne)
Test Finished (ObjectStorageTest::testOne)
Test Suite Finished (ObjectStorageTest, 1 test)
Test Runner Execution Finished
Test Runner Finished
Time: 00:00.004, Memory: 8.00 MB

OK (1 test, 2 assertions)
PHPUnit Finished (Shell Exit Code: 0)

Improve export of closed resources

Given the following code:

use SebastianBergmann\Exporter\Exporter;

include __DIR__ . '/vendor/autoload.php';

$exporter = new Exporter;

$dir = opendir( __DIR__ );
echo $exporter->export($dir), PHP_EOL;

closedir($dir);
echo $exporter->export($dir), PHP_EOL;

... the output would be along the lines of:

resource(11) of type (stream)
NULL

... which when used in a PHPUnit error message results is something along the lines of:

Failed asserting that NULL is not of type "boolean"

I'd like to suggest reporting closed resources as resource (closed) instead of NULL.

Modernize build automation

• Use GitHub Actions instead of Travis CI
• Have Composer in tools/composer and managed through composer self-update (see update-tools target in build.xml
• Install Psalm using Phive as tools/psalm (phive install --copy psalm)
• Install PHP-CS-Fixer using Phive as tools/php-cs-fixer (phive install --copy php-cs-fixer)
• Create Psalm configuration
• Add Psalm build step to GitHub Actions-based CI workflow
• Add PHP-CS-Fixer build step to GitHub Actions-based CI workflow

Export arrays using short array syntax

Pretty much nobody uses array() form anymore. Since PHP 5.4, everyone uses short syntax, which looks like []. This is not only more readable, but also easier for copying from exporter into the code base. Would you consider changing the format you are using?

Quoted next to / vs Binary String

request for comments

I make use of the exporter library via Phpunit.

When I'm looking for expected output and this fails and the output contains characters from the C0 / C1 range (control characters), the string is hex-dumped.

This is kinda cumbersome as it is not easily readable any longer. I can copy the hex-string (after beginning 0x) and convert it to a readable string then, e.g.:

$ xclip -o -selection cliboard | xxd -r -p | less

This works but needs extra manual labour.

In these cases I can also patch exporter by replacing in src/Exporter.php

                return 'Binary String: 0x' . \bin2hex($value);

with

                return 'Quoted String: "' . \addcslashes($value, "\0..\11!@\14..\37!@\177..\377") . '"';

which perfectly fit my needs. This is especially well fitting in my case as I have merely standard output with very little control characters (mainly flow control) of which some are fine to render (like \n) and some are fine to transpose (with the example code above in octal notation).

I'm filing this issue as I'd like to get some comments on this. My main aim here is readability by the user which I think the exporter is for but this is a broad topic and needs may vary across users.

Also I'm asking myself what a good strategy would be. For pure binary strings the octal representation might be more verbose than the hexits so the hex notation is still preferable for purely binary strings.

The routine could look for a NUL byte in the string and if that is the case have it like before as "Binary String: 0x....". This can be compared on how grep does decide whether a file is binary or not.

I normally only need from Unicode the part it shares in the UTF-8 variant with the US-ASCII character set, so UTF-8 encoding is not specifically addressed here but it might play a role for others, too.

Possible `array_keys` bug in PHP 5.3.3.

I haven't had the chance to look into this yet, but it seems PHP 5.3.3 may suffer from the same bug described here: facebook/hhvm#1667.

For reference: https://travis-ci.org/sebastianbergmann/exporter/jobs/18225891

Idea: Showing spl_object_id instead of spl_object_hash in exporter output for objects?

The latest release of this repo supports php >=8.0 - older releases had to support php 7.1 and below. In a future release of the repo, would it make sense to use spl_object_id from php 7.2 instead?

It seems easier to me to distinguish small decimal numbers than 32-character hashes when reading an object.

I could work on an implementation and updating tests if you are interested in doing that and would prefer that for v5

---

Existing behavior:

stdClass Object &0000000003a66dcc0000000025e723e2 (
    'self' => stdClass Object &0000000003a66dcc0000000025e723e2
)

Proposed: &id or #id (like var_dump)

stdClass Object &5 (
    'self' => stdClass Object &5
)

Multibyte strings are not being detected

When working on #19 I noticed that the multibyte strings are not being properly detected but are being treated as regular strings.
The test that verifies multibyte strings:

public function provideNonBinaryMultibyteStrings()
    {
        return array(
            array(implode('', array_map('chr', range(0x09, 0x0d))), 5),
            array(implode('', array_map('chr', range(0x20, 0x7f))), 96),
            array(implode('', array_map('chr', range(0x80, 0xff))), 128),
        );
    }


    /**
     * @dataProvider provideNonBinaryMultibyteStrings
     */
    public function testNonBinaryStringExport($value, $expectedLength)
    {
        $this->assertRegExp(
            "~'.{{$expectedLength}}'\$~s",
            $this->exporter->export($value)
        );
    }

The code that checks for multibyte stirngs but is not detecting them:

            // Match for most non printable chars somewhat taking multibyte chars into account
            if (preg_match("/[^\x09-\x0d\x1b\x20-\xff]/", $value)) {
                return 'Binary String: 0x' . bin2hex($value);
            }

When the test runs, the code inside the previous conditional block is never executed.
This blocks: #19

README is Incorrect about Implementation

print new Exporter(46);

// 4.0
print new Exporter(4.0);

// 'hello, world!'
print new Exporter('hello, world!');

// false
print new Exporter(false);

// NAN
print new Exporter(acos(8));

// -INF
print new Exporter(log(0));

// null
print new Exporter(null);

None of these work, Exporter doesn't even have a constructor let alone the magic __toString.

Tests run against PHPUnit's vendor/sebastian/exporter/, not the local tree

Zend, with local modification that makes it so they shouldn't pass:

~/local/exporter] git diff
diff --git a/src/Exporter.php b/src/Exporter.php
index 6897e00..81ffd02 100644
--- a/src/Exporter.php
+++ b/src/Exporter.php
@@ -80,7 +80,7 @@ class Exporter
      * @return string
      */
     public function export($value, $indentation = 0)
-    {
+    {return 'nope';
         return $this->recursiveExport($value, $indentation);
     }
~/local/exporter] ~/opt/php-5.5.7/bin/php ../phpunit/phpunit --config phpunit.xml.dist
PHPUnit 3.9-gbb6e5d1 by Sebastian Bergmann.

Configuration read from /data/users/fredemmott/exporter/phpunit.xml.dist

The Xdebug extension is not loaded. No code coverage will be generated.

.................................

Time: 71 ms, Memory: 3.00Mb

OK (33 tests, 33 assertions

Under HHVM, it fatals so you get the backtrace:

infinite recursion detected
    #0 array_keys(), called at [/data/users/fredemmott/phpunit/vendor/sebastian/exporter/src/Context.php:167]
    #1 SebastianBergmann\Exporter\Context->containsArray(), called at [/data/users/fredemmott/phpunit/vendor/sebastian/exporter/src/Context.php:114]
    #2 SebastianBergmann\Exporter\Context->contains(), called at [/data/users/fredemmott/phpunit/vendor/sebastian/exporter/src/Exporter.php:140]
    #3 SebastianBergmann\Exporter\Exporter->recursiveExport(), called at [/data/users/fredemmott/phpunit/vendor/sebastian/exporter/src/Exporter.php:154]
    #4 SebastianBergmann\Exporter\Exporter->recursiveExport(), called at [/data/users/fredemmott/phpunit/vendor/sebastian/exporter/src/Exporter.php:84]
    #5 SebastianBergmann\Exporter\Exporter->export(), called at [/data/users/fredemmott/exporter/tests/ExporterTest.php:284]

Blacklisting of object details for some classes/interfaces

Currently, Prophecy contains a (outdated) copy of the exporter, altered to avoid dumping the internals of Prophecy objects, to make the export much more readable.
It would be great to support such feature in this library directly, allowing Prophecy to use it instead of copying it (making maintenance much easier). See phpspec/prophecy#296 (comment) for the discussion about it.

See https://github.com/phpspec/prophecy/blob/5c324f4951aca87a2de61b7903b75126516b6386/src/Prophecy/Util/ExportUtil.php#L184 for the current implementation.