I have often worked with users who are having issues with directory paths and files within their installations.
I am about to release a new premium snippet on reallyusefulplugins.com, and that will require users to understand pathed soldered, specifically a folder of their choosing below above or on the same level as HTML. So, it’s not publicly accessible, but I can already see the issues users would have in doing this.
So I thought long and hard about the best way to help people understand this and work out how to do this, and that was where I came up with RUP Troubleshooting Tools
- 1. [rup_troubleshoot_directory_path] Displays the WordPress installation directory (ABSPATH).
- 2. [rup_troubleshoot_check_path path=”/home/username/”] – Checks if the folder exists and displays its status.
- 3. [rup_troubleshoot_list_files path=”/home/username/” extension=”pdf”] – Lists files in the folder, filtering by PDF files.
- 4. [rup_troubleshoot_file_permissions path=”/home/username/another_event_ticket_99.pdf”] – Displays the permissions of the file in octal format.
- 5. [rup_troubleshoot_file_status path=”/home/username/another_event_ticket_99.pdf”] – Checks if the file is readable, writable, and executable.
For easy operation there is even a single-use dynamic shortcode based on some admin area options called [rup_troubleshoot_dynamic_content] that will populate all those shortcodes on a page based on the default options in the admin area
Below is an example of an output page split over two images so you can see examples of the output
All this is set through the admin settings page, which can be found within the Tools menu.
Warning: Don’t leave this installed on your site. It is for fault-finding and troubleshooting only. This information should be protected. Don’t leave it on the front end for anyone to find beyond your faultfinding.
<?php
/**
* RUP Troubleshooting Tools (Snippet)
*
* Paste this code into your theme’s functions.php file.
* It provides individual troubleshooting shortcodes plus a dynamic shortcode,
* an admin settings page (under Tools) to update example paths,
* and registers dynamic Gutenberg blocks for each shortcode.
*
* Use [rup_troubleshoot_dynamic_content] anywhere to display the dynamic troubleshooting content.
*/
/**
* ------------------------------
* TROUBLESHOOTING SHORTCODES
* ------------------------------
*/
/* 1. Display WordPress Installation Directory Path */
function rup_troubleshoot_directory_path_shortcode() {
if ( ! current_user_can( 'manage_options' ) ) {
return 'Insufficient permissions.';
}
return '<pre>' . esc_html( ABSPATH ) . '</pre>';
}
add_shortcode( 'rup_troubleshoot_directory_path', 'rup_troubleshoot_directory_path_shortcode' );
/* 2. Check if a Path Exists */
function rup_troubleshoot_check_path_shortcode( $atts ) {
if ( ! current_user_can( 'manage_options' ) ) {
return 'Insufficient permissions.';
}
$atts = shortcode_atts( array(
'path' => ABSPATH,
), $atts, 'rup_troubleshoot_check_path' );
$path = $atts['path'];
$status = file_exists( $path ) ? 'exists' : 'does not exist';
$output = sprintf( "Path: %s\nStatus: %s", esc_html( $path ), esc_html( $status ) );
return '<pre>' . $output . '</pre>';
}
add_shortcode( 'rup_troubleshoot_check_path', 'rup_troubleshoot_check_path_shortcode' );
/* 3. List Files in a Directory */
function rup_troubleshoot_list_files_shortcode( $atts ) {
if ( ! current_user_can( 'manage_options' ) ) {
return 'Insufficient permissions.';
}
$atts = shortcode_atts( array(
'path' => ABSPATH,
'extension' => '', // e.g., "pdf" to filter by PDF files.
), $atts, 'rup_troubleshoot_list_files' );
$dir = $atts['path'];
if ( ! is_dir( $dir ) ) {
return 'The specified path is not a directory.';
}
$files = scandir( $dir );
if ( $files === false ) {
return 'Unable to read the directory.';
}
$output = '<ul>';
foreach ( $files as $file ) {
if ( $file === '.' || $file === '..' ) {
continue;
}
if ( $atts['extension'] ) {
if ( pathinfo( $file, PATHINFO_EXTENSION ) !== ltrim( $atts['extension'], '.' ) ) {
continue;
}
}
$output .= '<li>' . esc_html( $file ) . '</li>';
}
$output .= '</ul>';
return $output;
}
add_shortcode( 'rup_troubleshoot_list_files', 'rup_troubleshoot_list_files_shortcode' );
/* 4. Check File Permissions */
function rup_troubleshoot_file_permissions_shortcode( $atts ) {
if ( ! current_user_can( 'manage_options' ) ) {
return 'Insufficient permissions.';
}
$atts = shortcode_atts( array(
'path' => '',
), $atts, 'rup_troubleshoot_file_permissions' );
$file = $atts['path'];
if ( empty( $file ) ) {
return 'Please provide a file path.';
}
if ( ! file_exists( $file ) ) {
return 'The specified file does not exist.';
}
$perms = fileperms( $file );
$perms_octal = substr( sprintf( '%o', $perms ), -4 );
$output = "File: " . esc_html( $file ) . "\n";
$output .= "Permissions: " . esc_html( $perms_octal );
return '<pre>' . esc_html( $output ) . '</pre>';
}
add_shortcode( 'rup_troubleshoot_file_permissions', 'rup_troubleshoot_file_permissions_shortcode' );
/* 5. Check File Status (Readable, Writable, Executable) */
function rup_troubleshoot_file_status_shortcode( $atts ) {
if ( ! current_user_can( 'manage_options' ) ) {
return 'Insufficient permissions.';
}
$atts = shortcode_atts( array(
'path' => '',
), $atts, 'rup_troubleshoot_file_status' );
$file = $atts['path'];
if ( empty( $file ) ) {
return 'Please provide a file path.';
}
if ( ! file_exists( $file ) ) {
return 'The specified file does not exist.';
}
$status = array();
$status[] = 'Readable: ' . ( is_readable( $file ) ? 'Yes' : 'No' );
$status[] = 'Writable: ' . ( is_writable( $file ) ? 'Yes' : 'No' );
$status[] = 'Executable: ' . ( is_executable( $file ) ? 'Yes' : 'No' );
$output = "File: " . esc_html( $file ) . "\n";
$output .= implode( "\n", $status );
return '<pre>' . esc_html( $output ) . '</pre>';
}
add_shortcode( 'rup_troubleshoot_file_status', 'rup_troubleshoot_file_status_shortcode' );
/**
* -------------------------------------------
* DYNAMIC FRONT-END CONTENT SHORTCODE
* -------------------------------------------
*
* This shortcode dynamically builds the troubleshooting content using the saved options.
* We pass its output through do_shortcode() so that any embedded shortcodes are rendered.
*/
function rup_troubleshoot_dynamic_content_shortcode() {
// Retrieve saved options.
$existing_folder = get_option( 'rup_troubleshoot_existing_folder', '/home/wpdemosi66/domains/tickets.wpninja.uk/events/event2' );
$existing_file = get_option( 'rup_troubleshoot_existing_file', '/home/wpdemosi66/domains/tickets.wpninja.uk/events/event2/another_event_ticket_99.pdf' );
$nonexistent = get_option( 'rup_troubleshoot_nonexistent', '/home/wpdemosi66/domains/tickets.wpninja.uk/events/event2/nonexistent_file.pdf' );
$output = '<h1>System File Checks</h1>';
$output .= '<p>This section provides various troubleshooting shortcodes to check file paths, list files, and examine file properties.</p>';
$output .= '<h2>Shortcode Examples</h2>';
$output .= '<ul>';
$output .= '<li><strong>Directory Path:</strong> [rup_troubleshoot_directory_path]</li>';
$output .= '<li><strong>Check Folder (Existing):</strong><br>[rup_troubleshoot_check_path path="' . esc_attr( $existing_folder ) . '"]</li>';
$output .= '<li><strong>Check Folder (Non-Existent):</strong><br>[rup_troubleshoot_check_path path="' . esc_attr( $existing_folder . '/nonexistent_folder' ) . '"]</li>';
$output .= '<li><strong>List Files (Existing Folder):</strong><br>[rup_troubleshoot_list_files path="' . esc_attr( $existing_folder ) . '" extension="pdf"]</li>';
$output .= '<li><strong>File Permissions (Existing File):</strong><br>[rup_troubleshoot_file_permissions path="' . esc_attr( $existing_file ) . '"]</li>';
$output .= '<li><strong>File Permissions (Non-Existent):</strong><br>[rup_troubleshoot_file_permissions path="' . esc_attr( $nonexistent ) . '"]</li>';
$output .= '<li><strong>File Status (Existing File):</strong><br>[rup_troubleshoot_file_status path="' . esc_attr( $existing_file ) . '"]</li>';
$output .= '<li><strong>File Status (Non-Existent):</strong><br>[rup_troubleshoot_file_status path="' . esc_attr( $nonexistent ) . '"]</li>';
$output .= '</ul>';
return do_shortcode( $output );
}
add_shortcode( 'rup_troubleshoot_dynamic_content', 'rup_troubleshoot_dynamic_content_shortcode' );
/**
* -------------------------------------------
* ADMIN TOOLS PAGE WITH SETTINGS
* -------------------------------------------
*
* Adds a link under Tools > File Paths Troubleshooting that displays a settings form
* so you can enter your example paths. These values are used by the dynamic shortcode.
* Also, the "Individual Shortcodes" section below now shows each shortcode populated
* with the current option values.
*/
function rup_troubleshoot_admin_menu() {
add_management_page(
'File Paths Troubleshooting', // Page title.
'File Paths Troubleshooting', // Menu title.
'manage_options', // Capability.
'rup-troubleshoot-admin', // Menu slug.
'rup_troubleshoot_admin_page' // Callback function.
);
}
add_action( 'admin_menu', 'rup_troubleshoot_admin_menu' );
function rup_troubleshoot_admin_page() {
// Process form submission.
if ( isset( $_POST['rup_troubleshoot_settings_nonce'] ) &&
wp_verify_nonce( $_POST['rup_troubleshoot_settings_nonce'], 'rup_troubleshoot_save_settings' ) ) {
// Sanitize and update options.
$existing_folder = sanitize_text_field( $_POST['rup_troubleshoot_existing_folder'] );
$existing_file = sanitize_text_field( $_POST['rup_troubleshoot_existing_file'] );
$nonexistent = sanitize_text_field( $_POST['rup_troubleshoot_nonexistent'] );
update_option( 'rup_troubleshoot_existing_folder', $existing_folder );
update_option( 'rup_troubleshoot_existing_file', $existing_file );
update_option( 'rup_troubleshoot_nonexistent', $nonexistent );
echo '<div id="message" class="updated notice is-dismissible"><p>Settings saved.</p></div>';
}
// Get saved options or defaults.
$existing_folder = get_option( 'rup_troubleshoot_existing_folder', '/home/wpdemosi66/domains/tickets.wpninja.uk/events/event2' );
$existing_file = get_option( 'rup_troubleshoot_existing_file', '/home/wpdemosi66/domains/tickets.wpninja.uk/events/event2/another_event_ticket_99.pdf' );
$nonexistent = get_option( 'rup_troubleshoot_nonexistent', '/home/wpdemosi66/domains/tickets.wpninja.uk/events/event2/nonexistent_file.pdf' );
?>
<div class="wrap">
<h1>File Paths Troubleshooting</h1>
<p>Use the form below to set the example paths. These values are used by the dynamic shortcode <code>[rup_troubleshoot_dynamic_content]</code>.</p>
<form method="post" action="">
<?php wp_nonce_field( 'rup_troubleshoot_save_settings', 'rup_troubleshoot_settings_nonce' ); ?>
<table class="form-table">
<tr valign="top">
<th scope="row"><label for="rup_troubleshoot_existing_folder">Existing Folder</label></th>
<td>
<input type="text" id="rup_troubleshoot_existing_folder" name="rup_troubleshoot_existing_folder" value="<?php echo esc_attr( $existing_folder ); ?>" class="regular-text" />
<p class="description">Folder that exists on your system.</p>
</td>
</tr>
<tr valign="top">
<th scope="row"><label for="rup_troubleshoot_existing_file">Existing File</label></th>
<td>
<input type="text" id="rup_troubleshoot_existing_file" name="rup_troubleshoot_existing_file" value="<?php echo esc_attr( $existing_file ); ?>" class="regular-text" />
<p class="description">File that exists on your system.</p>
</td>
</tr>
<tr valign="top">
<th scope="row"><label for="rup_troubleshoot_nonexistent">Non-Existent File/Folder</label></th>
<td>
<input type="text" id="rup_troubleshoot_nonexistent" name="rup_troubleshoot_nonexistent" value="<?php echo esc_attr( $nonexistent ); ?>" class="regular-text" />
<p class="description">A path that does not exist (for testing purposes).</p>
</td>
</tr>
</table>
<?php submit_button(); ?>
</form>
<h2>Dynamic Shortcode Example</h2>
<p>Place the shortcode <code>[rup_troubleshoot_dynamic_content]</code> anywhere in your posts or pages to display the troubleshooting content.</p>
<h2>Individual Shortcodes (Populated with Current Settings)</h2>
<pre>
[rup_troubleshoot_directory_path]
- Displays the WordPress installation directory (ABSPATH).
[rup_troubleshoot_check_path path="<?php echo esc_html( $existing_folder ); ?>"]
- Checks if the folder exists and displays its status.
[rup_troubleshoot_list_files path="<?php echo esc_html( $existing_folder ); ?>" extension="pdf"]
- Lists files in the folder, filtering by PDF files.
[rup_troubleshoot_file_permissions path="<?php echo esc_html( $existing_file ); ?>"]
- Displays the permissions of the file in octal format.
[rup_troubleshoot_file_status path="<?php echo esc_html( $existing_file ); ?>"]
- Checks if the file is readable, writable, and executable.
</pre>
</div>
<?php
}
