yaffs.net Git - yaffs-website/blob - web/modules/contrib/devel/kint/kint/README.md

   1 # Kint - debugging helper for PHP developers
   2
   3 [![Total Downloads](https://poser.pugx.org/raveren/kint/downloads.png)](https://packagist.org/packages/raveren/kint)
   4
   5 > **New version** v1.0.0 is released with more than two years of active development - changes are too numerous to list, but there's CLI output and literally hundreds of improvements and additions.
   6
   7 ![Screenshot](http://raveren.github.com/kint/img/preview.png)
   8
   9 ## What am I looking at?
  10
  11 At first glance Kint is just a pretty replacement for **[var_dump()](http://php.net/manual/en/function.var-dump.php)**, **[print_r()](http://php.net/manual/en/function.print-r.php)** and **[debug_backtrace()](http://php.net/manual/en/function.debug-backtrace.php)**.
  12
  13 However, it's much, *much* more than that. Even the excellent `xdebug` var_dump improvements don't come close - you will eventually wonder how you developed without it.
  14
  15 Just to list some of the most useful features:
  16
  17  * The **variable name and place in code** where Kint was called from is displayed;
  18  * You can **disable all Kint output easily and on the fly** - so you can even debug live systems without anyone knowing (even though you know you shouldn't be doing that!:).
  19  * **CLI is detected** and formatted for automatically (but everything can be overridden on the fly) - if your setup supports it, the output is colored too:
  20   ![Kint CLI output](http://i.imgur.com/6B9MCLw.png)
  21  * **Debug backtraces** are finally fully readable, actually informative and a pleasure to the eye.
  22  * Kint has been **in active development for more than six years** and is shipped with [Drupal 8](https://www.drupal.org/) by default as part of its devel suite. You can trust it not being abandoned or getting left behind in features.
  23  * Variable content is **displayed in the most informative way** - and you *never, ever* miss anything! Kint guarantees you see every piece of physically available information about everything you are dumping*;
  24    * <sup>in some cases, the content is truncated where it would otherwise be too large to view anyway - but the user is always made aware of that;</sup>
  25  * Some variable content types have an alternative display - for example you will be able see `JSON` in its raw form - but also as an associative array:
  26   ![Kint displays data intelligently](http://i.imgur.com/9P57Ror.png)
  27   There are more than ten custom variable type displays inbuilt and more are added periodically.
  28
  29
  30 ## Installation and Usage
  31
  32 One of the main goals of Kint is to be **zero setup**.
  33
  34 [Download the archive](https://github.com/raveren/kint/releases/download/1.0.2/kint.zip) and simply
  35 ```php
  36 <?php
  37 require '/kint/Kint.class.php';
  38 ```
  39
  40 **Or, if you use Composer:**
  41
  42 ```json
  43 "require": {
  44    "raveren/kint": "^1.0"
  45 }
  46 ```
  47
  48 Or just run `composer require raveren/kint`
  49
  50 **That's it, you can now use Kint to debug your code:**
  51
  52 ```php
  53 ########## DUMP VARIABLE ###########################
  54 Kint::dump($GLOBALS, $_SERVER); // pass any number of parameters
  55
  56 // or simply use d() as a shorthand:
  57 d($_SERVER);
  58
  59
  60 ########## DEBUG BACKTRACE #########################
  61 Kint::trace();
  62 // or via shorthand:
  63 d(1);
  64
  65
  66 ############# BASIC OUTPUT #########################
  67 # this will show a basic javascript-free display
  68 s($GLOBALS);
  69
  70
  71 ######### WHITESPACE FORMATTED OUTPUT ##############
  72 # this will be garbled if viewed in browser as it is whitespace-formatted only
  73 ~d($GLOBALS); // just prepend with the tilde
  74
  75
  76 ########## MISCELLANEOUS ###########################
  77 # this will disable kint completely
  78 Kint::enabled(false);
  79
  80 ddd('Get off my lawn!'); // no effect
  81
  82 Kint::enabled(true);
  83 ddd( 'this line will stop the execution flow because Kint was just re-enabled above!' );
  84
  85
  86 ```
  87
  88 Note, that Kint *does* have configuration (like themes and IDE integration!), but it's in need of being rewritten, so I'm not documenting it yet.
  89
  90 ## Tips & Tricks
  91
  92   * Kint is enabled by default, call `Kint::enabled(false);` to turn its funcionality completely off. The *best practice* is to enable Kint in DEVELOPMENT environment only (or for example `Kint::enabled($_SERVER['REMOTE_ADDR'] === '<your IP>');`) - so even if you accidentally leave a dump in production, no one will know.
  93   * `sd()` and `ddd()` are shorthands for `s();die;` and `d();die;` respectively.
  94     * **Important:** The older shorthand `dd()` is deprecated due to compatibility issues and will eventually be removed. Use the analogous `ddd()` instead.
  95   * When looking at Kint output, press <kbd>D</kbd> on the keyboard and you will be able to traverse the tree with arrows and tab keys - and expand/collapse nodes with space or enter.
  96   * Double clicking the `[+]` sign in the output will expand/collapse ALL nodes; triple clicking big blocks of text will select it all.
  97   * Clicking the tiny arrows on the right of the output open it in a separate window where you can keep it for comparison.
  98   * To catch output from Kint just assign it to a variable<sup>beta</sup>
  99 ```php
 100 $o = Kint::dump($GLOBALS);
 101 // yes, the assignment is automatically detected, and $o
 102 // now holds whatever was going to be printed otherwise.
 103
 104 // it also supports modifiers (read on) for the variable:
 105 ~$o = Kint::dump($GLOBALS); // this output will be in whitespace
 106 ```
 107   * There are a couple of real-time modifiers you can use:
 108     * `~d($var)` this call will output in plain text format.
 109     * `+d($var)` will disregard depth level limits and output everything (careful, this can hang your browser on huge objects)
 110     * `!d($var)` will show expanded rich output.
 111     * `-d($var)` will attempt to `ob_clean` the previous output so if you're dumping something inside a HTML page, you will still see Kint output.
 112   You can combine modifiers too: `~+d($var)`
 113   * To force a specific dump output type just pass it to the `Kint::enabled()` method. Available options are: `Kint::MODE_RICH` (default), `Kint::MODE_PLAIN`, `Kint::MODE_WHITESPACE` and `Kint::MODE_CLI`:
 114 ```php
 115 Kint::enabled(Kint::MODE_WHITESPACE);
 116 $kintOutput = Kint::dump($GLOBALS);
 117 // now $kintOutput can be written to a text log file and
 118 // be perfectly readable from there
 119 ```
 120   * To change display theme, use `Kint::$theme = '<theme name>';` where available options are: `'original'` (default), `'solarized'`, `'solarized-dark'` and `'aante-light'`. Here's an (outdated) preview:
 121   ![Kint themes](http://raveren.github.io/kint/img/theme-preview.png)
 122   * Kint also includes a naïve profiler you may find handy. It's for determining relatively which code blocks take longer than others:
 123 ```php
 124 Kint::dump( microtime() ); // just pass microtime()
 125 sleep( 1 );
 126 Kint::dump( microtime(), 'after sleep(1)' );
 127 sleep( 2 );
 128 ddd( microtime(), 'final call, after sleep(2)' );
 129 ```
 130   ![Kint profiling feature](http://i.imgur.com/tmHUMW4.png)
 131 ----
 132
 133 [Visit the project page](http://raveren.github.com/kint/) for documentation, configuration, and more advanced usage examples.
 134
 135 ### Author
 136
 137 **Rokas Šleinius** (Raveren)
 138
 139 ### License
 140
 141 Licensed under the MIT License