emergency diagnostic recovery tool

Introduction

White Screen of Death? Server 500 Error? Error caused by an unknown plugin or theme? ParaMedic dropin instantly tests all your plugins and themes with WordPress individually for errors, letting you know quickly what is causing issues.

While this can save anyone time in fixing their own website, it will save developers, support agents, and web hosts that time many times over each and every month in resolving issues and conflicts faster.

Security Warning

Even though the security risk is very low (revealing installed plugin and theme versions) - it is still preferable that you do not leave Paramedic installed during normal operation of a live site, but rather drop it in, use it, and then remove it when you are done.

Practically speaking however, if your site (or admin) is crashed, in an emergency there are situations where you may need to keep using Paramedic to narrow down the problem further. In this case you will want to setup a simple security key to access Paramedic. (see Security Key Setup in the Installation section)

Installation

  1. Simply copy this one file in your WordPress install /wp-content/mu-plugins/ directory.
  2. If this directory does not exist then you will need to create it first.
    • remembering to chown owner:group mu-plugins to match your existing installation.
  3. Note because of the 000- filename prefix, this file will load before other must-use plugins.
    • this is intentional so that it can test and track the results of other must-use plugins.
  4. Go to your site and append ?paramedic to the URL to load the ParaMedic test interface.
    • eg. http://yoursite.com/?paramedic
Security Key Setup

If you are leaving Paramedic installed for any length of time, it is recommended you require an authentication key to access the interface. Set this constant in wp-config.php:

define('PARAMEDIC_MUSTAUTH', true);

And define a hard-coded password-style authentication string there as well:

define('PARAMEDIC_KEY', 'myaccesskey');

Once done, to access Paramedic you will need to provide the key in the URL:

http://yoursite.com/?paramedic=myaccesskey or http://yoursite.com/?paramedic&key=myaccesskey

Usage Notes

The Paramedic Interface is available by appending ?paramedic to your site URL: eg. http://yoursite.com/?paramedic

Alternatively you can use a direct Querystring to conduct test (see list below) eg. http://yoursite.com/?paramedic&plugintest=all

Trigger Test Querystrings

?paramedic launch ParaMedic tests and/or display test launch form menu
&coretest= active/yes/1 (automatically triggered for any other tests)
&themetest= active/yes/1, inactive, network, all {comma-separated theme slugs}
&plugintest= active/yes/1, inactive, network, all {comma-separated plugin slugs}

&testall= yes or 1 test all plugins and themes
active test all active plugins and active theme
inactive tests all inactive plugins and themes
network tests network active plugins and active blog themes

Note: combinations can trigger multiple tests in series.

Test Specific Resources

this documentation may need updating

&testplugins= comma separated string of plugins to test
&testthemes= comma separated string of themes to test

Test Querystrings

Querystring Possible Values Description
&testid= id arbitrary ID (for identifying test result log)
&testurl= {FULL URL} eg. http://example.com/ (defaults to site_url('/'))
&usetheme= themeslug forces the use of a specified theme with plugin tests
&silent= yes or 1 test results to log file only, no screen output
&user= current/guest/userid user to be used during tests (default: current user)
&userid= numeric [KEY REQUIRED] set specific user ID (if user=userid)
&method= wp/curl set test method for Curl (default wp)
&timelimit= numeric maximum time limit for all tests to complete in
&testlog= yes or 1 whether to log test results to instance file
&logpath= directory path directory path for logging and test results files
&cleanup= yes or 1 cleanup test instance log files (can be used with logpath)
&inverse= yes/1, no/0 or all do inverse plugin test on plugin error (default yes)
&repair= yes or 1 [KEY REQUIRED] deactivate plugins with fatal errors
&debug yes/echo, log or logecho output tester debugger information on the page

Note: security key constant (see below) is required for setting userid or repair.

Test Constants

Set these in your wp-config.php.

Security Constants

PARAMEDIC_KEY set/override access key for tests (required for specific user ID tests)
PARAMEDIC_MUSTAUTH set to true to require the access key for any tests and test menu display

Settings Constants

Setting of these constants override any querystrings values (see Test Querystrings section.) If set, remember that results from querystring-triggered tests may not be what you expected.

PARAMEDIC_ID override for test instance ID
PARAMEDIC_TOKEN override for test internal token
PARAMEDIC_URL override for test request URL
PARAMEDIC_TIME override for test maximum execution time
PARAMEDIC_USER override for test user (current, guest, user ID, or username)
PARAMEDIC_METHOD override for test method (wp or curl)
PARAMEDIC_TESTLOG override for test result logging switch
PARAMEDIC_LOGPATH override for debug log path (default /wp-content/debug.log)
PARAMEDIC_SILENT override for silent test output (ie. logging only)
PARAMEDIC_THEME_DIR override for theme root directory
PARAMEDIC_PLUGIN_DIR override for plugin root directory
PARAMEDIC_REPAIR override for auto-deactivate plugins causing fatal errors
PARAMEDIC_DEBUG override for displaying all debug information on test page

Must-Use Plugin Tests

This feature is still under consideration and development.

As this file is itself a must-use plugin, in order to test these you will need to add this snippet to your wp-config.php to make testing these possible:

if (isset($_REQUEST['paramedic'])) { define('MUPLUGINDIR', ABSPATH.'/wp-content/mu-plugins/paramedic/'); define('WPMU_PLUGIN_DIR', ABSPATH.'/wp-content/mu-plugins/paramedic/'); define('WPMU_PLUGIN_URL', $_SERVER['HTTP_HOST'].'/wp-content/mu-plugins/paramedic/'); }

  1. Add the above code snippet to your installation wp-config.php file.
  2. If needed, adjust the paths and URLs to match your WordPress installation.
  3. Then copy 000-paramedic.php to /wp-content/mu-plugins/paramedic/
  4. Copy any must-use plugins that you want to test into the same directory.
  5. Remember to check and maybe change the file owner permissions to match your intall.
  6. Run WP Paramedic tests as normal and it will be able to test the mu-plugins


Love WP ParaMedic? Say thankyou by supporting WP Medic through Patreon
Share with Love: