feat: add support for laravel-telescope

lotyp · lotyp · commit fb6c8cc14ead · 2024-03-20T01:51:37.000+02:00
diff --git a/composer.json b/composer.json
@@ -47,7 +47,8 @@
         "phpunit/phpunit": "^10.5",
         "roave/security-advisories": "dev-latest",
         "wayofdev/cs-fixer-config": "^1.2",
-        "beberlei/assert": "^3.3"
+        "beberlei/assert": "^3.3",
+        "laravel/telescope": "^5.0"
     },
     "autoload": {
         "psr-4": {
diff --git a/composer.lock b/composer.lock
diff --git a/config/cycle.php b/config/cycle.php
@@ -104,11 +104,27 @@
             /*
              * Setup sqlite database in-memory for testing purposes
              */
-            'sqlite' => new Config\SQLiteDriverConfig(
+            'memory' => new Config\SQLiteDriverConfig(
                 connection: new Config\SQLite\MemoryConnectionConfig(),
                 queryCache: true
             ),
 
+            'sqlite' => new Config\SQLiteDriverConfig(
+                connection: new Config\SQLite\FileConnectionConfig(
+                    database: env('DB_DATABASE', database_path('database.sqlite'))
+                ),
+                driver: Driver\SQLite\SQLiteDriver::class,
+                reconnect: true,
+                timezone: 'UTC',
+                queryCache: true,
+                readonlySchema: false,
+                readonly: false,
+                options: [
+                    'logInterpolatedQueries' => env('DB_USE_TELESCOPE_LOGGER', false),
+                    'logQueryParameters' => env('DB_USE_TELESCOPE_LOGGER', false),
+                ],
+            ),
+
             'pgsql' => new Config\PostgresDriverConfig(
                 connection: new Config\Postgres\TcpConnectionConfig(
                     database: env('DB_DATABASE', 'wod'),
@@ -121,7 +137,13 @@
                 driver: Driver\Postgres\PostgresDriver::class,
                 reconnect: true,
                 timezone: 'UTC',
-                queryCache: true
+                queryCache: true,
+                readonlySchema: false,
+                readonly: false,
+                options: [
+                    'logInterpolatedQueries' => env('DB_USE_TELESCOPE_LOGGER', false),
+                    'logQueryParameters' => env('DB_USE_TELESCOPE_LOGGER', false),
+                ],
             ),
 
             'mysql' => new Config\MySQLDriverConfig(
@@ -136,6 +158,12 @@
                 reconnect: true,
                 timezone: 'UTC',
                 queryCache: true,
+                readonlySchema: false,
+                readonly: false,
+                options: [
+                    'logInterpolatedQueries' => env('DB_USE_TELESCOPE_LOGGER', false),
+                    'logQueryParameters' => env('DB_USE_TELESCOPE_LOGGER', false),
+                ],
             ),
 
             'sqlserver' => new Config\SQLServerDriverConfig(
@@ -150,6 +178,12 @@
                 reconnect: true,
                 timezone: 'UTC',
                 queryCache: true,
+                readonlySchema: false,
+                readonly: false,
+                options: [
+                    'logInterpolatedQueries' => env('DB_USE_TELESCOPE_LOGGER', false),
+                    'logQueryParameters' => env('DB_USE_TELESCOPE_LOGGER', false),
+                ],
             ),
         ],
 
@@ -159,7 +193,23 @@
          * Use any of channels configured in your logging.php file
          */
         'logger' => [
+            /*
+             * If enabled, allows laravel/telescope to catch all queries
+             */
+            'use_telescope' => env('DB_USE_TELESCOPE_LOGGER', false),
+
+            /*
+             * Default logger channel to use with all databases
+             * Set to null to disable logging
+             * Use any of channels configured in your logging.php file
+             */
             'default' => env('DB_DEFAULT_LOGGER', null),
+
+            /*
+             * Logger channels for specific drivers
+             * Set to null to disable logging
+             * Use any of channels configured in your logging.php file
+             */
             'drivers' => [
                 'sqlite' => env('DB_DEFAULT_LOGGER', null),
                 'pgsql' => env('DB_DEFAULT_LOGGER', null),
diff --git a/docs/pages/getting-started/configuration.mdx b/docs/pages/getting-started/configuration.mdx
@@ -74,6 +74,7 @@ These variables offer further customization for CycleORM's operation within Lara
 export const extraEnv = [
     ["DB_DEFAULT_CONNECTION", "string", "default", "The default database connection."],
     ["DB_DEFAULT_LOGGER", "?string", "null", "Laravel logger channel, to log queries. Loggers can be added in `config/logging.php`"],
+    ["DB_USE_TELESCOPE_LOGGER", "boolean", "false", "When enabled, `QueryExecuted` event will be fired through `TelescopeLogger` class."],
     ["DB_MIGRATIONS_TABLE", "string", "cycle_migrations", "The table name for the migrations."],
     ["CYCLE_TOKENIZER_CACHE_TARGETS", "boolean", "true", "Determines whether to cache located classes utilizing annotations."],
     ["CYCLE_TOKENIZER_LOAD_CLASSES", "boolean", "true", "Controls whether files of type `class` should be loaded."],
diff --git a/docs/pages/services/_meta.json b/docs/pages/services/_meta.json
@@ -0,0 +1,7 @@
+{
+    "factories": "Factories",
+    "seeders": "Seeders",
+    "testing": "Testing",
+    "validation": "Validation",
+    "laravel-telescope": "Laravel Telescope"
+}
diff --git a/docs/pages/services/laravel-telescope.mdx b/docs/pages/services/laravel-telescope.mdx
@@ -0,0 +1,87 @@
+import ExternalLink from "../../components/external-link";
+import Image from 'next/image'
+
+# Laravel Telescope
+
+## 🗒️ Introduction
+
+<ExternalLink href="https://laravel.com/docs/11.x/telescope">Laravel Telescope</ExternalLink> is an elegant debug assistant for the Laravel framework. Telescope provides insight into the requests coming into your application, exceptions, log entries, database queries, queued jobs, mail, notifications, cache operations, scheduled tasks, variable dumps and more. Telescope makes a wonderful companion to your local Laravel development environment.
+
+This adapter package provides you with abillity to also log and debug your Cycle ORM queries in Laravel Telescope.
+
+## 📀 Installation
+
+<div className="steps-container">
+
+### Step 1: Install Telescope
+
+Install, telescope as usual, via Composer package manager:
+
+```bash
+composer require laravel/telescope
+```
+
+### Step 2: Publish Telescope Assets and run Migrations
+
+After installing Telescope, publish its assets and migrations using the telescope:install Artisan command. After installing Telescope, you should also run the migrate command in order to create the tables needed to store Telescope's data:
+
+```bash
+php artisan telescope:install
+
+php artisan migrate
+```
+
+### Step 3: Add the CycleORM Query Watcher
+
+Next, edit your `config/telescope.php` configuration file and add the following lines to the `watchers` array, right after the default`Watchers\QueryWatcher::class` line:
+
+```php {13-18} filename="config/telescope.php"
+return [
+    // ...
+
+    'watchers' => [
+        // ...
+        Watchers\QueryWatcher::class => [
+            'enabled' => true,
+            'ignore_packages' => true,
+            'ignore_paths' => [],
+            'slow' => 100,
+        ],
+
+        WayOfDev\Cycle\Bridge\Telescope\Watchers\QueryWatcher::class => [
+            'enabled' => true,
+            'ignore_packages' => true,
+            'ignore_paths' => [],
+            'slow' => 100,
+        ],
+    ],
+    // ...
+];
+```
+
+### Step 4: Add .env Configuration
+
+Add the following configuration to your `.env` file:
+
+```dotenv filename=".env"
+...
+
+DB_USE_TELESCOPE_LOGGER=true
+
+...
+```
+
+### Step 5: Access Laravel Telescope
+
+Finally, you may access the Telescope dashboard via the `/telescope` route. Of course, don't forget to start your Laravel application:
+
+```bash
+php artisan serve
+```
+</div>
+
+## 🎉 Final Result
+
+Now, you can access the Laravel Telescope dashboard and see all the CycleORM queries executed by your application.
+
+<Image src="/images/telescope-min.png" alt="Hello" width={1600} height={1483} />
diff --git a/docs/public/images/telescope-min.png b/docs/public/images/telescope-min.png
diff --git a/src/Bridge/Laravel/LoggerFactory.php b/src/Bridge/Laravel/LoggerFactory.php
@@ -11,6 +11,8 @@
 use Illuminate\Log\LogManager;
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
+use WayOfDev\Cycle\Bridge\Telescope\TelescopeLogger;
+use WayOfDev\Cycle\Support\Arr;
 
 final class LoggerFactory implements LoggerFactoryInterface
 {
@@ -39,6 +41,12 @@ public function getLogger(?DriverInterface $driver = null): LoggerInterface
             }
         }
 
-        return $this->manager->channel($channel);
+        $logger = $this->manager->channel($channel);
+
+        if (Arr::get($this->config, 'use_telescope') === true) {
+            return new TelescopeLogger($logger);
+        }
+
+        return $logger;
     }
 }
diff --git a/src/Bridge/Telescope/Events/Database/QueryExecuted.php b/src/Bridge/Telescope/Events/Database/QueryExecuted.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WayOfDev\Cycle\Bridge\Telescope\Events\Database;
+
+/**
+ * @see https://github.com/laravel/framework/blob/11.x/src/Illuminate/Database/Connection.php
+ * @see https://github.com/laravel/framework/blob/11.x/src/Illuminate/Database/Events/QueryExecuted.php
+ */
+final class QueryExecuted
+{
+    public function __construct(public string $sql, public array $bindings, public ?float $time, public ?string $driver = null)
+    {
+        $this->time = $time * 1000;
+        $this->driver = null !== $driver ? 'CycleORM/' . $driver : 'CycleORM';
+    }
+}
diff --git a/src/Bridge/Telescope/TelescopeLogger.php b/src/Bridge/Telescope/TelescopeLogger.php
@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WayOfDev\Cycle\Bridge\Telescope;
+
+use Psr\Log\LoggerInterface;
+use Stringable;
+use WayOfDev\Cycle\Bridge\Telescope\Events\Database\QueryExecuted;
+
+class TelescopeLogger implements LoggerInterface
+{
+    private LoggerInterface $parentLogger;
+
+    public function __construct($parentLogger)
+    {
+        $this->parentLogger = $parentLogger;
+    }
+
+    public function log($level, $message, array $context = []): void
+    {
+        $this->parentLogger->log($level, $message, $context);
+
+        if ('info' === $level && isset($context['elapsed'])) {
+            event(
+                new QueryExecuted(
+                    sql: $message,
+                    bindings: $context['parameters'] ?? [],
+                    time: $context['elapsed'],
+                    driver: $context['driver'] ?? null
+                )
+            );
+        }
+    }
+
+    public function info(Stringable|string $message, array $context = []): void
+    {
+        $this->log('info', $message, $context);
+    }
+
+    public function error(Stringable|string $message, array $context = []): void
+    {
+        $this->log('error', $message, $context);
+    }
+
+    public function alert(Stringable|string $message, array $context = []): void
+    {
+        $this->log('alert', $message, $context);
+    }
+
+    public function emergency(Stringable|string $message, array $context = []): void
+    {
+        $this->log('emergency', $message, $context);
+    }
+
+    public function critical(Stringable|string $message, array $context = []): void
+    {
+        $this->log('emergency', $message, $context);
+    }
+
+    public function warning(Stringable|string $message, array $context = []): void
+    {
+        $this->log('warning', $message, $context);
+    }
+
+    public function notice(Stringable|string $message, array $context = []): void
+    {
+        $this->log('notice', $message, $context);
+    }
+
+    public function debug(Stringable|string $message, array $context = []): void
+    {
+        $this->log('debug', $message, $context);
+    }
+}
diff --git a/src/Bridge/Telescope/Watchers/QueryWatcher.php b/src/Bridge/Telescope/Watchers/QueryWatcher.php
@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WayOfDev\Cycle\Bridge\Telescope\Watchers;
+
+use Cycle\Database\Query\Interpolator;
+use Laravel\Telescope\IncomingEntry;
+use Laravel\Telescope\Telescope;
+use Laravel\Telescope\Watchers\FetchesStackTrace;
+use Laravel\Telescope\Watchers\Watcher;
+use WayOfDev\Cycle\Bridge\Telescope\Events\Database\QueryExecuted;
+
+use function md5;
+use function number_format;
+
+final class QueryWatcher extends Watcher
+{
+    use FetchesStackTrace;
+
+    public function register($app): void
+    {
+        $app['events']->listen(QueryExecuted::class, [$this, 'recordQuery']);
+    }
+
+    public function recordQuery(QueryExecuted $event): void
+    {
+        if (! Telescope::isRecording()) {
+            return;
+        }
+
+        $time = $event->time;
+        $caller = $this->getCallerFromStackTrace();
+
+        if (null !== $caller) {
+            Telescope::recordQuery(IncomingEntry::make([
+                'connection' => $event->driver,
+                'bindings' => $event->bindings,
+                'sql' => Interpolator::interpolate($event->sql, $event->bindings),
+                'time' => number_format($time, 2, '.', ''),
+                'slow' => isset($this->options['slow']) && $time >= $this->options['slow'],
+                'file' => $caller['file'],
+                'line' => $caller['line'],
+                'hash' => $this->familyHash($event),
+            ])->tags($this->tags($event)));
+        }
+    }
+
+    public function familyHash(QueryExecuted $event): string
+    {
+        return md5($event->sql);
+    }
+
+    protected function tags(QueryExecuted $event): array
+    {
+        return isset($this->options['slow']) && $event->time >= $this->options['slow'] ? ['slow'] : [];
+    }
+}
diff --git a/tests/src/Bridge/Laravel/LoggerFactoryTest.php b/tests/src/Bridge/Laravel/LoggerFactoryTest.php

Original file line number	Diff line number	Diff line change
`@@ -11,6 +11,8 @@`
`11`	`11`	`use Illuminate\Log\LogManager;`
`12`	`12`	`use Psr\Log\LoggerInterface;`
`13`	`13`	`use Psr\Log\NullLogger;`
	`14`	`+use WayOfDev\Cycle\Bridge\Telescope\TelescopeLogger;`
	`15`	`+use WayOfDev\Cycle\Support\Arr;`
`14`	`16`
`15`	`17`	`final class LoggerFactory implements LoggerFactoryInterface`
`16`	`18`	`{`
`@@ -39,6 +41,12 @@ public function getLogger(?DriverInterface $driver = null): LoggerInterface`
`39`	`41`	`}`
`40`	`42`	`}`
`41`	`43`
`42`		`- return $this->manager->channel($channel);`
	`44`	`+ $logger = $this->manager->channel($channel);`
	`45`	`+`
	`46`	`+ if (Arr::get($this->config, 'use_telescope') === true) {`
	`47`	`+ return new TelescopeLogger($logger);`
	`48`	`+ }`
	`49`	`+`
	`50`	`+ return $logger;`
`43`	`51`	`}`
`44`	`52`	`}`