File Manager

Editing File: /home/maglabs/realtor/wp-content/plugins/woocommerce/src/Internal/Admin/Logging/FileV2/File.php

<?php
declare( strict_types = 1 );

namespace Automattic\WooCommerce\Internal\Admin\Logging\FileV2;

use Automattic\Jetpack\Constants;
use Automattic\WooCommerce\Internal\Utilities\FilesystemUtil;
use Exception;

/**
 * File class.
 *
 * An object representation of a single log file.
 */
class File {
	/**
	 * The absolute path of the file.
	 *
	 * @var string
	 */
	protected $path;

/**
	 * The source property of the file, derived from the filename.
	 *
	 * @var string
	 */
	protected $source = '';

/**
	 * The 0-based increment of the file, if it has been rotated. Derived from the filename. Can only be 0-9.
	 *
	 * @var int|null
	 */
	protected $rotation;

/**
	 * The date the file was created, as a Unix timestamp, derived from the filename.
	 *
	 * @var int
	 */
	protected $created = 0;

/**
	 * The hash property of the file, derived from the filename.
	 *
	 * @var string
	 */
	protected $hash = '';

/**
	 * The file's resource handle when it is open.
	 *
	 * @var resource
	 */
	protected $stream;

/**
	 * Class File
	 *
	 * @param string $path The absolute path of the file.
	 */
	public function __construct( $path ) {
		$this->path = $path;
		$this->ingest_path();
	}

/**
	 * Make sure open streams are closed.
	 */
	public function __destruct() {
		if ( is_resource( $this->stream ) ) {
			// phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_read_fclose -- No suitable alternative.
			fclose( $this->stream );
		}
	}

/**
	 * Parse a path to a log file to determine if it uses the standard filename structure and various properties.
	 *
	 * This makes assumptions about the structure of the log file's name. Using `-` to separate the name into segments,
	 *  if there are at least 5 segments, it assumes that the last segment is the hash, and the three segments before
	 *  that make up the date when the file was created in YYYY-MM-DD format. Any segments left after that are the
	 *  "source" that generated the log entries. If the filename doesn't have enough segments, it falls back to the
	 *  source and the hash both being the entire filename, and using the inode change time as the creation date.
	 *
	 *  Example:
	 *      my-custom-plugin.2-2025-01-01-a1b2c3d4e5f.log
	 *            |          |       |         |
	 *    'my-custom-plugin' | '2025-01-01'    |
	 *         (source)      |   (created)     |
	 *                      '2'          'a1b2c3d4e5f'
	 *                  (rotation)           (hash)
	 *
	 * @param string $path The full path of the log file.
	 *
	 * @return array {
	 *     @type string   $dirname   The directory structure containing the file. See pathinfo().
	 *     @type string   $basename  The filename with extension. See pathinfo().
	 *     @type string   $extension The file extension. See pathinfo().
	 *     @type string   $filename  The filename without extension. See pathinfo().
	 *     @type string   $source    The source of the log entries contained in the file.
	 *     @type int|null $rotation  The 0-based incremental rotation marker, if the file has been rotated.
	 *                               Should only be a single digit.
	 *     @type int      $created   The date the file was created, as a Unix timestamp.
	 *     @type string   $hash      The hash suffix of the filename that protects from direct access.
	 *     @type string   $file_id   The public ID of the log file (filename without the hash).
	 * }
	 */
	public static function parse_path( string $path ): array {
		$defaults = array(
			'dirname'   => '',
			'basename'  => '',
			'extension' => '',
			'filename'  => '',
			'source'    => '',
			'rotation'  => null,
			'created'   => 0,
			'hash'      => '',
			'file_id'   => '',
		);

$parsed = array_merge( $defaults, pathinfo( $path ) );

$segments  = explode( '-', $parsed['filename'] );
		$timestamp = strtotime( implode( '-', array_slice( $segments, -4, 3 ) ) );

if ( count( $segments ) >= 5 && false !== $timestamp ) {
			$parsed['source']  = implode( '-', array_slice( $segments, 0, -4 ) );
			$parsed['created'] = $timestamp;
			$parsed['hash']    = array_slice( $segments, -1 )[0];
		} else {
			$parsed['source'] = implode( '-', $segments );
		}

$rotation_marker = strrpos( $parsed['source'], '.', -1 );
		if ( false !== $rotation_marker ) {
			$rotation = substr( $parsed['source'], -1 );
			if ( is_numeric( $rotation ) ) {
				$parsed['rotation'] = intval( $rotation );
			}

$parsed['source'] = substr( $parsed['source'], 0, $rotation_marker );
		}

$parsed['file_id'] = static::generate_file_id(
			$parsed['source'],
			$parsed['rotation'],
			$parsed['created']
		);

return $parsed;
	}

/**
	 * Generate a public ID for a log file based on its properties.
	 *
	 * The file ID is the basename of the file without the hash part. It allows us to identify a file without revealing
	 * its full name in the filesystem, so that it's difficult to access the file directly with an HTTP request.
	 *
	 * @param string   $source   The source of the log entries contained in the file.
	 * @param int|null $rotation Optional. The 0-based incremental rotation marker, if the file has been rotated.
	 *                           Should only be a single digit.
	 * @param int      $created  Optional. The date the file was created, as a Unix timestamp.
	 *
	 * @return string
	 */
	public static function generate_file_id( string $source, ?int $rotation = null, int $created = 0 ): string {
		$file_id = static::sanitize_source( $source );

if ( ! is_null( $rotation ) ) {
			$file_id .= '.' . $rotation;
		}

if ( $created > 0 ) {
			$file_id .= '-' . gmdate( 'Y-m-d', $created );
		}

return $file_id;
	}

/**
	 * Generate a hash to use as the suffix on a log filename.
	 *
	 * @param string $file_id A file ID (file basename without the hash).
	 *
	 * @return string
	 */
	public static function generate_hash( string $file_id ): string {
		$key = Constants::get_constant( 'AUTH_SALT' ) ?? 'wc-logs';

return hash_hmac( 'md5', $file_id, $key );
	}

/**
	 * Sanitize the source property of a log file.
	 *
	 * @param string $source The source of the log entries contained in the file.
	 *
	 * @return string
	 */
	public static function sanitize_source( string $source ): string {
		return sanitize_file_name( $source );
	}

/**
	 * Parse the log file path and assign various properties to this class instance.
	 *
	 * @return void
	 */
	protected function ingest_path(): void {
		$parsed_path    = static::parse_path( $this->path );
		$this->source   = $parsed_path['source'];
		$this->rotation = $parsed_path['rotation'];
		$this->created  = $parsed_path['created'];
		$this->hash     = $parsed_path['hash'];
	}

/**
	 * Check if the filename structure is in the expected format.
	 *
	 * @see parse_path().
	 *
	 * @return bool
	 */
	public function has_standard_filename(): bool {
		return ! ! $this->get_hash();
	}

/**
	 * Check if the file represented by the class instance is a file and is readable.
	 *
	 * @return bool
	 */
	public function is_readable(): bool {
		try {
			$filesystem  = FilesystemUtil::get_wp_filesystem();
			$is_readable = $filesystem->is_file( $this->path ) && $filesystem->is_readable( $this->path );
		} catch ( Exception $exception ) {
			return false;
		}

return $is_readable;
	}

/**
	 * Check if the file represented by the class instance is a file and is writable.
	 *
	 * @return bool
	 */
	public function is_writable(): bool {
		try {
			$filesystem  = FilesystemUtil::get_wp_filesystem();
			$is_writable = $filesystem->is_file( $this->path ) && $filesystem->is_writable( $this->path );
		} catch ( Exception $exception ) {
			return false;
		}

return $is_writable;
	}

/**
	 * Open a read-only stream for this file.
	 *
	 * @return resource|false
	 */
	public function get_stream() {
		if ( ! $this->is_readable() ) {
			return false;
		}

if ( ! is_resource( $this->stream ) ) {
			// phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_read_fopen -- No suitable alternative.
			$this->stream = fopen( $this->path, 'rb' );
		}

return $this->stream;
	}

/**
	 * Close the stream for this file.
	 *
	 * The stream will also close automatically when the class instance destructs, but this can be useful for
	 * avoiding having a large number of streams open simultaneously.
	 *
	 * @return bool
	 */
	public function close_stream(): bool {
		// phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_read_fclose -- No suitable alternative.
		return fclose( $this->stream );
	}

/**
	 * Get the full absolute path of the file.
	 *
	 * @return string
	 */
	public function get_path(): string {
		return $this->path;
	}

/**
	 * Get the name of the file, with extension, but without full path.
	 *
	 * @return string
	 */
	public function get_basename(): string {
		return basename( $this->path );
	}

/**
	 * Get the file's source property.
	 *
	 * @return string
	 */
	public function get_source(): string {
		return $this->source;
	}

/**
	 * Get the file's rotation property.
	 *
	 * @return int|null
	 */
	public function get_rotation(): ?int {
		return $this->rotation;
	}

/**
	 * Get the file's hash property.
	 *
	 * @return string
	 */
	public function get_hash(): string {
		return $this->hash;
	}

/**
	 * Get the file's public ID.
	 *
	 * @return string
	 */
	public function get_file_id(): string {
		$created = 0;
		if ( $this->has_standard_filename() ) {
			$created = $this->get_created_timestamp();
		}

$file_id = static::generate_file_id(
			$this->get_source(),
			$this->get_rotation(),
			$created
		);

return $file_id;
	}

/**
	 * Get the file's created property.
	 *
	 * @return int
	 */
	public function get_created_timestamp(): int {
		if ( ! $this->created && $this->is_readable() ) {
			$this->created = filectime( $this->path );
		}

return $this->created;
	}

/**
	 * Get the time of the last modification of the file, as a Unix timestamp. Or false if the file isn't readable.
	 *
	 * @return int|false
	 */
	public function get_modified_timestamp() {
		try {
			$filesystem = FilesystemUtil::get_wp_filesystem();
			$timestamp  = $filesystem->mtime( $this->path );
		} catch ( Exception $exception ) {
			return false;
		}

return $timestamp;
	}

/**
	 * Get the size of the file in bytes. Or false if the file isn't readable.
	 *
	 * @return int|false
	 */
	public function get_file_size() {
		try {
			$filesystem = FilesystemUtil::get_wp_filesystem();

if ( ! $filesystem->is_readable( $this->path ) ) {
				return false;
			}

$size = $filesystem->size( $this->path );
		} catch ( Exception $exception ) {
			return false;
		}

return $size;
	}

/**
	 * Create and set permissions on the file.
	 *
	 * @return bool
	 */
	protected function create(): bool {
		try {
			$filesystem = FilesystemUtil::get_wp_filesystem();
			$created    = $filesystem->touch( $this->path );
			$modded     = $filesystem->chmod( $this->path );
		} catch ( Exception $exception ) {
			return false;
		}

return $created && $modded;
	}

/**
	 * Write content to the file, appending it to the end.
	 *
	 * @param string $text The content to add to the file.
	 *
	 * @return bool
	 */
	public function write( string $text ): bool {
		if ( '' === $text ) {
			return false;
		}

if ( ! $this->is_writable() ) {
			$created = $this->create();

if ( ! $created || ! $this->is_writable() ) {
				return false;
			}
		}

// Ensure content ends with a line ending.
		$eol_pos = strrpos( $text, PHP_EOL );
		if ( false === $eol_pos || strlen( $text ) !== $eol_pos + 1 ) {
			$text .= PHP_EOL;
		}

// phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_read_fopen -- No suitable alternative.
		$resource = fopen( $this->path, 'ab' );

mbstring_binary_safe_encoding();
		// phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_read_fwrite -- No suitable alternative.
		$bytes_written = fwrite( $resource, $text );
		reset_mbstring_encoding();

// phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_read_fclose -- No suitable alternative.
		fclose( $resource );

if ( strlen( $text ) !== $bytes_written ) {
			return false;
		}

return true;
	}

/**
	 * Rename this file with an incremented rotation number.
	 *
	 * @return bool True if the file was successfully rotated.
	 */
	public function rotate(): bool {
		if ( ! $this->is_writable() ) {
			return false;
		}

$created = 0;
		if ( $this->has_standard_filename() ) {
			$created = $this->get_created_timestamp();
		}

if ( is_null( $this->get_rotation() ) ) {
			$new_rotation = 0;
		} else {
			$new_rotation = $this->get_rotation() + 1;
		}

$new_file_id = static::generate_file_id( $this->get_source(), $new_rotation, $created );

$search  = array( $this->get_file_id() );
		$replace = array( $new_file_id );
		if ( $this->has_standard_filename() ) {
			$search[]  = $this->get_hash();
			$replace[] = static::generate_hash( $new_file_id );
		}

$old_filename = $this->get_basename();
		$new_filename = str_replace( $search, $replace, $old_filename );
		$new_path     = str_replace( $old_filename, $new_filename, $this->path );

try {
			$filesystem = FilesystemUtil::get_wp_filesystem();
			$moved      = $filesystem->move( $this->path, $new_path, true );
		} catch ( Exception $exception ) {
			return false;
		}

if ( ! $moved ) {
			return false;
		}

$this->path = $new_path;
		$this->ingest_path();

return $this->is_readable();
	}

/**
	 * Delete the file from the filesystem.
	 *
	 * @return bool True on success, false on failure.
	 */
	public function delete(): bool {
		try {
			$filesystem = FilesystemUtil::get_wp_filesystem();
			$deleted    = $filesystem->delete( $this->path, false, 'f' );
		} catch ( Exception $exception ) {
			return false;
		}

return $deleted;
	}
}

Back to Directory File Manager