Skip to content

Latest commit

 

History

History
307 lines (234 loc) · 9.9 KB

README.md

File metadata and controls

307 lines (234 loc) · 9.9 KB
Raw

Laravel Inspector

At a Glance
Messages Exceptions
idd() - Dump and die on steroids idd() SQLs page
Laravel Inspector as the default Exception renderer Timers and Timeline
Redirection API/Ajax calls
Using Postman REST client app laravel_inspector=dump parameter
Available Collectors Information about
MessageCollector User's messages and dumps
ExceptionCollector Exceptions
DBCollector Queries, including execution time and parameters binding
TimersCollector Timers and time stamps
RoutesCollector Application routes
RequestCollector Current Request
ResponseCollector Current Response
SessionCollector Session variables
ServerCollector $_SERVER dump
More to come...

Installation

This package was tested under PHP 5.6, PHP 7, Laravel 5.2 and Laravel 5.3-Dev

Installing the package via composer:

composer require lsrur/inspector

Next, add InspectorServiceProvider to the providers array in config/app.php:

Lsrur\Inspector\InspectorServiceProvider::class,

And this Facade in the same configuration file:

'Inspector' => Lsrur\Inspector\Facade\Inspector::class,

For usage only during development and not during production, do not edit the config/app.php and add the following to your AppServiceProvider :

public function register()
{
  // ...
  if ($this->app->environment() == 'development') {
      $this->app->register(\Lsrur\Inspector\InspectorServiceProvider::class);
  }
  // ...
}

Configuration

In order to use Inspector as the default exceptions renderer, add the following line in the file app/Exceptions/Handler.php of your Laravel project:

public function render($request, Exception $exception)
{
    \Inspector::renderException($exception);	// <= THIS LINE
    return parent::render($request, $exception);
}

For usage only during development:

public function render($request, Exception $exception)
{
    if (\App::environment() == 'development')
    {
        \Lsrur\Inspector\Facade\Inspector::renderException($exception);
    }
    return parent::render($request, $exception);
}

Usage

Laravel inspector can be invoked using the Facade, the provided helper functions and a Blade directive:

//Using Facade
\Inspector::log(...);
\Inspector::info(...);

//Using the "inspector" helper function
inspector()->info(...);
inspector()->warning($myVar);

// "li" is an alias of "inspector"
li()->error(...);
li()->group('myGroup');

// "inspect" function makes an "Inspector::log($v)" for each passed argument
inspect($var1, $var2, $var3, ...);

// Dump and die using Laravel Inspector magic
idd();
idd($var1, $var2);

// Inside Blade
@li(cmd,param1,param2,...)

// samples
@li('log', 'My comment', $myVar)
@li(log, 'My comment', $myVar) //also works without command quotes
@li(group,"myGroup")
@li(endGroup)

Laravel inspector will only be active if the config variable app.debug is true.
Anyway, you can temporarily turn Inspector off (just for the current request) with:

li()->turnOff();

Messages

You can inspect objects and variables with the following methods, each of which has its own output format:

Method Description
log([string $description,] mixed $data) Outputs data with "log" format
info([string $description,] mixed $data) Outputs data with "info" format
error([string $description,] mixed $data) Outputs data with "error" format
warning([string $description,] mixed $data) Outputs data with "warning" format
success([string $description,] mixed $data) Outputs data with "success" format
table([string $description,] mixed $data) Outputs data inside a table

Examples:

li()->log("MyData", $myData);
li()->info($myData);
li()->table("clients", $myClientsCollection);

Additionally, you can use the "inspect" helper function to quickly inspect objects and variables.

inspect($var1, $var2, $var3,...);

Grouping Messages

Laravel Inspector allows you to group messages into nodes and subnodes:

li()->group('MyGroup');
	li()->info($data);
	li()->group('MySubGroup');
		li()->error('oops', $errorCode);
	li()->groupEnd();
	li()->success('perfect!');
li()->groupEnd();

In addition to the ability to group information, each group and subgroup excecution time will be measured and shown. If you forget to close a group, Laravel Inspector will automatically do it at the end of the script, but the excecution time for that group can not be taken.

Timers

Method Description
time(string $timerName) Starts a timer
timeEnd(string $timerName) Ends a timer
timeStamp(string $name) Adds a single marker to the timeline

Examples:

li()->time("MyTimer");
// ...
li()->timeEnd("MyTimer");

li()->timeStamp('Elapsed time from LARAVEL_START here');

Redirects

Laravel Inspector handles redirects smoothly; showing the collectors bag for both, the original and the target views.

Dump and die

The dd() method (or idd() helper) will dump the entire collectors bag and terminates the script:

\Inspector::dd();
li()->dd();

// or simply
idd();

// adding last minute data
idd($var1, $var2,...)

As the rest of the package, this feature intelligently determines how will be the format of the output, even if the call was performed from CLI.

Another way to make an inspection, but without interrupting the flow of the request/response, is by adding the parameter laravel_inspector=dump to the URL:

http://myapp.dev/contacts?id=1&laravel_inspector=dump

Thus, Laravel Inspector wont be activated until the a terminable middleware is reached.

Exceptions

The function addException() will inspect our caught exceptions:

try {
	...
} catch (Exception $e) {
	li()->addException($e);
}

Optionally, you can setup LI as the default exception renderer during development time (app.debug=true). Refer to the configuration to do so.

VIEW/AJAX/API requests, how it works

Laravel Inspector (LI) automatically detects the type of the request/response pair and determines the output format. If a View response is detected, the code needed to elegantly show the collected information in the browser console will be injected as a javascript into that view. Along with this, LI will also add a small piece of pure javascript code that serves as a generic http interceptor, which will examine subsequent AJAX calls looking for information injected by LI (this interceptor was tested under pure javascript, Angular 1.x ($http) and jQuery ($.ajax) and should work with any js framework). The interceptor also adds a header in each client AJAX call to let LI know that the interceptor is present. Then, from Laravel side, during an AJAX request or a JSON response, LI will send a script to be interpreted (and properly rendered in the browsers console) by the interceptor, OR a pure Json if that header is not present and then assuming that the request was sent from cURL, a REST client app or something else.

If you are developing, for example, an SPA and using Laravel only for the API but not to serve the web page/s, you can include the following code in your client app to take full advantage of all formatting features of Laravel Inspector.

(function(XHR) {
"use strict";

var send = XHR.prototype.send;

XHR.prototype.send = function(data) {
	var self = this;
	var oldOnReadyStateChange;
	var url = this._url;
	this.setRequestHeader('Laravel-Inspector', 'interceptor-present');
	function onReadyStateChange() {
		if(self.readyState == 4 /* complete */) {
			var response = JSON.parse(this.response);
			if (typeof response.LARAVEL_INSPECTOR !== 'undefined') {
				if(typeof response.LARAVEL_INSPECTOR === 'string')
				{
					eval(response.LARAVEL_INSPECTOR);
				} else {
					console.log('LARAVEL INSPECTOR ', response);
				 }
			 }   
		}
		if(oldOnReadyStateChange) {
			oldOnReadyStateChange();
		}
	}
	if(!this.noIntercept) {            
		if(this.addEventListener) {
			this.addEventListener("readystatechange", onReadyStateChange, false);
		} else {
			oldOnReadyStateChange = this.onreadystatechange;
			this.onreadystatechange = onReadyStateChange;
		}
	}
	send.call(this, data);
}
})(XMLHttpRequest);

License

Laravel Inspector is licensed under the MIT License.