feat: introduce better-fitting method names

Author: tpetry

README.md

@@ -10,7 +10,7 @@
 
 MySQL Query optimization with the `EXPLAIN` command is unnecessarily complicated: The output contains a lot of cryptic information that is incomprehensible or entirely misleading.
 
-This Larvel package collects many query metrics that will be sent to [mysqlexplain.com](https://mysqlexplain.com) and transformed to be much easier to understand.
+This Laravel package collects many query metrics that will be sent to [mysqlexplain.com](https://mysqlexplain.com) and transformed to be much easier to understand.
 
 ## Installation
 
@@ -26,26 +26,28 @@ composer require tpetry/laravel-mysql-explain
 
 Three new methods have been added to the query builder for very easy submission of query plans: 
 
-| Type                   | Action                                                              |
-|------------------------|---------------------------------------------------------------------|
-| `explainForHumans`     | returns URL to processed EXPLAIN output                             |
-| `dumpExplainForHumans` | dumps URL to processed EXPLAIN output and continue normal execution |
-| `ddExplainForHumans`   | dumps URL to processed EXPLAIN output and stops execution           |
-
+| Type                                      | Action                                                              |
+|-------------------------------------------|---------------------------------------------------------------------|
+| `visualExplain`                           | returns URL to processed EXPLAIN output                             |
+| `dumpVisualExplain`                       | dumps URL to processed EXPLAIN output and continue normal execution |
+| `ddVisualExplain`                         | dumps URL to processed EXPLAIN output and stops execution           |
+| `explainForHumans` ***(deprecated)***     | returns URL to processed EXPLAIN output                             |
+| `dumpExplainForHumans` ***(deprecated)*** | dumps URL to processed EXPLAIN output and continue normal execution |
+| `ddExplainForHumans` ***(deprecated)***   | dumps URL to processed EXPLAIN output and stops execution           |
 
 ```php
 // $url will be e.g. https://mysqlexplain.com/explain/01j2gcrbsjet9r8rav114vgfsy
 $url = Film::where('description', 'like', '%astronaut%')
-    ->explainForHumans();
+    ->visualExplain();
 
 // URL to EXPLAIN will be printed to screen
 $users = Film::where('description', 'like', '%astronaut%')
-    ->dumpExplainForHumans()
+    ->dumpVisualExplain()
     ->get();
 
 // URL to EXPLAIN will be printed to screen & execution is stopped
-$users = Film::where('description', 'like', '%astronaut%')
-    ->ddExplainForHumans();
+Film::where('description', 'like', '%astronaut%')
+    ->ddVisualExplain();
 ```
 
 ### Raw Queries

composer.json

@@ -1,6 +1,6 @@
 {
     "name": "tpetry/laravel-mysql-explain",
-    "description": "Get MySQL EXPLAIN plans that are understandable for humans",
+    "description": "Get Visual MySQL EXPLAIN for Laravel.",
     "keywords": [
         "laravel",
         "mysql",

src/Mixins/BuilderMixin.php

@@ -22,6 +22,16 @@ public function ddExplainForHumans(): Closure
         };
     }
 
+    public function ddVisualExplain(): Closure
+    {
+        /** @return never-returns */
+        return function () {
+            /** @var \Illuminate\Contracts\Database\Query\Builder $this */
+            $url = MysqlExplain::submitBuilder($this);
+            dd($url);
+        };
+    }
+
     public function dumpExplainForHumans(): Closure
     {
         return function () {
@@ -33,6 +43,17 @@ public function dumpExplainForHumans(): Closure
         };
     }
 
+    public function dumpVisualExplain(): Closure
+    {
+        return function () {
+            /** @var \Illuminate\Contracts\Database\Query\Builder $this */
+            $url = MysqlExplain::submitBuilder($this);
+            dump($url);
+
+            return $this;
+        };
+    }
+
     public function explainForHumans(): Closure
     {
         return function (): string {
@@ -42,4 +63,14 @@ public function explainForHumans(): Closure
             return $url;
         };
     }
+
+    public function visualExplain(): Closure
+    {
+        return function (): string {
+            /** @var \Illuminate\Contracts\Database\Query\Builder $this */
+            $url = MysqlExplain::submitBuilder($this);
+
+            return $url;
+        };
+    }
 }

tests/Mixins/EloquentBuilderTest.php

@@ -15,11 +15,21 @@ public function testDdExplainForHumans(): void
         $this->markTestSkipped('how to test dump() and not exit PHPUnit on exit() call?');
     }
 
+    public function testDdVisualExplain(): void
+    {
+        $this->markTestSkipped('how to test dump() and not exit PHPUnit on exit() call?');
+    }
+
     public function testDumpExplainForHumans(): void
     {
         $this->markTestSkipped('how to test dump()?');
     }
 
+    public function testDumpVisualExplain(): void
+    {
+        $this->markTestSkipped('how to test dump()?');
+    }
+
     public function testExplainForHumans(): void
     {
         $model = new class() extends Model {};
@@ -34,4 +44,19 @@ public function testExplainForHumans(): void
 
         $this->assertEquals('https://dummy-url-A5mhRHJXvC.local/I2aifhDBCO', $url);
     }
+
+    public function testVisualExplain(): void
+    {
+        $model = new class() extends Model {};
+        $builder = $model->newQuery();
+
+        MysqlExplain::shouldReceive('submitBuilder')
+            ->once()
+            ->with($builder)
+            ->andReturn('https://dummy-url-A5mhRHJXvC.local/I2aifhDBCO');
+
+        $url = $builder->visualExplain();
+
+        $this->assertEquals('https://dummy-url-A5mhRHJXvC.local/I2aifhDBCO', $url);
+    }
 }

tests/Mixins/QueryBuilderTest.php

@@ -15,11 +15,21 @@ public function testDdExplainForHumans(): void
         $this->markTestSkipped('how to test dump() and not exit PHPUnit on exit() call?');
     }
 
+    public function testDdVisualExplain(): void
+    {
+        $this->markTestSkipped('how to test dump() and not exit PHPUnit on exit() call?');
+    }
+
     public function testDumpExplainForHumans(): void
     {
         $this->markTestSkipped('how to test dump()?');
     }
 
+    public function testDumpVisualExplain(): void
+    {
+        $this->markTestSkipped('how to test dump()?');
+    }
+
     public function testExplainForHumans(): void
     {
         $builder = DB::table('test123');
@@ -32,4 +42,17 @@ public function testExplainForHumans(): void
 
         $this->assertEquals('https://dummy-url-f6V7VImZnz.local', $url);
     }
+
+    public function testVisualExplain(): void
+    {
+        $builder = DB::table('test123');
+        MysqlExplain::shouldReceive('submitBuilder')
+            ->once()
+            ->with($builder)
+            ->andReturn('https://dummy-url-f6V7VImZnz.local');
+
+        $url = $builder->visualExplain();
+
+        $this->assertEquals('https://dummy-url-f6V7VImZnz.local', $url);
+    }
 }