Merge pull request #572 from PHPCSStandards/utils/new-fileinfo-class

✨ New FileInfo utility class

PHPCSUtils/Utils/FileInfo.php

@@ -0,0 +1,92 @@
+<?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;
+
+/**
+ * Utility functions to retrieve information about the file under scan.
+ *
+ * @since 1.1.0
+ */
+final class FileInfo
+{
+
+    /**
+     * List of supported BOM definitions.
+     *
+     * Use encoding names as keys and hex BOM representations as values.
+     *
+     * @since 1.1.0
+     *
+     * @var array<string, string>
+     */
+    private static $bomDefinitions = [
+        'UTF-8'       => 'efbbbf',
+        'UTF-16 (BE)' => 'feff',
+        'UTF-16 (LE)' => 'fffe',
+    ];
+
+    /**
+     * Determine whether the file under scan has a byte-order mark at the start.
+     *
+     * Inspired by similar code being used in a couple of PHPCS native sniffs.
+     *
+     * @since 1.1.0
+     *
+     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
+     *
+     * @return string|false Name of the type of BOM found or FALSE when the file does not start with a BOM.
+     */
+    public static function hasByteOrderMark(File $phpcsFile)
+    {
+        $tokens = $phpcsFile->getTokens();
+
+        if ($tokens[0]['code'] !== \T_INLINE_HTML) {
+            return false;
+        }
+
+        foreach (self::$bomDefinitions as $bomName => $expectedBomHex) {
+            $bomByteLength = (int) (\strlen($expectedBomHex) / 2);
+            $htmlBomHex    = \bin2hex(\substr($tokens[0]['content'], 0, $bomByteLength));
+            if ($htmlBomHex === $expectedBomHex) {
+                return $bomName;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Determine whether the file under scan has a shebang line at the start.
+     *
+     * @since 1.1.0
+     *
+     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
+     *
+     * @return bool
+     */
+    public static function hasSheBang(File $phpcsFile)
+    {
+        $tokens = $phpcsFile->getTokens();
+        if ($tokens[0]['code'] !== \T_INLINE_HTML) {
+            return false;
+        }
+
+        $start            = 0;
+        $hasByteOrderMark = self::hasByteOrderMark($phpcsFile);
+        if ($hasByteOrderMark !== false) {
+            $start = (int) (\strlen(self::$bomDefinitions[$hasByteOrderMark]) / 2);
+        }
+
+        return (\substr($tokens[0]['content'], $start, 2) === '#!');
+    }
+}

Tests/Utils/FileInfo/HasByteOrderMarkAnsiTest.inc

@@ -0,0 +1,3 @@
+<?php
+
+echo 'This file does not have a byte order mark and uses ANSI encoding';

Tests/Utils/FileInfo/HasByteOrderMarkAnsiTest.php

@@ -0,0 +1,35 @@
+<?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\Tests\Utils\FileInfo;
+
+use PHPCSUtils\TestUtils\UtilityMethodTestCase;
+use PHPCSUtils\Utils\FileInfo;
+
+/**
+ * Tests for the \PHPCSUtils\Utils\FileInfo::hasByteOrderMark() method.
+ *
+ * @covers \PHPCSUtils\Utils\FileInfo::hasByteOrderMark
+ *
+ * @since 1.1.0
+ */
+final class HasByteOrderMarkAnsiTest extends UtilityMethodTestCase
+{
+
+    /**
+     * Test whether a file without byte order mark at the start of the file is correctly recognized.
+     *
+     * @return void
+     */
+    public function testHasByteOrderMark()
+    {
+        $this->assertFalse(FileInfo::hasByteOrderMark(self::$phpcsFile));
+    }
+}

Tests/Utils/FileInfo/HasByteOrderMarkUTF16BETest.php

@@ -0,0 +1,35 @@
+<?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\Tests\Utils\FileInfo;
+
+use PHPCSUtils\TestUtils\UtilityMethodTestCase;
+use PHPCSUtils\Utils\FileInfo;
+
+/**
+ * Tests for the \PHPCSUtils\Utils\FileInfo::hasByteOrderMark() method.
+ *
+ * @covers \PHPCSUtils\Utils\FileInfo::hasByteOrderMark
+ *
+ * @since 1.1.0
+ */
+final class HasByteOrderMarkUTF16BETest extends UtilityMethodTestCase
+{
+
+    /**
+     * Test whether a byte order mark at the start of the file is correctly recognized.
+     *
+     * @return void
+     */
+    public function testHasByteOrderMark()
+    {
+        $this->assertSame('UTF-16 (BE)', FileInfo::hasByteOrderMark(self::$phpcsFile));
+    }
+}

Tests/Utils/FileInfo/HasByteOrderMarkUTF16LETest.php

@@ -0,0 +1,35 @@
+<?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\Tests\Utils\FileInfo;
+
+use PHPCSUtils\TestUtils\UtilityMethodTestCase;
+use PHPCSUtils\Utils\FileInfo;
+
+/**
+ * Tests for the \PHPCSUtils\Utils\FileInfo::hasByteOrderMark() method.
+ *
+ * @covers \PHPCSUtils\Utils\FileInfo::hasByteOrderMark
+ *
+ * @since 1.1.0
+ */
+final class HasByteOrderMarkUTF16LETest extends UtilityMethodTestCase
+{
+
+    /**
+     * Test whether a byte order mark at the start of the file is correctly recognized.
+     *
+     * @return void
+     */
+    public function testHasByteOrderMark()
+    {
+        $this->assertSame('UTF-16 (LE)', FileInfo::hasByteOrderMark(self::$phpcsFile));
+    }
+}

Tests/Utils/FileInfo/HasByteOrderMarkUTF8NoBomTest.inc

@@ -0,0 +1,3 @@
+<?php
+
+echo 'This file does not have a byte order mark and uses UTF-8 encoding';

Tests/Utils/FileInfo/HasByteOrderMarkUTF8NoBomTest.php

@@ -0,0 +1,35 @@
+<?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\Tests\Utils\FileInfo;
+
+use PHPCSUtils\TestUtils\UtilityMethodTestCase;
+use PHPCSUtils\Utils\FileInfo;
+
+/**
+ * Tests for the \PHPCSUtils\Utils\FileInfo::hasByteOrderMark() method.
+ *
+ * @covers \PHPCSUtils\Utils\FileInfo::hasByteOrderMark
+ *
+ * @since 1.1.0
+ */
+final class HasByteOrderMarkUTF8NoBomTest extends UtilityMethodTestCase
+{
+
+    /**
+     * Test whether a file without byte order mark at the start of the file is correctly recognized.
+     *
+     * @return void
+     */
+    public function testHasByteOrderMark()
+    {
+        $this->assertFalse(FileInfo::hasByteOrderMark(self::$phpcsFile));
+    }
+}

Tests/Utils/FileInfo/HasByteOrderMarkUTF8WithBomTest.inc

@@ -0,0 +1,3 @@
+<?php
+
+echo 'This file does has a UTF-8 byte order mark';

Tests/Utils/FileInfo/HasByteOrderMarkUTF8WithBomTest.php

@@ -0,0 +1,35 @@
+<?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\Tests\Utils\FileInfo;
+
+use PHPCSUtils\TestUtils\UtilityMethodTestCase;
+use PHPCSUtils\Utils\FileInfo;
+
+/**
+ * Tests for the \PHPCSUtils\Utils\FileInfo::hasByteOrderMark() method.
+ *
+ * @covers \PHPCSUtils\Utils\FileInfo::hasByteOrderMark
+ *
+ * @since 1.1.0
+ */
+final class HasByteOrderMarkUTF8WithBomTest extends UtilityMethodTestCase
+{
+
+    /**
+     * Test whether a byte order mark at the start of the file is correctly recognized.
+     *
+     * @return void
+     */
+    public function testHasByteOrderMark()
+    {
+        $this->assertSame('UTF-8', FileInfo::hasByteOrderMark(self::$phpcsFile));
+    }
+}

Tests/Utils/FileInfo/HasSheBangEnvPHPTest.inc

@@ -0,0 +1,4 @@
+#!/usr/bin/env php
+<?php
+
+echo 'This file has a PHP shebang line';

Tests/Utils/FileInfo/HasSheBangEnvPHPTest.php

@@ -0,0 +1,35 @@
+<?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\Tests\Utils\FileInfo;
+
+use PHPCSUtils\TestUtils\UtilityMethodTestCase;
+use PHPCSUtils\Utils\FileInfo;
+
+/**
+ * Tests for the \PHPCSUtils\Utils\FileInfo::hasSheBang() method.
+ *
+ * @covers \PHPCSUtils\Utils\FileInfo::hasSheBang
+ *
+ * @since 1.1.0
+ */
+final class HasSheBangEnvPHPTest extends UtilityMethodTestCase
+{
+
+    /**
+     * Test whether a byte order mark at the start of the file is correctly recognized.
+     *
+     * @return void
+     */
+    public function testHasSheBang()
+    {
+        $this->assertTrue(FileInfo::hasSheBang(self::$phpcsFile));
+    }
+}

Tests/Utils/FileInfo/HasSheBangNoneTest.inc

@@ -0,0 +1,3 @@
+<?php
+
+echo 'This file does not have a PHP shebang line';

Tests/Utils/FileInfo/HasSheBangNoneTest.php

@@ -0,0 +1,35 @@
+<?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\Tests\Utils\FileInfo;
+
+use PHPCSUtils\TestUtils\UtilityMethodTestCase;
+use PHPCSUtils\Utils\FileInfo;
+
+/**
+ * Tests for the \PHPCSUtils\Utils\FileInfo::hasSheBang() method.
+ *
+ * @covers \PHPCSUtils\Utils\FileInfo::hasSheBang
+ *
+ * @since 1.1.0
+ */
+final class HasSheBangNoneTest extends UtilityMethodTestCase
+{
+
+    /**
+     * Test whether a byte order mark at the start of the file is correctly recognized.
+     *
+     * @return void
+     */
+    public function testHasSheBang()
+    {
+        $this->assertFalse(FileInfo::hasSheBang(self::$phpcsFile));
+    }
+}

Tests/Utils/FileInfo/HasSheBangPHPAndUTF8BomTest.inc

@@ -0,0 +1,4 @@
+#!/usr/bin/php
+<?php
+
+echo 'This file has a PHP shebang line and is encoded in UTF-8 with a Byte order mark';