diff --git a/README.md b/README.md index 5b599d2..44c5d15 100644 --- a/README.md +++ b/README.md @@ -8,14 +8,14 @@ better understanding what is going on under the hood. Laravel Profiler is design ### How does it work? -Laravel Profiler delivers data about Laravel framework execution: +Profiler delivers data about Laravel framework execution: - 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) - when tests are run (PHPUnit, Laravel Dusk) - on any other action that terminates Laravel framework. -Laravel Profiler is divided into 3 parts: +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. @@ -43,31 +43,30 @@ Data tracked, collected and delivered to Profiler Client are: - response (web) / output (console) - application (Laravel status, config, loaded service providers, container bindings, framework paths) -Trackers start framework tracking on service providers booting and finish on application terminating. - -Laravel Profiler and its trackers do their work after request / artisan command is finished. +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: Profiler Package installation +### Step 1: Install Profiler Package Requirements: PHP 7.1+ and Laravel 5.2+ It is recommended to install Profiler Package only for development -``` +```shell 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 use config/app.php because that will add Laravel Profiler -for every environment. Instead of that open AppServiceProvider class -and add Laravel Profiler service provider in register method: +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: -``` +```php // app/Providers/AppServiceProvider.php public function register() @@ -77,55 +76,87 @@ public function register() } } ``` + ### Step 2: Publish configuration file Run command -``` + +```shell php artisan vendor:publish --provider="JKocik\Laravel\Profiler\ServiceProvider" ``` -... and check config/profiler.php file for Laravel Profiler settings. -Uncomment trackers you would like to use. +... and check config/profiler.php file for Profiler settings. -### Step 3: Profiler Client and Profiler Server installation +### Step 3: Install Profiler Server and Profiler Client -It is recommended to install Profiler Client and Profiler Server only for development +It is recommended to install Profiler Server and Profiler Client only for development -``` +```shell npm install laravel-profiler-client --save-dev ``` -... then add new scripts to your package.json file +### 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 commands + +```shell +php artisan profiler:server +``` + +and + +```shell +php artisan profiler:client ``` + +After that your browser should have new tab opened with Profiler Client connected to Profiler Server. + +### Step 5: Verify installation + +Run command + +```shell +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 + +```json "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/", + "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 -``` +```shell npm run ps ``` ... and Profiler Client -``` +```shell npm run pc ``` -Open new tab in you browser according to Profiler Client instructions given in console. +b) If you don't want to open new browser tab every time you run Profiler Client command use manual option -### Step 4: Configuration +```shell +php artisan profiler:client -m +``` -You should be able to use Laravel Profiler without any other configuration. If you need to change -ports for HTTP and WebSockets protocols you can do it in profiler.php file, in your npm scripts -and using Laravel Client GUI (top right plugin icon). +c) If default ports used by Profiler are taken on your machine configure them in config/profiler.php file. ### Done! @@ -138,7 +169,7 @@ You are ready to use Laravel Profiler. Enjoy! Profiler delivers basic performance metrics including peak of memory usage and Laravel execution time. You can extend metrics by using Profiler helper functions: -``` +```php profiler_start('my time metric name'); // my code to track execution time @@ -146,17 +177,19 @@ profiler_start('my time metric name'); profiler_finish('my time metric name'); ``` -Then check results in Profiler Client (Performance > Custom tab). +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 usage from your code -before moving your code to production or any environment without Laravel Profiler installed. +_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: -``` +```php public function testBasicTest() { $response = $this->get('/'); @@ -167,7 +200,7 @@ public function testBasicTest() First test will terminate application and Profiler will work as expected. However second test -``` +```php public function testBasicTest() { $this->assertTrue(true); @@ -177,7 +210,7 @@ public function testBasicTest() ... will not provide any data because this time application is not terminated. You can force Profiler to work by adding terminate method: -``` +```php public function testBasicTest() { $this->assertTrue(true); @@ -186,8 +219,8 @@ public function testBasicTest() } ``` -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. +_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