my list of debugging functions to keep in an MU file

norcross-debug-functions.php

<?php
/*
Plugin Name: Norcross Debug Functions
Plugin URI: https://gist.github.com/norcross/7864205/
Description: A set of functions I use on all sites while building
Author: Andrew Norcross
Version: 0.0.1
Requires at least: 3.0
Author URI: http://andrewnorcross.com
*/

// Redefine the "expensive" query for QM.
define( 'QM_DB_EXPENSIVE', 0.1 );

// Set the name of the debug file.
define( 'RKV_DEBUG_LOGFILE', WP_CONTENT_DIR . '/debug.log' );

/**
 * Set up our various actions and filters as such.
 */
add_filter( 'auto_core_update_send_email', 'rkv_bypass_auto_update_email', 10, 4 );
add_action( 'wp_head', 'rkv_add_qm_css' );
add_action( 'admin_head', 'rkv_add_qm_css' );
add_action( 'init', 'rkv_auto_login' );
add_action( 'admin_init', 'rkv_auto_login' );
add_action( 'admin_init', 'rkv_purge_debug_file' );
add_action( 'admin_bar_menu', 'rkv_admin_bar_static', 9999 );


/**
 * Bypass the email sent for a successful auto-update.
 *
 * @param  bool   $send         Whether or not to send the email.
 * @param  string $type         The type of email to send. Can be one of 'success', 'fail', 'critical'.
 * @param  object $core_update  The update offer that was attempted.
 * @param  mixed  $result       The result for the core update. Can be WP_Error.
 *
 * @return bool                 The result to send the email.
 */
function rkv_bypass_auto_update_email( $send, $type, $core_update, $result ) {
	return ! empty( $type ) && 'success' === $type ? false : true;
}

/**
 * Add a small bit of CSS to the Query Monitor output.
 *
 * @return void
 */
function rkv_add_qm_css() {
	echo '<style>#qm { position: relative; z-index: 1000; }</style>' . "\n";
}

/**
 * Keeps a user always logged in.
 * NOTE: Don't use this on a production site, ever!
 *
 * @return void
 */
function rkv_auto_login() {

	// Bail if the user is logged in, an Ajax call, or a CLI call.
	if ( is_user_logged_in() || wp_doing_ajax() || defined( 'WP_CLI' ) && WP_CLI ) {
		return;
	}

	// Don't load on a specific query string.
	if ( isset( $_GET['test-logout'] ) ) {
		return;
	}

	// Get our userdata (change the ID to match).
	$user   = get_userdata( 1 );

	// Bail if I don't have userdata.
	if ( empty( $user ) || ! is_object( $user ) ) {
		return;
	}

	// Set the current user.
	wp_set_current_user( $user->ID, $user->user_login );

	// Set the auth cookie if we haven't sent headers already.
	if ( ! headers_sent() ) {
		wp_set_auth_cookie( $user->ID, true );
	}

	// Now actually log in.
	do_action( 'wp_login', $user->user_login, $user );
}

/**
 * Display array results in a readable fashion.
 *
 * @param  mixed   $display  The output we want to display.
 * @param  boolean $die      Whether or not to die as soon as output is generated.
 * @param  boolean $return   Whether to return the output or show it.
 *
 * @return mixed             Our printed (or returned) output.
 */
function preprint( $display, $die = false, $return = false ) {

	// Add some CSS to make it a bit more readable.
	$style  = 'background-color: #fff; color: #000; font-size: 16px; line-height: 22px; padding: 5px; white-space: pre-wrap; white-space: -moz-pre-wrap; white-space: -pre-wrap; white-space: -o-pre-wrap; word-wrap: break-word;';

	// Filter the style.
	$style  = apply_filters( 'rkv_preprint_style', $style );

	// Set up the code itself.
	$code   = print_r( $display, 1 );

	// Generate the actual output.
	$output = wp_doing_ajax() || defined( 'WP_CLI' ) && WP_CLI ? $code : '<pre style="' . $style . '">' . $code . '</pre>';

	// Return if requested.
	if ( $return ) {
		return $output;
	}

	// Print if requested (the default).
	if ( ! $return ) {
		print $output;
	}

	// Die if you want to die.
	if ( $die ) {
		die();
	}
}

/**
 * Grab the global WP_Query object and dump it.
 *
 * @param  boolean $die  Whether to die after generation.
 *
 * @return void
 */
function fullquery( $die = true ) {

	// Call the global WP_Query object.
	global $wp_query;

	// Output it.
	preprint( $wp_query, $die );
}

/**
 * Debugging Convenience function to show all the "filters" currently attached to a hook.
 *
 * @param  string  $hook  The hook to grab filters for.
 * @param  boolean $die   Whether to die after generation.
 *
 * @return mixed         Our printed output.
 */
function print_filters_for( $hook = '', $die = false ) {

	// Call the global wp_filter object.
	global $wp_filter;

	// Bail if no hook was provided or doesn't exist in the wp_filter object.
	if ( empty( $hook ) || ! isset( $wp_filter[ $hook ] ) ) {
		return;
	}

	// Output the information.
	preprint( $wp_filter[ $hook ], $die );
}

/**
 * Parse a JSON file into more readable text.
 *
 * @param  string $text  The JSON text we want to parse.
 *
 * @return string $text  The JSON text we want to parse.
 */
function rkv_json_parse( $text = '' ) {
	return str_replace( array( '\n', '\t' ), '', $text );
}

/**
 * Purge the debug file when requested.
 *
 * @return void
 */
function rkv_purge_debug_file() {

	// Bail if the user is not logged in, an Ajax call, or a CLI call.
	if ( ! is_user_logged_in() || ! is_admin() || wp_doing_ajax() || defined( 'WP_CLI' ) && WP_CLI ) {
		return;
	}

	// Bail if current user doesnt have cap.
	if ( ! current_user_can( 'manage_options' ) ) {
		return;
	}

	// Check for the query string.
	if ( empty( $_GET['purge-debug'] ) ) {
		return;
	}

	// Now check the nonce.
	if ( ! $_GET['purge-nonce'] || ! wp_verify_nonce( $_GET['purge-nonce'], 'purge-action' ) ) {
		return;
	}

	// Erase the debug file.
	file_put_contents( RKV_DEBUG_LOGFILE, '' );

	// And redirect with a query string.
	$direct = add_query_arg( array( 'purge-complete' => 1 ), admin_url( '/' ) );

	// Then redirect.
	wp_redirect( $direct );
	exit;
}

/**
 * Set our data array of GH repos.
 *
 * @return array
 */
function rkv_admin_bar_github_repos() {

	// Set the array to title => link structure.
	return apply_filters( 'rkv_admin_bar_github_repo_data', array() );
}

/**
 * Set our data array of site links.
 *
 * @return array
 */
function rkv_admin_bar_sitedev_links() {

	// Set the array to title => link structure.
	return apply_filters( 'rkv_admin_bar_sitedev_links_data', array() );
}

/**
 * Set up an array of the resource links.
 *
 * @return array
 */
function rkv_admin_bar_resource_links() {

	// Set the array to title => link structure.
	return array(
		'CLI Commands Directory' => 'https://developer.wordpress.org/cli/commands/',
		'CLI Commands Cookbook'  => 'https://make.wordpress.org/cli/handbook/commands-cookbook/',
		'CMB2 Wiki'              => 'https://github.com/CMB2/CMB2/wiki',
	);
}

/**
 * Determine if the file size exists.
 *
 * @return boolean / integer
 */
function rkv_admin_bar_logfile_size( $return = 'bytes' ) {

	// Check if the file exists at all.
	if ( ! file_exists( RKV_DEBUG_LOGFILE ) ) {

		// Make a blank debug file.
		file_put_contents( RKV_DEBUG_LOGFILE, '' );

		// And return zero (since it's empty).
		return 0;
	}

	// Check for some bytes.
	$maybe_has_byte = filesize( RKV_DEBUG_LOGFILE );

	// If it's empty, return the zero regardless of return type.
	if ( empty( $maybe_has_byte ) ) {
		return 0;
	}

	// Return the boolean or bytes.
	return 'boolean' === sanitize_text_field( $return ) ? true : $maybe_has_byte;
}

/**
 * Set all the args for the purge debug admin bar item.
 *
 * @param string $admin_parent  The parent item to add the item.
 *
 * @return array
 */
function rkv_admin_bar_logfile_args( $admin_parent = 'norcross-dev-links' ) {

	// Get the debug file size.
	$debug_filesize = rkv_admin_bar_logfile_size();

	// Determine the title.
	$adminbar_title = ! empty( $debug_filesize ) ? sprintf( __( 'Purge Debug File (%d bytes)' ), absint( $debug_filesize ) ) : __( 'Purge Debug File' );

	// Create the purge link, and decide if a target blank.
	$adminbar_link  = add_query_arg( array( 'purge-debug' => 1, 'purge-nonce' => wp_create_nonce( 'purge-action' ) ), admin_url( '/' ) );
	$adminbar_blank = ! is_admin() ? '_blank' : '';

	// Now set up and return the args.
	return array(
		'id'       => 'purge-debug-file',
		'title'    => esc_attr( $adminbar_title ),
		'href'     => esc_url( $adminbar_link ),
		'position' => 0,
		'parent'   => esc_attr( $admin_parent ),
		'meta'     => array(
			'title'    => 'Purge Debug File',
			'target'   => $adminbar_blank,
		),
	);
}

/**
 * Set up some quick links for the admin bar.
 *
 * @param  WP_Admin_Bar $wp_admin_bar  The global WP_Admin_Bar object.
 *
 * @return void.
 */
function rkv_admin_bar_static( WP_Admin_Bar $wp_admin_bar ) {

	// Bail if current user doesnt have cap.
	if ( ! current_user_can( 'manage_options' ) ) {
		return;
	}

	// Remove customizer.
	$wp_admin_bar->remove_node( 'customize' );

	// Add a main parent item.
	$wp_admin_bar->add_node(
		array(
			'id'    => 'norcross-dev-links',
			'title' => 'Dev Links',
		)
	);

	// Get my purge file args.
	$purge_args = rkv_admin_bar_logfile_args();

	// If we have purge args, continue.
	if ( ! empty( $purge_args ) ) {
		$wp_admin_bar->add_node( $purge_args );
	}

	// Add the GitHub profile link.
	$wp_admin_bar->add_node(
		array(
			'id'       => 'github-profile',
			'title'    => 'GitHub Profile',
			'href'     => 'https://github.com/norcross/',
			'position' => 0,
			'parent'   => 'norcross-dev-links',
			'meta'     => array(
				'title'    => 'GitHub Profile',
				'target'   => '_blank',
			),
		)
	);

	// Attempt to fetch the repos.
	$reposlist  = rkv_admin_bar_github_repos();

	// If we have repos, continue.
	if ( ! empty( $reposlist ) ) {

		// Add a parent item for the GitHub repos.
		$wp_admin_bar->add_node(
			array(
				'id'     => 'norcross-github-repos',
				'title'  => 'GitHub Repos',
				'parent' => 'norcross-dev-links',
			)
		);

		// Loop our repos and make links.
		foreach ( $reposlist as $label => $link ) {

			// Add the individual link.
			$wp_admin_bar->add_node(
				array(
					'id'       => sanitize_title_with_dashes( $label, '', 'save' ),
					'title'    => esc_attr( $label ),
					'href'     => esc_url( $link ),
					'position' => 0,
					'parent'   => 'norcross-github-repos',
					'meta'     => array(
						'title'    => esc_attr( $label ),
						'target'   => '_blank',
					),
				)
			);

			// No remaining things needed on each link.
		}
	}

	// Attempt to fetch the site list.
	$siteslist  = rkv_admin_bar_sitedev_links();

	// If we have sites, continue.
	if ( ! empty( $siteslist ) ) {

		// Add a parent item for the GitHub repos.
		$wp_admin_bar->add_node(
			array(
				'id'     => 'norcross-sitelist-repos',
				'title'  => 'Related Site Links',
				'parent' => 'norcross-dev-links',
			)
		);

		// Loop our repos and make links.
		foreach ( $siteslist as $label => $link ) {

			// Add the individual link.
			$wp_admin_bar->add_node(
				array(
					'id'       => sanitize_title_with_dashes( $label, '', 'save' ),
					'title'    => esc_attr( $label ),
					'href'     => esc_url( $link ),
					'position' => 0,
					'parent'   => 'norcross-sitelist-repos',
					'meta'     => array(
						'title'    => esc_attr( $label ),
						'target'   => '_blank',
					),
				)
			);

			// No remaining things needed on each link.
		}
	}

	// Attempt to fetch the resources.
	$resources  = rkv_admin_bar_resource_links();

	// If we have resources, continue.
	if ( ! empty( $resources ) ) {

		// Add a secondary parent item for the resources links.
		$wp_admin_bar->add_node(
			array(
				'id'     => 'norcross-dev-resource-links',
				'title'  => 'Resources',
				'parent' => 'norcross-dev-links',
			)
		);

		// Now loop our resources.
		foreach ( $resources as $label => $link ) {

			// Add the individual link.
			$wp_admin_bar->add_node(
				array(
					'id'       => sanitize_title_with_dashes( $label, '', 'save' ),
					'title'    => esc_attr( $label ),
					'href'     => esc_url( $link ),
					'position' => 0,
					'parent'   => 'norcross-dev-resource-links',
					'meta'     => array(
						'title'    => esc_attr( $label ),
						'target'   => '_blank',
					),
				)
			);

			// No remaining things needed on each link.
		}

		// No more resources added.
	}

	// Include any remaining modifications here.
}