* The plugin logging class.
defined( 'WPINC' ) || exit();
* Centralized debug logging utilities for LiteSpeed Cache.
class Debug2 extends Root {
private static $log_path;
* Directory prefix for all log files.
private static $log_path_prefix;
* Request-specific log line prefix.
const TYPE_CLEAR_LOG = 'clear_log';
const TYPE_BETA_TEST = 'beta_test';
const BETA_TEST_URL = 'beta_test_url';
const BETA_TEST_URL_WP = 'https://downloads.wordpress.org/plugin/litespeed-cache.zip';
* NOTE: until LSCWP_LOG is defined, calls to WP filters are not logged to
* avoid a recursion loop inside log_filters().
public function __construct() {
self::$log_path_prefix = LITESPEED_STATIC_DIR . '/debug/';
// Maybe move legacy log files
$this->_maybe_init_folder();
self::$log_path = $this->path( 'debug' );
$ua = isset( $_SERVER['HTTP_USER_AGENT'] )
? sanitize_text_field( wp_unslash( $_SERVER['HTTP_USER_AGENT'] ) )
if ( '' !== $ua && 0 === strpos( $ua, 'lscache_' ) ) {
self::$log_path = $this->path( 'crawler' );
! defined( 'LSCWP_LOG_TAG' ) && define( 'LSCWP_LOG_TAG', get_current_blog_id() );
if ( $this->conf( Base::O_DEBUG_LEVEL ) ) {
! defined( 'LSCWP_LOG_MORE' ) && define( 'LSCWP_LOG_MORE', true );
defined( 'LSCWP_DEBUG_EXC_STRINGS' ) || define( 'LSCWP_DEBUG_EXC_STRINGS', $this->conf( Base::O_DEBUG_EXC_STRINGS ) );
* Disable all functionalities temporarily (toggle).
* @param int $time How long (in seconds) to disable LSC functions.
public static function tmp_disable( $time = 86400 ) {
$disabled = self::cls()->conf( Base::DEBUG_TMP_DISABLE );
$conf->update_confs( [ Base::DEBUG_TMP_DISABLE => time() + (int) $time ] );
self::debug2( 'LiteSpeed Cache temporary disabled.' );
$conf->update_confs( [ Base::DEBUG_TMP_DISABLE => 0 ] );
self::debug2( 'LiteSpeed Cache reactivated.' );
* Is the temporary disable active? If expired, re-enable.
public static function is_tmp_disable() {
$disabled_time = self::cls()->conf( Base::DEBUG_TMP_DISABLE );
if ( 0 === $disabled_time ) {
if ( time() < (int) $disabled_time ) {
Conf::cls()->update_confs( [ Base::DEBUG_TMP_DISABLE => 0 ] );
* Ensure log directory exists and move legacy logs into it.
private function _maybe_init_folder() {
if ( file_exists( self::$log_path_prefix . 'index.php' ) ) {
File::save( self::$log_path_prefix . 'index.php', '<?php // Silence is golden.', true );
$logs = [ 'debug', 'debug.purge', 'crawler' ];
foreach ( $logs as $log ) {
$old_path = LSCWP_CONTENT_DIR . '/' . $log . '.log';
$new_path = $this->path( $log );
if ( file_exists( $old_path ) && ! file_exists( $new_path ) ) {
// phpcs:ignore WordPress.WP.AlternativeFunctions.rename_rename -- Moving legacy log files during migration
rename( $old_path, $new_path );
* Get absolute path for a log type.
* @param string $type Log type (debug|purge|crawler).
public function path( $type ) {
return self::$log_path_prefix . self::FilePath( $type );
* Get fixed filename for a log type.
* @param string $type Log type (debug|debug.purge|crawler).
public static function FilePath( $type ) {
if ( 'debug.purge' === $type ) {
$key = defined( 'AUTH_KEY' ) ? AUTH_KEY : md5( __FILE__ );
$rand = substr( md5( substr( $key, -16 ) ), -16 );
return $type . $rand . '.log';
* Write end-of-request markers and response timing.
public static function ended() {
$headers = headers_list();
foreach ( $headers as $key => $header ) {
if ( 0 === stripos( $header, 'Set-Cookie' ) ) {
unset( $headers[ $key ] );
self::debug( 'Response headers', $headers );
$elapsed_time = number_format( ( microtime( true ) - LSCWP_TS_0 ) * 1000, 2 );
self::debug( "End response\n--------------------------------------------------Duration: " . $elapsed_time . " ms------------------------------\n" );
* Run beta test upgrade. Accepts a direct ZIP URL or attempts to derive one.
* @param string|false $zip ZIP URL or false to read from request.
public function beta_test( $zip = false ) {
// phpcs:ignore WordPress.Security.NonceVerification.Recommended
if ( empty( $_REQUEST[ self::BETA_TEST_URL ] ) ) {
// phpcs:ignore WordPress.Security.NonceVerification.Recommended
$zip = sanitize_text_field( wp_unslash( $_REQUEST[ self::BETA_TEST_URL ] ) );
if ( self::BETA_TEST_URL_WP !== $zip ) {
if ( 'latest' === $zip ) {
$zip = self::BETA_TEST_URL_WP;
$zip = $this->_package_zip( $zip );
self::debug( '[Debug2] ❌ No ZIP file' );
self::debug( '[Debug2] ZIP file ' . $zip );
$update_plugins = get_site_transient( 'update_plugins' );
if ( ! is_object( $update_plugins ) ) {
$update_plugins = new \stdClass();
$plugin_info = new \stdClass();
$plugin_info->new_version = Core::VER;
$plugin_info->slug = Core::PLUGIN_NAME;
$plugin_info->plugin = Core::PLUGIN_FILE;
$plugin_info->package = $zip;
$plugin_info->url = 'https://wordpress.org/plugins/litespeed-cache/';
$update_plugins->response[ Core::PLUGIN_FILE ] = $plugin_info;
set_site_transient( 'update_plugins', $update_plugins );
Activation::cls()->upgrade();
* Resolve a GitHub commit-ish into a downloadable ZIP URL via QC API.
* @param string $commit Commit hash/branch/tag.
private function _package_zip( $commit ) {
$res = Cloud::get( Cloud::API_BETA_TEST, $data );
if ( empty( $res['zip'] ) ) {
* Write purge headers into a dedicated purge log.
* @param string $purge_header The Purge header value.
public static function log_purge( $purge_header ) {
if ( ! defined( 'LSCWP_LOG' ) && ! defined( 'LSCWP_LOG_BYPASS_NOTADMIN' ) ) {
$purge_file = self::cls()->path( 'purge' );
self::cls()->_init_request( $purge_file );
$msg = $purge_header . self::_backtrace_info( 6 );
File::append( $purge_file, self::format_message( $msg ) );
* Initialize logging for current request if enabled.
if ( defined( 'LSCWP_LOG' ) ) {
$debug = $this->conf( Base::O_DEBUG );
if ( Base::VAL_ON2 === $debug ) {
if ( ! $this->cls( 'Router' )->is_admin_ip() ) {
defined( 'LSCWP_LOG_BYPASS_NOTADMIN' ) || define( 'LSCWP_LOG_BYPASS_NOTADMIN', true );
* Check if hit URI includes/excludes
* This is after LSCWP_LOG_BYPASS_NOTADMIN to make `log_purge()` still work
$list = $this->conf( Base::O_DEBUG_INC );
$request_uri = isset( $_SERVER['REQUEST_URI'] ) ? sanitize_text_field( wp_unslash( $_SERVER['REQUEST_URI'] ) ) : '';
$result = Utility::str_hit_array( $request_uri, $list );
$list = $this->conf( Base::O_DEBUG_EXC );
$request_uri = isset( $_SERVER['REQUEST_URI'] ) ? sanitize_text_field( wp_unslash( $_SERVER['REQUEST_URI'] ) ) : '';
$result = Utility::str_hit_array( $request_uri, $list );
if ( ! defined( 'LSCWP_LOG' ) ) {
define( 'LSCWP_LOG', true );
* Create the initial log record with request context.
* @param string|null $log_file Optional specific log file path.
private function _init_request( $log_file = null ) {
$log_file = self::$log_path;
// Rotate if exceeding configured size (MiB).
$log_file_size = (int) $this->conf( Base::O_DEBUG_FILESIZE );
if ( file_exists( $log_file ) && filesize( $log_file ) > $log_file_size * 1000000 ) {
File::save( $log_file, '' );
// Add extra spacing if last write was > 2 seconds ago.
if ( file_exists( $log_file ) && ( time() - filemtime( $log_file ) ) > 2 ) {
File::append( $log_file, "\n\n\n\n" );
if ( 'cli' === PHP_SAPI ) {
'HTTP_ACCEPT_ENCODING' => '',
'LSCACHE_VARY_COOKIE' => '',
'LSCACHE_VARY_VALUE' => '',
'ESI_CONTENT_TYPE' => '',
$server = array_merge($servervars, $_SERVER);
if ( isset( $_SERVER['HTTPS'] ) && 'on' === $_SERVER['HTTPS'] ) {
$server['SERVER_PROTOCOL'] .= ' (HTTPS) ';
$param = sprintf('💓 ------%s %s %s', $server['REQUEST_METHOD'], $server['SERVER_PROTOCOL'], strtok($server['REQUEST_URI'], '?'));
$qs = !empty($server['QUERY_STRING']) ? $server['QUERY_STRING'] : '';
if ( $this->conf( Base::O_DEBUG_COLLAPSE_QS ) ) {
$qs = $this->_omit_long_message( $qs );
$params[] = 'Query String: ' . $qs;
if ( ! empty( $server['HTTP_REFERER'] ) ) {
$params[] = 'HTTP_REFERER: ' . $this->_omit_long_message( $server['HTTP_REFERER'] );
if ( defined( 'LSCWP_LOG_MORE' ) ) {
$params[] = 'User Agent: ' . $this->_omit_long_message( $server['HTTP_USER_AGENT'] );
$params[] = 'Accept: ' . $server['HTTP_ACCEPT'];
$params[] = 'Accept Encoding: ' . $server['HTTP_ACCEPT_ENCODING'];
if ( isset( $_COOKIE['_lscache_vary'] ) ) {
$params[] = 'Cookie _lscache_vary: ' . sanitize_text_field( wp_unslash( $_COOKIE['_lscache_vary'] ) );
if ( defined( 'LSCWP_LOG_MORE' ) ) {
$params[] = 'X-LSCACHE: ' . ( ! empty( $server['X-LSCACHE'] ) ? 'true' : 'false' );
if ( $server['LSCACHE_VARY_COOKIE'] ) {
$params[] = 'LSCACHE_VARY_COOKIE: ' . $server['LSCACHE_VARY_COOKIE'];
if ( $server['LSCACHE_VARY_VALUE'] ) {
$params[] = 'LSCACHE_VARY_VALUE: ' . $server['LSCACHE_VARY_VALUE'];
if ( $server['ESI_CONTENT_TYPE'] ) {
$params[] = 'ESI_CONTENT_TYPE: ' . $server['ESI_CONTENT_TYPE'];
$request = array_map( __CLASS__ . '::format_message', $params );
File::append( $log_file, $request );
* Trim long message to keep logs compact.
* @param string $msg Message.
private function _omit_long_message( $msg ) {
if ( strlen( $msg ) > 53 ) {
$msg = substr( $msg, 0, 53 ) . '...';
* Format a single log line with timestamp and prefix.
* @param string $msg Message to log.
* @return string Formatted line.
private static function format_message( $msg ) {
if ( ! defined( 'LSCWP_LOG_TAG' ) ) {
if ( ! isset( self::$_prefix ) ) {
if ( 'cli' === PHP_SAPI ) {
if ( isset( $_SERVER['USER'] ) ) {
$addr .= sanitize_text_field( wp_unslash( $_SERVER['USER'] ) );
} elseif ( ! empty( $_SERVER['HTTP_X_FORWARDED_FOR'] ) ) {
$addr .= sanitize_text_field( wp_unslash( $_SERVER['HTTP_X_FORWARDED_FOR'] ) );
$ip = isset( $_SERVER['REMOTE_ADDR'] ) ? sanitize_text_field( wp_unslash( $_SERVER['REMOTE_ADDR'] ) ) : '';
$port = isset( $_SERVER['REMOTE_PORT'] ) ? sanitize_text_field( wp_unslash( $_SERVER['REMOTE_PORT'] ) ) : '';
self::$_prefix = sprintf( ' [%s %s %s] ', $addr, LSCWP_LOG_TAG, Str::rrand( 3 ) );
list( $usec, $sec ) = explode( ' ', microtime() );
// Use gmdate to avoid tz-related warnings; apply offset if defined.
$ts = gmdate( 'm/d/y H:i:s', (int) $sec + ( defined( 'LITESPEED_TIME_OFFSET' ) ? (int) LITESPEED_TIME_OFFSET : 0 ) );
return $ts . substr( $usec, 1, 4 ) . self::$_prefix . $msg . "\n";
* @param string $msg Message to write.
* @param int|array $backtrace_limit Depth for backtrace or payload to append.