jkocik / laravel-profiler by jkocik

Laravel Profiler

The aim of this project is to track console and web Laravel framework execution and give developers better understanding what is going on under the hood. Laravel Profiler is designed for Laravel 5.2+.

How does it work?

Profiler delivers data about Laravel framework execution:

• when tests are run (PHPUnit, Laravel Dusk)
• when Laravel is executed via console (artisan)
• when Laravel is executed via browser request
• when Laravel is executed via web request not expecting HTML response (API)
• on any other action that terminates Laravel framework.

Profiler does not add any routes to your application and does not modify the content of the response.

Profiler is divided into 3 parts:

• Profiler Package - PHP package for Laravel (this repository)
• Profiler Client - Single Page Application to review data delivered by Profiler Package
• Profiler Server - bridge between Profiler Package and Profiler Client.

Profiler Client and Profiler Server both live in laravel-profiler-client repository

Data flow

Profiler Package tracks Laravel execution and sends collected data to Profiler Server using HTTP. Profiler Server passes data to Profiler Client using WebSockets.

Trackers

Data tracked, collected and delivered to Profiler Client are:

• auth
• route
• views
• events
• session
• exceptions
• server status
• database queries
• performance metrics
• request (web) / input (console)
• response (web) / output (console)
• application (Laravel status, config, loaded service providers, container bindings, framework paths)

Profiler and its trackers do their job after request / artisan command is finished. That keeps your framework execution time and peak of memory usage as close to real values (without Profiler impact) as possible.

Installation and configuration

Step 1: Install Profiler Package

Requirements: PHP 7.1+ and Laravel 5.2+

It is recommended to install Profiler Package only for development

composer require jkocik/laravel-profiler --dev

For Laravel 5.5+ you are fine and you can go to Step 2 of this installation process.

For Laravel 5.4 or lower add Service Provider to your application. Do not add it in config/app.php because that will add Profiler for all your environments. Instead of that open AppServiceProvider class and add Profiler Service Provider in register method:

// app/Providers/AppServiceProvider.php

public function register()
{
    if (! $this->app->environment('production')) {
        $this->app->register(\JKocik\Laravel\Profiler\ServiceProvider::class);
    }
}

Step 2: Publish configuration file

Run command

php artisan vendor:publish --provider="JKocik\Laravel\Profiler\ServiceProvider"

... and check config/profiler.php file for Profiler settings.

Step 3: Install Profiler Server and Profiler Client

It is recommended to install Profiler Server and Profiler Client only for development

npm install laravel-profiler-client --save-dev

Step 4: Run Profiler Server and Profiler Client

Windows users: If you have any issue with running Profiler Server or Profiler Client check Installation options / issues section below.

Run command

php artisan profiler:server

and

a) for your local machine

php artisan profiler:client

After that your browser should have new tab opened with Profiler Client connected to Profiler Server.

b) for Vagrant or any other machine different than local

php artisan profiler:client -m

... and open new browser tab according to instructions in console. Remember that you need to connect Profiler Client to Profiler Server yourself because by default Profiler Client uses localhost. You can do that in Profiler Client interface.

Step 5: Verify installation

Run command

php artisan profiler:status

... to check Profiler status and see first data of Laravel execution in Profiler Client.

Installation options / issues

a) If you have any issue with running Profiler Server or Profiler Client use npm scripts instead of artisan commands. Add new scripts to your package.json file

"scripts": {
    "profiler-server": "node node_modules/laravel-profiler-client/server/server.js http=8099 ws=1901",
    "profiler-client": "http-server node_modules/laravel-profiler-client/dist/ -o -s",
    "ps": "npm run profiler-server",
    "pc": "npm run profiler-client"    
}

... then run Profiler Server

npm run ps

... and Profiler Client

npm run pc

b) If you don't want to open new browser tab every time you run Profiler Client command use manual option

php artisan profiler:client -m

c) If default ports used by Profiler are taken on your machine configure them in config/profiler.php file.

Done!

You are ready to use Laravel Profiler. Enjoy!

Usage

Performance metrics

Profiler delivers basic performance metrics including peak of memory usage and Laravel execution time. You can extend metrics by using Profiler helper functions:

profiler_start('my time metric name');

// my code to track execution time

profiler_finish('my time metric name');

Then check results in Profiler Client (Performance > Custom tab). You should keep unique metric names otherwise duplicates will be skipped and reported as an error (in a way according to your exception handling settings in config/profiler.php file).

Important notice: remove Profiler helper functions from your code before moving to production or any environment without Profiler installed.

Laravel Profiler for testing environment

When testing Profiler will deliver the same data as for regular request / artisan command. However application should be terminated. Lets see two default tests Laravel is shipped with:

public function testBasicTest()
{
    $response = $this->get('/');

    $response->assertStatus(200);
}

First test will terminate application and Profiler will work as expected. However second test

public function testBasicTest()
{
    $this->assertTrue(true);
}

... will not provide any data because this time application is not terminated. You can force Profiler to work by adding terminate method:

public function testBasicTest()
{
    $this->assertTrue(true);
    
    $this->app->terminate();
}

Important notice related to testing environment: peak of memory usage can not be tracked for each test separately so is not shown in Profiler Client.

Using together with Laravel Debugbar

It is not recommended using Laravel Profiler and Laravel Debugbar together. Profiler will finish its work after Debugbar and Profiler report of framework execution time and peak of memory usage will be increased by Debugbar activity. Use Profiler or Debugbar one at a time.