README


Version	2.1.1
Changelog	https://gitlab.com/viharm/phpKhelper/-/blob/master/CHANGELOG
Download	https://gitlab.com/viharm/phpKhelper/tags
Repository	https://gitlab.com/viharm/phpKhelper.git
Issues	https://gitlab.com/viharm/phpKhelper/issues
License	BSD (3-clause)
Language	PHP

phpKhelper is a companion PHP library to accompany Kint (http://kint-php.github.io/kint/)

Pre-requisites

PHP: At least version 7.4.0.
Kint: At least version 6.0.0. The file phpKhelper.lib.inc.php is a launcher for the Kint library. From phpKhelper v01.03.00 onwards, Kint is included in the project by default and no user intervention is required for inclusion of Kint.

Download

Download the debug module.

Composer

From v1.4.1 onwards, phpKhelper is enabled for Composer, and is available on Packagist as viharm/php-khelper. You may either install it standalone or include it in your project as a dependency.

Standalone

php composer.phar create-project viharm/php-khelper phpKhelper

The above command will install phpKhelper in a sub-directory phpKhelper of the current working directory.

Dependency

To make Composer automatically install phpKhelper as a dependency include the following in your composer.json

{
	"require": {
    "viharm/php-khelper": "^1.4.1"
	}
}

If you would prefer to install this dependency in a custom directory, please include the following in your composer.json

{
	"require": {
    "php": ">=7.4.0",
    "mnsami/composer-custom-directory-installer": "2.0.*",
    "viharm/php-khelper": ">=2.0.0"
	},
 "config": {
    "vendor-dir": "Lib"
  },
  "extra": {
    "installer-paths": {
      "./Lib/phpKhelper": ["viharm/php-khelper"]
    }
}

In the above example, mnsami's Composer Custom Directory Installer is used to customise the install path.

* `Lib` is the sub-directory for plugins
* `./Lib/phpKhelper` is the install path for *phpKhelper*, relative to your project directory (`composer.json` location)

Clone repository

Clone the repository into the required location

git clone https://gitlab.com/viharm/phpKhelper.git

Deploy

You should have a directory structure like the following:

<YOURINCLUDEPATH>/phpKhelper/README.md
<YOURINCLUDEPATH>/phpKhelper/LICENSE
<YOURINCLUDEPATH>/phpKhelper/VERSION
<YOURINCLUDEPATH>/phpKhelper/phpKhelper.lib.inc.php
<YOURINCLUDEPATH>/phpKhelper/kint.phar

Configure

Simply include the debug script in your code. If your include path is in the sub-directory Lib, then you can use the following code to include all files in that directory ending with .inc.php.

  $sr_Filename = '' ;
  foreach (
    glob ( 
      dirname(__FILE__) . DIRECTORY_SEPARATOR .
      'Lib' .  DIRECTORY_SEPARATOR .
      '*.inc.php'
    ) as $sr_Filename
  ) {
    include_once(realpath($sr_Filename)) ;
  }

Replace the above values with those relevant/appropriate to the application environment.

Usage

Debugging can be enabled by setting boolean $GLOBALS['bl_DebugSwitch'] to TRUE.

$GLOBALS['bl_DebugSwitch'] = TRUE ;

Simply pass your desired variables to phpKhelper as an argument to the fn_Debug function.

fn_Debug ( 'Some message describing the output' , $VariableToDebug ) ;

For most use cases, this function simply passes the variable to Kint for display/logging.

If this is the only desired feature then phpKhelper is not required and it is recommended to use Kint directly. However phpKhelper is particularly useful for additional functionality, not provided by Kint.

Additional features

Some additional features have been included.

Obfuscation

If your users have to send you debug output, then this may assist by not having them manually remove their sensitive information.

Obfuscation can be carried out on strings variable or on string items inside arrays.

Strings

Obfuscate strings by passing a third non-null parameter

fn_Debug ( 'Some message describing the output' , $StringToDebug , 'AnyNonNullVariable' ) ;

This could be anything, even an empty string.

Strings inside arrays

If the sensitive data is inside an array then simply pass the array as usual, followed by the key name whose value is to be obfuscated.

Key name comparison is currently case-sensitive.

Single key value

If obfuscation is required for the values for all occurences of a single key, the third argument should be a string with the exact key name.

e.g., for the array

$ArrayToDebug = array (
  'username' => 'john' ,
  'password' => 'secret'
) ;

... the following call to debug will obfuscate the value (secret) of the key password.

fn_Debug ( 'Some message describing the output' , $ArrayToDebug , 'password' ) ;

Multiple key values

If obfuscation is required for the values for all occurences of more than one key, the third argument should be a non-associative array with each item as a string with the exact key names to obfuscated.

e.g., for the array

$ArrayToDebug = array (
  'username' => 'john' ,
  'password' => 'secret' ,
  'proxy'    => array (
    'proxyhost' => 'localhost' ,
    'proxyuser' => 'usernameforproxy' ,
    'proxypw'   => 'passwordforproxy'
  )
) ;

... the following call to debug will obfuscate the value (secret) of the key password as well as the value (passwordforproxy) of the key proxypw.

fn_Debug ( 'Some message describing the output' , $ArrayToDebug , array('password','proxpw') ) ;

Debug override

If the global debug is disabled ($GLOBALS['bl_DebugSwitch'] = FALSE ;), then the fourth parameter can override this to debug only specific parts of your script.

fn_Debug ( 'Some message describing the output' , $VariableToDebug , NULL , TRUE ) ;

Since this is controlled locally, remember to disable it as it overrides the global setting, so the latter will have no effect on this.

Fallback debug

Some frameworks may suppress Kint's output (which is typically unlikely).

In this case, the fifth parameter can cause the debug output to be displayed as PHP errors.

fn_Debug ( 'Some message describing the output' , $StringToDebug , NULL , NULL , TRUE ) ;

Known limitations

See

Support

For issues, queries, suggestions and comments please create an issue using the link provided at the top of this page.

Contribute

Please feel free to clone/fork and contribute via pull requests. Donations also welcome at (https://ko-fi.com/viharm).

Please make contact for more information.

Development environment

Developed on..

Debian Wheezy
Debian Jessie
Apache 2.2
Apache 2.4
PHP 5.4 [Kint 6.x requires at least PHP 7.4]
PHP 5.5
PHP 5.6
PHP 7.4
PHP 8.0
PHP 8.1
PHP 8.2
PHP 8.3
PHP 8.4
Kint (as of 2015-06-15)
Kint 2.1.2
Kint 6.x

License

Licensed under the modified BSD (3-clause) license.

A copy of the license is available...

in the enclosed LICENSE file.
at http://opensource.org/licenses/BSD-3-Clause

Reference

Kint

Kint debugging library (http://kint-php.github.io/kint/). Licensed under the MIT license

PHP

This project has been developed using the PHP scripting language.

Keep a Changelog

All notable changes to this project will be documented in the CHANGELOG file.

The format is based on Keep a Changelog. Referenced under the MIT license.

Gitmoji

This project endeavours to adhere to the Gitmoji specification. Referenced under the MIT license.

Credits

Code Server

A self-hosted, open source, cloud development environment.

Ungit

Ungit client for Git (https://github.com/FredrikNoren/ungit) used under the MIT license

GitLab

Hosted by GitLab code repository (gitlab.com).

Codiad

Codiad web based IDE (https://github.com/Codiad/Codiad). Licensed under a MIT-style license.

CodeGit

CodeGit Git plugin for Codiad (https://github.com/Andr3as/Codiad-CodeGit), used under a MIT-style license.

viharm / php-khelper

Maintainers

Details