[!!!][TASK] Introduce type declarations in AbstractDriver

Releases: main Resolves: #101471 Change-Id: I0d633ea2d5dc6daed5e3cd97020d03a2a0749969 Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/80201 Reviewed-by: Christian Kuhn <lolli@schwarzbu.ch> Tested-by: Stefan B�rk <stefan@buerk.tech> Reviewed-by: Stefan B�rk <stefan@buerk.tech> Tested-by: Christian Kuhn <lolli@schwarzbu.ch> Tested-by: core-ci <typo3@b13.com> Reviewed-by: Oliver Klee <typo3-coding@oliverklee.de>
TYPO3 · Jul 28, 2023 · 6a6b59f · 6a6b59f
1 parent 9a38896
commit 6a6b59f
Show file tree

Hide file tree

Showing 4 changed files with 90 additions and 44 deletions.
diff --git a/typo3/sysext/core/Classes/Resource/Driver/AbstractDriver.php b/typo3/sysext/core/Classes/Resource/Driver/AbstractDriver.php
@@ -36,26 +36,27 @@ abstract class AbstractDriver implements DriverInterface
 
     /**
      * The storage uid the driver was instantiated for
-     *
-     * @var int
      */
-    protected $storageUid;
+    protected ?int $storageUid = null;
 
     /**
      * A list of all supported hash algorithms, written all lower case and
      * without any dashes etc. (e.g. sha1 instead of SHA-1)
      * Be sure to set this in inherited classes!
      *
-     * @var array
+     * @phpstan-var list<string>
+     *
+     * @todo: Remove this from this class. Properties of abstract classes MUST NOT be api. If all drivers
+     *        need to implement this, consider creating a new method stub in the DriverInterface or consider
+     *        creating a new SupportedHashAlgorithmsAwareInterface that demands implementations to provide said
+     *        information. Inside this abstract class, this property is useless, however.
      */
-    protected $supportedHashAlgorithms = [];
+    protected array $supportedHashAlgorithms = [];
 
     /**
      * The configuration of this driver
-     *
-     * @var array
      */
-    protected $configuration = [];
+    protected array $configuration = [];
 
     /**
      * Creates this object.
@@ -68,11 +69,8 @@ public function __construct(array $configuration = [])
     /**
      * Checks a fileName for validity. This could be overridden in concrete
      * drivers if they have different file naming rules.
-     *
-     * @param string $fileName
-     * @return bool TRUE if file name is valid
      */
-    protected function isValidFilename($fileName)
+    protected function isValidFilename(string $fileName): bool
     {
         if (str_contains($fileName, '/')) {
             return false;
@@ -102,7 +100,7 @@ public function getCapabilities(): Capabilities
     /**
      * Returns TRUE if this driver has the given capability.
      *
-     * @param Capabilities::CAPABILITY_* $capability
+     * @phpstan-param Capabilities::CAPABILITY_* $capability
      */
     public function hasCapability(int $capability): bool
     {
@@ -116,10 +114,10 @@ public function hasCapability(int $capability): bool
     /**
      * Returns a temporary path for a given file, including the file extension.
      *
-     * @param string $fileIdentifier
-     * @return non-empty-string
+     * @phpstan-param non-empty-string $fileIdentifier
+     * @phpstan-return non-empty-string
      */
-    protected function getTemporaryPathForFile($fileIdentifier)
+    protected function getTemporaryPathForFile(string $fileIdentifier): string
     {
         return GeneralUtility::tempnam('fal-tempfile-', '.' . PathUtility::pathinfo($fileIdentifier, PATHINFO_EXTENSION));
     }
@@ -129,8 +127,8 @@ protected function getTemporaryPathForFile($fileIdentifier)
      * into account. This helps mitigating problems with case-insensitive
      * databases.
      *
-     * @param non-empty-string $identifier
-     * @return non-empty-string
+     * @phpstan-param non-empty-string $identifier
+     * @phpstan-return non-empty-string
      */
     public function hashIdentifier(string $identifier): string
     {
@@ -156,25 +154,24 @@ public function isCaseSensitiveFileSystem(): bool
     /**
      * Makes sure the path given as parameter is valid
      *
-     * @param string $filePath The file path (most times filePath)
-     * @return string
+     * @phpstan-param non-empty-string $filePath The file path (most times filePath)
+     * @phpstan-return non-empty-string
      */
-    abstract protected function canonicalizeAndCheckFilePath($filePath);
+    abstract protected function canonicalizeAndCheckFilePath(string $filePath): string;
 
     /**
      * Makes sure the identifier given as parameter is valid
      *
-     * @param non-empty-string $fileIdentifier The file Identifier
-     * @return non-empty-string
-     * @throws \TYPO3\CMS\Core\Resource\Exception\InvalidPathException
+     * @phpstan-param non-empty-string $fileIdentifier The file Identifier
+     * @phpstan-return non-empty-string
      */
-    abstract protected function canonicalizeAndCheckFileIdentifier($fileIdentifier);
+    abstract protected function canonicalizeAndCheckFileIdentifier(string $fileIdentifier): string;
 
     /**
      * Makes sure the identifier given as parameter is valid
      *
-     * @param string $folderIdentifier The folder identifier
-     * @return string
+     * @phpstan-param non-empty-string $folderIdentifier The folder identifier
+     * @phpstan-return non-empty-string
      */
-    abstract protected function canonicalizeAndCheckFolderIdentifier($folderIdentifier);
+    abstract protected function canonicalizeAndCheckFolderIdentifier(string $folderIdentifier): string;
 }
diff --git a/typo3/sysext/core/Classes/Resource/Driver/AbstractHierarchicalFilesystemDriver.php b/typo3/sysext/core/Classes/Resource/Driver/AbstractHierarchicalFilesystemDriver.php
@@ -29,23 +29,22 @@ abstract class AbstractHierarchicalFilesystemDriver extends AbstractDriver
     /**
      * Wrapper for \TYPO3\CMS\Core\Utility\GeneralUtility::validPathStr()
      *
-     * @param string $theFile Filepath to evaluate
      * @return bool TRUE if no '/', '..' or '\' is in the $theFile
      * @see \TYPO3\CMS\Core\Utility\GeneralUtility::validPathStr()
      */
-    protected function isPathValid($theFile)
+    protected function isPathValid(string $theFile): bool
     {
         return GeneralUtility::validPathStr($theFile);
     }
 
     /**
      * Makes sure the Path given as parameter is valid
      *
-     * @param string $filePath The file path (including the file name!)
-     * @return string
+     * @phpstan-param non-empty-string $filePath The file path (including the file name!)
+     * @phpstan-return non-empty-string
      * @throws InvalidPathException
      */
-    protected function canonicalizeAndCheckFilePath($filePath)
+    protected function canonicalizeAndCheckFilePath(string $filePath): string
     {
         $filePath = PathUtility::getCanonicalPath($filePath);
         // $filePath must be valid
@@ -58,11 +57,11 @@ protected function canonicalizeAndCheckFilePath($filePath)
     /**
      * Makes sure the Path given as parameter is valid
      *
-     * @param string $fileIdentifier The file path (including the file name!)
-     * @return string
+     * @phpstan-param non-empty-string $fileIdentifier The file path (including the file name!)
+     * @phpstan-return non-empty-string
      * @throws InvalidPathException
      */
-    protected function canonicalizeAndCheckFileIdentifier($fileIdentifier)
+    protected function canonicalizeAndCheckFileIdentifier(string $fileIdentifier): string
     {
         if ($fileIdentifier !== '') {
             $fileIdentifier = $this->canonicalizeAndCheckFilePath($fileIdentifier);
@@ -77,10 +76,10 @@ protected function canonicalizeAndCheckFileIdentifier($fileIdentifier)
     /**
      * Makes sure the Path given as parameter is valid
      *
-     * @param string $folderPath The file path (including the file name!)
-     * @return string
+     * @phpstan-param non-empty-string $folderPath The file path (including the file name!)
+     * @phpstan-return non-empty-string
      */
-    protected function canonicalizeAndCheckFolderIdentifier($folderPath)
+    protected function canonicalizeAndCheckFolderIdentifier(string $folderPath): string
     {
         if ($folderPath === '/') {
             $canonicalizedIdentifier = $folderPath;
@@ -93,8 +92,8 @@ protected function canonicalizeAndCheckFolderIdentifier($folderPath)
     /**
      * Returns the identifier of the folder the file resides in
      *
-     * @param non-empty-string $fileIdentifier
-     * @return non-empty-string
+     * @phpstan-param non-empty-string $fileIdentifier
+     * @phpstan-return non-empty-string
      */
     public function getParentFolderIdentifierOfIdentifier(string $fileIdentifier): string
     {

diff --git a/typo3/sysext/core/Classes/Resource/Driver/LocalDriver.php b/typo3/sysext/core/Classes/Resource/Driver/LocalDriver.php
@@ -55,10 +55,8 @@ class LocalDriver extends AbstractHierarchicalFilesystemDriver implements Stream
 
     /**
      * A list of all supported hash algorithms, written all lower case.
-     *
-     * @var array
      */
-    protected $supportedHashAlgorithms = ['sha1', 'md5'];
+    protected array $supportedHashAlgorithms = ['sha1', 'md5'];
 
     /**
      * The base URL that points to this driver's storage. As long is this

diff --git a/...on/Changelog/13.0/Breaking-101471-IntroduceTypeDeclarationsInAbstractDriver.rst b/...on/Changelog/13.0/Breaking-101471-IntroduceTypeDeclarationsInAbstractDriver.rst
@@ -0,0 +1,52 @@
+.. include:: /Includes.rst.txt
+
+.. _breaking-101471-1690531810:
+
+=================================================================
+Breaking: #101471 - Introduce type declarations in AbstractDriver
+=================================================================
+
+See :issue:`101471`
+
+Description
+===========
+
+Return and param type declarations have been introduced for all methods and method
+stubs of of :php:`\TYPO3\CMS\Core\Resource\Driver\AbstractDriver` and
+:php:`\TYPO3\CMS\Core\Resource\Driver\AbstractHierarchicalFilesystemDriver`
+
+
+Impact
+======
+
+In consequence, all classes, extending any of those abstract classes and overriding
+any of those affected methods need to reflect those changes and add the same return
+and param type declarations.
+
+Affected methods are:
+
+- :php:`\TYPO3\CMS\Core\Resource\Driver\AbstractDriver::isValidFilename()`
+- :php:`\TYPO3\CMS\Core\Resource\Driver\AbstractDriver::getTemporaryPathForFile()`
+- :php:`\TYPO3\CMS\Core\Resource\Driver\AbstractDriver::canonicalizeAndCheckFilePath()`
+- :php:`\TYPO3\CMS\Core\Resource\Driver\AbstractDriver::canonicalizeAndCheckFileIdentifier()`
+- :php:`\TYPO3\CMS\Core\Resource\Driver\AbstractDriver::canonicalizeAndCheckFolderIdentifier()`
+
+- :php:`\TYPO3\CMS\Core\Resource\Driver\AbstractHierarchicalFilesystemDriver::isPathValid()`
+- :php:`\TYPO3\CMS\Core\Resource\Driver\AbstractHierarchicalFilesystemDriver::canonicalizeAndCheckFilePath()`
+- :php:`\TYPO3\CMS\Core\Resource\Driver\AbstractHierarchicalFilesystemDriver::canonicalizeAndCheckFileIdentifier()`
+- :php:`\TYPO3\CMS\Core\Resource\Driver\AbstractHierarchicalFilesystemDriver::canonicalizeAndCheckFolderIdentifier()`
+
+
+Affected installations
+======================
+
+Installations that extend any of those abstract classes might be affected.
+
+
+Migration
+=========
+
+Add the same param and return type declarations the interface does.
+
+
+.. index:: FAL, PHP-API, NotScanned, ext:core