<?php
/**
* PHPCSUtils, utility functions and classes for PHP_CodeSniffer sniff developers.
*
* @package PHPCSUtils
* @copyright 2019-2024 PHPCSUtils Contributors
* @license https://opensource.org/licenses/LGPL-3.0 LGPL3
* @link https://github.com/PHPCSStandards/PHPCSUtils
*/
namespace PHPCSUtils\Utils;
use PHP_CodeSniffer\Files\File;
use PHPCSUtils\Utils\TextStrings;
/**
* Helper functions for working with arbitrary file/directory paths.
*
* Typically, these methods are useful for sniffs which examine the name of the file
* under scan and need to act differently depending on the path in which the file
* under scan is found.
*
* @see \PHP_CodeSniffer\Files\getFilename Retrieves the absolute path to the file under scan.
* @see \PHPCSUtils\BackCompat\getCommandLineData Can be used to retrieve "basepath" setting.
*
* @since 1.1.0
*/
final class FilePath
{
/**
* Get the file name of the current file under scan.
*
* In contrast to the PHPCS native {@see \PHP_CodeSniffer\Files\getFilename()} method,
* the name returned by this method will have been normalized.
*
* @since 1.1.0
*
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
*
* @return string The file name without surrounding quotes and with forward slashes
* as directory separators.
*/
public static function getName(File $phpcsFile)
{
// Usage of `stripQuotes` is to ensure `stdin_path` passed by IDEs does not include quotes.
$fileName = TextStrings::stripQuotes($phpcsFile->getFileName());
if ($fileName !== 'STDIN') {
$fileName = self::normalizeAbsolutePath($fileName);
}
return \trim($fileName);
}
/**
* Check whether the input was received via STDIN.
*
* @since 1.1.0
*
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
*
* @return bool
*/
public static function isStdin(File $phpcsFile)
{
return (self::getName($phpcsFile) === 'STDIN');
}
/**
* Normalize an absolute path to forward slashes and to include a trailing slash for directories.
*
* @since 1.1.0
*
* @param string $path Absolute file or directory path.
*
* @return string
*/
public static function normalizeAbsolutePath($path)
{
return self::trailingSlashIt(self::normalizeDirectorySeparators($path));
}
/**
* Normalize all directory separators to be a forward slash.
*
* {@internal We cannot rely on the OS on which PHPCS is being run to determine the
* the expected slashes, as the file name could also come from a text string in a
* tokenized file or have been set by an IDE...}
*
* @since 1.1.0
*
* @param string $path File or directory path.
*
* @return string
*/
public static function normalizeDirectorySeparators($path)
{
return \strtr((string) $path, '\\', '/');
}
/**
* Ensure that a directory path ends on a trailing slash.
*
* Includes safeguard against adding a trailing slash to path ending on a file name.
*
* @since 1.1.0
*
* @param string $path File or directory path.
*
* @return string
*/
public static function trailingSlashIt($path)
{
if (\is_string($path) === false || $path === '') {
return '';
}
$extension = '';
$lastChar = \substr($path, -1);
if ($lastChar !== '/' && $lastChar !== '\\') {
// This may be a file, check if it has a file extension.
$extension = \pathinfo($path, \PATHINFO_EXTENSION);
}
if ($extension !== '') {
return $path;
}
return \rtrim((string) $path, '/\\') . '/';
}
/**
* Check whether one file/directory path starts with another path.
*
* Recommended to be used only when both paths are absolute.
*
* Note: this function does not normalize paths prior to comparing them.
* If this is needed, normalization should be done prior to passing
* the `$haystack` and `$needle` parameters to this function.
*
* Also note that this function does a case-sensitive comparison as most OS-es are case-sensitive.
*
* @since 1.1.0
*
* @param string $haystack Path to examine.
* @param string $needle Partial path which the haystack path should start with.
*
* @return bool
*/
public static function startsWith($haystack, $needle)
{
return (\strncmp($haystack, $needle, \strlen($needle)) === 0);
}
}