Merge pull request #843 from spatie/add-expand-payload

Add expand payload

docs/usage/framework-agnostic-php.md

@@ -21,6 +21,22 @@ ray($anObject);
 ray('as', 'many' , 'arguments', 'as', 'you', 'like');
 ```
 
+### Expanding arrays and objects
+
+When sending an array or object to Ray, it will be displayed in a collapsed state.
+
+To open up a node, you can use the `expand` method. 
+
+```php
+ray($arrayOrObject)->expand(); // will open up the first level of nodes
+ray($arrayOrObject)->expand(3); // will open up the first three levels of nodes
+ray($arrayOrObject)->expand('myKey'); // will open the node with key named `myKey`
+ray($arrayOrObject)->expand('myKey', 'anotherKey'); // open up all nodes with the given names
+
+// you can use dot notation to expand deeper nodes
+ray($arrayOrObject)->expand('myKey.nestedKey');
+```
+
 ### Using colors
 
 You can colorize things you sent to ray by using one of the color functions.

src/Payloads/ExpandPayload.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace Spatie\Ray\Payloads;
+
+class ExpandPayload extends Payload
+{
+    /** @var array */
+    protected $keys = [];
+
+    /** @var int|null */
+    protected $level = null;
+
+    public function __construct(array $values = [])
+    {
+        foreach($values as $value) {
+            if (is_numeric($value)) {
+                $this->level = max($this->level, $value);
+
+                continue;
+            }
+
+            $this->keys[] = $value;
+        }
+    }
+
+    public function getType(): string
+    {
+        return 'expand';
+    }
+
+    public function getContent(): array
+    {
+        return [
+            'keys' => $this->keys,
+            'level' => $this->level,
+        ];
+    }
+}

src/Ray.php

@@ -24,6 +24,7 @@
 use Spatie\Ray\Payloads\CustomPayload;
 use Spatie\Ray\Payloads\DecodedJsonPayload;
 use Spatie\Ray\Payloads\ExceptionPayload;
+use Spatie\Ray\Payloads\ExpandPayload;
 use Spatie\Ray\Payloads\FileContentsPayload;
 use Spatie\Ray\Payloads\HideAppPayload;
 use Spatie\Ray\Payloads\HidePayload;
@@ -317,6 +318,17 @@ protected function measureClosure(Closure $closure): self
         return $this->sendRequest($payload);
     }
 
+    public function expand(...$levelOrKey): self
+    {
+        if (empty($levelOrKey)) {
+            $levelOrKey = [1];
+        }
+
+        $payload = new ExpandPayload($levelOrKey);
+
+        return $this->sendRequest($payload);
+    }
+
     public function stopTime(string $stopwatchName = ''): self
     {
         if ($stopwatchName === '') {

tests/RayTest.php

@@ -1140,3 +1140,29 @@ function (InvalidArgumentException $e, $ray) {
 
     expect($sentRequests[0]['payloads'][0]['content']['values'])->toBe(['this is the result of the private method']);
 });
+
+it('can send the expand payload', function (
+    ?array $expandArguments,
+    ?int $expectedLevel,
+    array $expectedKeys
+) {
+
+    $expandArguments === null
+        ? $this->ray->expand()
+        : $this->ray->expand(...$expandArguments);
+
+    $sentRequests = $this->client->sentRequests();
+
+    expect($sentRequests)->toHaveCount(1);
+
+    expect($sentRequests[0]['payloads'][0]['content']['level'])->toBe($expectedLevel);
+    expect($sentRequests[0]['payloads'][0]['content']['keys'])->toBe($expectedKeys);
+})->with([
+    [null, 1, []],
+    [[1], 1, []],
+    [[1,2,3], 3, []],
+    [['key'], null, ['key']],
+    [['key', 'anotherKey'], null, ['key', 'anotherKey']],
+    [['key', 'anotherKey', 2], 2, ['key', 'anotherKey']],
+    [['key', 'anotherKey', 2, 3], 3, ['key', 'anotherKey']],
+]);