Debug your Laravel Application efficiently with Laravel Telescope

What does Telescope do?

Laravel Telescope is an official Laravel package that's meant to help you debug a Laravel app locally.

While its main use is for debugging in a local environment, it can also be used in production.

Use cases

• Inspect incoming requests
• Inspect database queries for optimization and look out for the dreaded N+1
• Preview mailables locally instead of actually sending them to a third party service like Mailtrap.io
• Visualize dumped data without killing the page
• Debug caching issues
• View logs

And much more. Take a look at the official documentation for more info.

---

Intro

First, we need an existing Laravel application.
For sake of brevity, I'm just going to provide a link to the documentation instead.

Telescope can be used both locally while developing and in production, but the steps are a little different for each use case.

---

Use Telescope locally and in production

The installation to use Telescope both locally and in production is the shortest one.

Be warned that running Telescope in production might impact your app's performance. Disabling the watchers you don't absolutely require is advised.

Installation

First, head to the terminal and add Telescope to the project:

composer require laravel/telescope

Once Telescope has been successfully added to the project, publish its assets using the Artisan command:

php artisan telescope:install

That's it! Telescope is now installed and is ready to go.

In production, the number of entries saved to the database can become huge very rapidly, depending on your site's traffic. That's why you should be pruning data regularly with a scheduled Artisan command.

You can find out more about this subject in the official Telescope documentation.

---

Use Telescope for local development only

Installing Telescope locally for development only is also possible if you don't need it in production.

While you won't have any data for your production app, this use case has the benefit of not causing any performance hit to your app.

Installation

As for the installation for use in production, let's head to the terminal and add Telescope to the project using Composer:

composer require laravel/telescope --dev

Then we can publish Telescope's assets using Artisan:

php artisan telescope:install

And finally run the migrations:

php artisan migrate

Register the service provider manually

Remove the Telescope service provider registration from the application's config/app.php configuration file:

'providers' => [
    /*
     * Application Service Providers...
     */
    // ...
    // Remove the line below
    App\Providers\TelescopeServiceProvider::class,
],

This is done so Laravel doesn't register Telescope when it registers its other service providers in production.

Register the Telescope service provider manually in the app's App\Providers\AppServiceProvider file:

/**
 * Register any application services.
 *
 * @return void
 */
public function register()
{
    if ($this->app->environment('local')) {
        $this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
        $this->app->register(TelescopeServiceProvider::class);
    }
}

That registers the TelescopeServiceProvider from the vendor directory and then the one that's configured for you app.

Finally, the Telescope package should not be auto-discovered by Laravel.

Add Telescope's package to the dont-discoverarray in the composer.json file to ignore it when running Composer install and update commands in production:

"extra": {
    "laravel": {
        "dont-discover": [
            "laravel/telescope"
        ]
    }
},

---

Dashboard & authorization

To access Telescope's dashboard, you can visit your-app.test/telescope.

By default, the dashboard is only accessible in a local environment.

For production environments though, you need to specify which users are allowed to access the dashboard as it is protected by an authorization gate.

You can authorize users in your app's TelescopeServiceProvider.php file:

/**
 * Register the Telescope gate.
 *
 * This gate determines who can access Telescope in non-local  environments.
 *
 * @return void
 */
protected function gate()
{
    Gate::define('viewTelescope', function ($user) {
        return in_array($user->email, [
            // [e-mail]
        ]);
    });
}

You don't need to specify any authorized user in a local environment as anyone is allowed, even unauthenticated.

---

Configuration

All of Telescope's configuration options can be found in its configuration file inside the app's config folder.

Be sure to review this file thoroughly to configure Telescope to your specific need.

While not in the config file itself, you can toggle Telescope's dark mode in your app's TelescopeServiceProvider.php file.

---

Upgrading Telescope

As stated in the official documentation, you should always review the changes when upgrading to a major version.

Re-publish Telescope's assets after upgrading:

php artisan telescope:publish

This process can also be automated by adding the last command into the post update scripts array in the composer.json file:

{
    "scripts": {
        "post-update-cmd": [
            "@php artisan telescope:publish --ansi"
        ]
    }
}

---

Diving deeper

This guide only covers installing and getting started with Laravel Telescope. There are a lot more subjects to cover like tags, watchers, etc.

Be sure to always review the official documentation.

---

Resources

• Official documentation
• GitHub