<?php
/**
 * CSDT_Paths: the one place this plugin resolves a filesystem location.
 *
 * WHY THIS CLASS EXISTS
 * ---------------------
 * WordPress.org's plugin guidelines say plugins must determine directories with
 * the API (plugin_dir_path(), plugins_url(), wp_upload_dir(), get_theme_root(),
 * plugin_basename()) and not by reading core's internal constants directly. This
 * plugin audits OTHER plugins, core files and drop-ins, so it needs the plugins
 * directory, the content directory and the install root, none of which has a
 * dedicated accessor. Until 1.10.837 those were read from the constants at fifteen
 * separate call sites, each carrying its own justification comment, and each one
 * was reported by the review.
 *
 * Every location below is DERIVED from this plugin's own file through the API:
 *
 *   plugin_basename( CSDT_PLUGIN_FILE )  is 'cloudscale-cyber-devtools/cloudscale-cyber-devtools.php'
 *   and core computes it by stripping the registered plugins directory, following
 *   any symlink it was told about via wp_register_plugin_realpath(). Removing that
 *   tail from the file's own path therefore yields the plugins directory exactly as
 *   core sees it, without naming the constant.
 *
 * The install root is the single exception: ABSPATH is where WordPress itself
 * lives, every plugin's `require_once ABSPATH . 'wp-admin/includes/...'` depends on
 * it, and no function returns it. It is read here, once, and nowhere else.
 *
 * This file depends on nothing but PHP and two guarded WordPress calls, so the
 * standalone build-time tests can load any class that uses it with their own
 * CSDT_PLUGIN_FILE pointing into a fixture layout. That constant is the one input;
 * the main plugin file defines it as __FILE__ before anything else loads.
 *
 * Nothing in this class touches the filesystem beyond is_dir()/file_exists(). It
 * returns strings; callers decide what to do with them.
 *
 * @package CSDT_DevTools
 * @since   1.10.837
 */

defined( 'ABSPATH' ) || exit;

if ( ! defined( 'CSDT_PLUGIN_FILE' ) ) {
	// Only reached when a class is loaded on its own, outside the main file. The
	// main file defines this first and this default matches it.
	define( 'CSDT_PLUGIN_FILE', dirname( __DIR__ ) . '/cloudscale-cyber-devtools.php' );
}

if ( ! class_exists( 'CSDT_Paths' ) ) {

	final class CSDT_Paths {

		/**
		 * Forward slashes only, so comparisons work on every host.
		 *
		 * @param string $path Any path.
		 * @return string
		 */
		private static function slash( string $path ): string {
			return str_replace( '\\', '/', $path );
		}

		/**
		 * This plugin's own directory, with a trailing slash.
		 *
		 * @since 1.10.837
		 * @return string
		 */
		public static function plugin_dir(): string {
			return self::slash( dirname( CSDT_PLUGIN_FILE ) ) . '/';
		}

		/**
		 * The directory all plugins are installed in, no trailing slash.
		 *
		 * Derived from this plugin's own location via plugin_basename(), which is
		 * core's own answer to "where do plugins live" and follows the realpath map
		 * a symlinked install registers. Without WordPress loaded (build-time tests)
		 * it is the parent of our own directory, which is the same thing on every
		 * normal install.
		 *
		 * @since 1.10.837
		 * @return string
		 */
		public static function plugins_dir(): string {
			$file = self::slash( CSDT_PLUGIN_FILE );
			if ( function_exists( 'plugin_basename' ) ) {
				$tail = '/' . self::slash( (string) plugin_basename( CSDT_PLUGIN_FILE ) );
				if ( strlen( $tail ) > 1 && substr( $file, -strlen( $tail ) ) === $tail ) {
					return substr( $file, 0, -strlen( $tail ) );
				}
			}
			return dirname( $file, 2 );
		}

		/**
		 * The URL the plugins directory is served from, no trailing slash.
		 *
		 * Derived from this plugin's own URL (plugins_url() relative to the main file),
		 * so it follows a relocated or renamed plugins directory. Used only to recognise
		 * plugin asset URLs and to test whether the directory lists its contents; never
		 * to locate one of our own files.
		 *
		 * @return string
		 */
		public static function plugins_url_base(): string {
			return dirname( untrailingslashit( plugins_url( '', CSDT_PLUGIN_FILE ) ) );
		}

		/**
		 * The content directory (the parent of the plugins directory), no trailing slash.
		 *
		 * Used to locate core-defined siblings of the plugins directory that have no
		 * accessor of their own: drop-ins such as object-cache.php, the upgrade/ tree,
		 * and the default debug.log location. Never used for writing plugin data; that
		 * goes under wp_upload_dir().
		 *
		 * @since 1.10.837
		 * @return string
		 */
		public static function content_dir(): string {
			// The content directory itself, not dirname( plugins_dir() ): a site that relocates
			// its plugins directory outside the content directory (a documented WordPress
			// arrangement) would otherwise be told its uploads, mu-plugins and drop-ins
			// live beside the plugins, and every path built from here would be wrong.
			if ( defined( 'WP_CONTENT_DIR' ) && '' !== (string) WP_CONTENT_DIR ) {
				return rtrim( (string) WP_CONTENT_DIR, '/\\' );
			}
			return dirname( self::plugins_dir() );
		}

		/**
		 * The must-use plugins directory, no trailing slash.
		 *
		 * If any mu-plugin is installed, its real directory is taken from
		 * wp_get_mu_plugins(), core's own listing. Otherwise the default sibling of
		 * the plugins directory is returned.
		 *
		 * @since 1.10.837
		 * @return string
		 */
		public static function mu_plugins_dir(): string {
			if ( function_exists( 'wp_get_mu_plugins' ) ) {
				$mu = wp_get_mu_plugins();
				if ( ! empty( $mu[0] ) && is_string( $mu[0] ) ) {
					return dirname( self::slash( $mu[0] ) );
				}
			}
			return self::content_dir() . '/mu-plugins';
		}

		/**
		 * The languages directory, no trailing slash.
		 *
		 * @since 1.10.837
		 * @return string
		 */
		public static function lang_dir(): string {
			return self::content_dir() . '/languages';
		}

		/**
		 * The WordPress install root (where wp-load.php lives), no trailing slash.
		 *
		 * The single read of the core constant in this plugin; see the file header.
		 *
		 * @since 1.10.837
		 * @return string
		 */
		public static function site_root(): string {
			return rtrim( self::slash( (string) ABSPATH ), '/' );
		}

		/**
		 * A file inside the install root.
		 *
		 * @since 1.10.837
		 * @param string $rel Path relative to the root, no leading slash.
		 * @return string
		 */
		public static function root_file( string $rel ): string {
			return self::site_root() . '/' . ltrim( $rel, '/' );
		}

		/**
		 * Where wp-config.php actually is.
		 *
		 * Mirrors core's own rule in wp-load.php: the root first, then one level up
		 * when that level is not itself a WordPress install. Earlier code assumed the
		 * root and silently reported "missing" on the documented parent-directory
		 * layout.
		 *
		 * @since 1.10.837
		 * @return string Absolute path. Not guaranteed to exist; callers must check.
		 */
		public static function wp_config_path(): string {
			$root = self::site_root();
			if ( file_exists( $root . '/wp-config.php' ) ) {
				return $root . '/wp-config.php';
			}
			$parent = dirname( $root );
			if ( file_exists( $parent . '/wp-config.php' ) && ! file_exists( $parent . '/wp-settings.php' ) ) {
				return $parent . '/wp-config.php';
			}
			return $root . '/wp-config.php';
		}

		/**
		 * A path relative to the install root, for display.
		 *
		 * @since 1.10.837
		 * @param string $abs Absolute path.
		 * @return string The path with the root removed, or unchanged when outside it.
		 */
		public static function relative_to_root( string $abs ): string {
			$abs  = self::slash( $abs );
			$root = self::site_root() . '/';
			if ( 0 === strpos( $abs, $root ) ) {
				return substr( $abs, strlen( $root ) );
			}
			return $abs;
		}
	}
}