Telescope for Laravel 5.0

laravel/telescope requires Laravel 5.7.7 and PHP 7.1. This gives a Laravel 5.0 application the same thing: requests, queries, queue jobs, artisan commands, exceptions, logs, cache and mail, each grouped into the batch that produced it — plus an Insights page that names your N+1 queries and the statements burning the most time.

No npm, no build step, no Vue. The dashboard is plain Blade.

🇻🇳 Bản tiếng Việt

Why this exists

Telescope cannot be made to run on 5.0 by loosening version constraints. It is built on APIs that simply did not exist yet:

The database schema (telescope_entries, telescope_entries_tags) and the core concepts — IncomingEntry, watchers, an entries repository, batch / tag / family hash — follow the original, so what you learn here still applies when you eventually upgrade.

Requirements

• PHP 5.4 or newer
• Laravel 5.0.x
• A database connection (MySQL, PostgreSQL, SQLite — anything the query builder supports)

Verified against Laravel 5.0.14 on PHP 7.0. Laravel 5.1 to 5.6 are untested; several hooks still exist there, so it may well work, but nothing is promised.

Installation

composer require hunglv-fs/laravel5-telescope

Register the service provider in config/app.php:

'providers' => [
    // ...
    'HungLv\Telescope\TelescopeServiceProvider',
],

Publish the config file and the migration, then migrate:

php artisan vendor:publish --provider="HungLv\Telescope\TelescopeServiceProvider"
php artisan migrate

Open /telescope.

Drop the package somewhere such as packages/telescope and require its bundled autoloader from bootstrap/autoload.php, right after Composer's:

require __DIR__.'/../packages/telescope/autoload.php';

Then copy config/telescope.php and the migration into your application by hand.

What gets recorded

Everything a request, command or job does shares one batch, so opening any entry shows the whole timeline around it.

Debugging queue jobs

Each job processed by the worker becomes its own batch: the job entry plus every query, log line and cache call it made. Open a job under /telescope/jobs to see how many queries it fired, how long it took, and which statements repeated.

The job must run through queue.worker — php artisan queue:work or queue:listen. With the sync driver the job simply runs inside the batch of whatever dispatched it, which is also what you want.

Insights

/telescope/insights answers the questions you actually open a profiler for:

• N+1 suspects — the same query shape executed several times inside one batch, with the file:line that issued it. in (?, ?) and in (?, ?, ?) are treated as one shape.
• Query hotspots — recent queries grouped by shape, ranked by total time spent.
• Slowest requests, jobs and commands.

Configuration

Everything lives in config/telescope.php.

Restricting access

The dashboard shows request payloads, sessions and SQL. By default it only opens in the environments listed under local_environments. To allow specific people elsewhere, register a callback in a service provider's boot():

\HungLv\Telescope\Telescope::auth(function ($request) {
    return in_array($request->user()->email, ['you@example.com']);
});

You can also drop entries before they are stored:

\HungLv\Telescope\Telescope::filter(function ($entry) {
    return $entry->type !== 'query' || $entry->hasTag('slow');
});

And record a handled exception yourself:

try {
    $this->import($row);
} catch (\Exception $e) {
    \HungLv\Telescope\Telescope::catchException($e, ['import', 'row:'.$row->id]);
}

Pruning

php artisan telescope:prune --hours=48   # put this on cron
php artisan telescope:clear              # delete everything

Laravel 5.0 quirks worth knowing

• Exceptions are recorded once. 5.0 binds Psr\Log\LoggerInterface straight to $app['log']->getMonolog(), so Handler::report() bypasses Illuminate\Log\Writer and never fires illuminate.log. That is why the exception watcher decorates the handler binding instead of listening to the log event.
• The storage connection is pinned at boot. migrate --database=other calls setDefaultConnection(), which rewrites database.default globally; resolving it lazily would silently send Telescope's own inserts to the wrong connection.
• Closure jobs are broken on PHP 7 in Laravel 5.0 itself (SuperClosure 1.x pulls in a php-parser release with a class named String, reserved since PHP 7). Use 'App\Foo@handle' or job objects.

Known limitations

• No live updates: the dashboard is a static Blade page, refresh to see new entries.
• No Redis, model, view or HTTP-client watchers — 5.0 emits no events for them.
• Artisan exit codes are not available (5.0 has no CommandFinished); a command is reported as failed on a fatal error, and tagged exception when one was reported.
• No telescope_monitoring (the "monitored tags" feature of the original).

Tests

Both run standalone, no application required:

php tests/smoke.php   # recording pipeline: batching, tags, N+1 detection, caps, backtrace, row shape
composer install && php tests/views.php   # compiles every view with the real Laravel 5.0 Blade compiler

Credits

An independent implementation for Laravel 5.0, following the schema and watcher architecture of laravel/telescope by Taylor Otwell. Not affiliated with or endorsed by Laravel.

License

MIT. See LICENSE.