Debug your Laravel Application efficiently with Laravel Telescope
Tags: webdev, php, laravel, telescope
Published: 2021-03-03 19:07:06

## 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](https://mailtrap.io/)
- Visualize dumped data without killing the page
- Debug caching issues
- View logs

And much more. Take a look at the [official documentation](https://laravel.com/docs/8.x/telescope) 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](https://laravel.com/docs/8.x/installation) 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.<br>
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-discover`array 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, [
            // taylor@laravel.com
        ]);
    });
}
```

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](https://laravel.com/docs/8.x/telescope#upgrading-telescope), you should always [review the changes](https://github.com/laravel/telescope/blob/master/UPGRADE.md) 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](https://laravel.com/docs/8.x/telescope).

---

## Resources

- [Official documentation](https://laravel.com/docs/8.x/telescope)
- [GitHub](https://github.com/laravel/telescope)