diff --git a/README.md b/README.md index 08319df..29f65bf 100644 --- a/README.md +++ b/README.md @@ -25,19 +25,19 @@ composer require --dev sebastian/exporter Exporting: ```php - '' - 'string' => '' - 'code' => 0 - 'file' => '/home/sebastianbergmann/test.php' - 'line' => 34 - 'previous' => null +Exception Object #4 ( + 'message' => '', + 'string' => '', + 'code' => 0, + 'file' => '/home/sebastianbergmann/test.php', + 'line' => 34, + 'previous' => null, ) */ @@ -49,7 +49,7 @@ print $exporter->export(new Exception); Exporting simple types: ```php -export(chr(0) . chr(1) . chr(2) . chr(3) . chr(4) . chr(5)); Exporting complex types: ```php - Array &1 ( - 0 => 1 - 1 => 2 - 2 => 3 - ) - 1 => Array &2 ( - 0 => '' - 1 => 0 - 2 => false - ) -) +Array &0 [ + 0 => Array &1 [ + 0 => 1, + 1 => 2, + 2 => 3, + ], + 1 => Array &2 [ + 0 => '', + 1 => 0, + 2 => false, + ], +] */ -print $exporter->export(array(array(1,2,3), array("",0,FALSE))); +print $exporter->export([[1, 2, 3], ['', 0, false]]); /* -Array &0 ( - 'self' => Array &1 ( - 'self' => Array &1 - ) -) +Array &0 [ + 'self' => Array &1 [ + 'self' => Array &1, + ], +] */ -$array = array(); +$array = []; $array['self'] = &$array; + print $exporter->export($array); /* -stdClass Object &0000000003a66dcc0000000025e723e2 ( - 'self' => stdClass Object &0000000003a66dcc0000000025e723e2 +stdClass Object #4 ( + 'self' => stdClass Object #4, ) */ -$obj = new stdClass(); +$obj = new stdClass; $obj->self = $obj; + print $exporter->export($obj); ``` Compact exports: ```php -shortenedExport(array()); +// [] +print $exporter->shortenedExport([]); -// Array (...) -print $exporter->shortenedExport(array(1,2,3,4,5)); +// [...] +print $exporter->shortenedExport([1, 2, 3, 4, 5]); // stdClass Object () print $exporter->shortenedExport(new stdClass); @@ -150,7 +152,7 @@ print $exporter->shortenedExport(new stdClass); // Exception Object (...) print $exporter->shortenedExport(new Exception); -// this\nis\na\nsuper\nlong\nstring\nt...\nspace +// 'this\nis\na\nsuper\nlong\nstr...nspace' print $exporter->shortenedExport( <<amount(), $object->currency()); + } +} +``` + +Object exporters are registered by passing an `ObjectExporterChain` to `Exporter`'s constructor. They are consulted, in the order in which they are composed into the chain, before the default representation of an object is used. The first object exporter whose `handles()` method returns `true` is asked for the representation: + +```php +export(new Money(1999, 'EUR')); + +/* +stdClass Object #6 ( + 'net' => Money (1999 EUR), + 'gross' => Money (2379 EUR), +) +*/ + +$price = new stdClass; +$price->net = new Money(1999, 'EUR'); +$price->gross = new Money(2379, 'EUR'); + +print $exporter->export($price); +``` + +Enums are objects and are therefore passed to the object exporters as well. When no object exporter handles an object, the default representation is used for it. + +### Repeated Occurrences + +When the same object occurs more than once, the default representation is only used for the first occurrence; subsequent occurrences are replaced with a reference to the object: + +```php +/* +Array &0 [ + 0 => Money Object #8 ( + 'amount' => 1999, + 'currency' => 'EUR', + ), + 1 => Money Object #8, +] +*/ + +$money = new Money(1999, 'EUR'); + +print (new Exporter)->export([$money, $money]); +``` + +An object exporter is responsible for the entire representation of the object it handles. Every occurrence of such an object is therefore exported by it: + +```php +/* +Array &0 [ + 0 => Money (1999 EUR), + 1 => Money (1999 EUR), +] +*/ + +print $exporter->export([$money, $money]); +``` + +The exception is an object that is (indirectly) nested in itself: it cannot be exported this way without recursing infinitely and is replaced with a reference to the object. + +### Exporting Nested Values + +An object exporter may use the `Exporter` it is given to export values that are nested in the object it handles. The `ExportContext` it is given must be passed on when it does. Otherwise, the export of these nested values starts over with an empty context and, for instance, assigns references to arrays that are already in use elsewhere in the same export: + +```php +export($object->items(), $indentation, $context); + } +} +``` + +```php +/* +Array &0 [ + 'basket' => Basket Array &1 [ + 0 => Money (1999 EUR), + ], +] +*/ + +$exporter = new Exporter( + objectExporter: new ObjectExporterChain([new BasketExporter, new MoneyExporter]), +); + +print $exporter->export(['basket' => new Basket([new Money(1999, 'EUR')])]); +``` + +Object exporters are not consulted by `Exporter::shortenedExport()` and `Exporter::shortenedRecursiveExport()`, which deliberately elide the contents of objects.