From 512c2e5d9df074f8aa8e531cd4629b08d24dd763 Mon Sep 17 00:00:00 2001 From: Matias Griese Date: Thu, 2 Dec 2021 21:22:10 +0200 Subject: [PATCH] Better typehints for Framework classes --- system/src/Grav/Framework/Acl/Access.php | 3 +- system/src/Grav/Framework/Acl/Action.php | 3 +- system/src/Grav/Framework/Acl/Permissions.php | 12 ++++++-- .../Framework/Acl/RecursiveActionIterator.php | 1 + .../Collection/AbstractFileCollection.php | 4 ++- .../Collection/AbstractIndexCollection.php | 13 +++++--- .../Collection/AbstractLazyCollection.php | 11 ++++++- .../Framework/Collection/ArrayCollection.php | 22 ++++++++++---- .../Collection/CollectionInterface.php | 1 + .../Framework/File/Formatter/CsvFormatter.php | 1 + .../File/Formatter/JsonFormatter.php | 1 + .../Grav/Framework/Filesystem/Filesystem.php | 2 ++ .../Interfaces/FilesystemInterface.php | 2 ++ system/src/Grav/Framework/Flex/Flex.php | 2 ++ .../Grav/Framework/Flex/FlexCollection.php | 15 ++++++++-- .../src/Grav/Framework/Flex/FlexDirectory.php | 30 ++++++++++++------- .../Grav/Framework/Flex/FlexDirectoryForm.php | 1 + system/src/Grav/Framework/Flex/FlexForm.php | 1 + system/src/Grav/Framework/Flex/FlexIndex.php | 2 +- system/src/Grav/Framework/Flex/FlexObject.php | 10 +++---- .../Interfaces/FlexDirectoryInterface.php | 5 ++++ .../Flex/Interfaces/FlexInterface.php | 2 ++ .../Flex/Interfaces/FlexObjectInterface.php | 1 + .../Flex/Pages/FlexPageCollection.php | 9 +++++- .../Flex/Pages/Traits/PageContentTrait.php | 6 ++-- .../Framework/Flex/Storage/SimpleStorage.php | 2 +- .../Framework/Flex/Traits/FlexMediaTrait.php | 5 +++- .../Grav/Framework/Form/Traits/FormTrait.php | 8 +++-- .../Interfaces/MediaCollectionInterface.php | 2 ++ .../src/Grav/Framework/Object/ArrayObject.php | 1 + .../Object/Base/ObjectCollectionTrait.php | 10 ++++++- .../src/Grav/Framework/Object/LazyObject.php | 1 + .../Framework/Object/ObjectCollection.php | 13 ++++---- .../src/Grav/Framework/Object/ObjectIndex.php | 18 +++++++++-- .../Grav/Framework/Object/PropertyObject.php | 2 ++ .../Pagination/AbstractPagination.php | 1 + .../Interfaces/PaginationInterface.php | 1 + system/src/Grav/Framework/Psr7/Response.php | 1 + .../Framework/Session/SessionInterface.php | 2 ++ 39 files changed, 174 insertions(+), 53 deletions(-) diff --git a/system/src/Grav/Framework/Acl/Access.php b/system/src/Grav/Framework/Acl/Access.php index ccc22cf1f..771d58e2f 100644 --- a/system/src/Grav/Framework/Acl/Access.php +++ b/system/src/Grav/Framework/Acl/Access.php @@ -25,6 +25,7 @@ use function strlen; /** * Class Access * @package Grav\Framework\Acl + * @implements IteratorAggregate */ class Access implements JsonSerializable, IteratorAggregate, Countable { @@ -34,7 +35,7 @@ class Access implements JsonSerializable, IteratorAggregate, Countable private $rules; /** @var array */ private $ops; - /** @var array */ + /** @var array */ private $acl = []; /** @var array */ private $inherited = []; diff --git a/system/src/Grav/Framework/Acl/Action.php b/system/src/Grav/Framework/Acl/Action.php index f5a6f6b4d..704f61e0d 100644 --- a/system/src/Grav/Framework/Acl/Action.php +++ b/system/src/Grav/Framework/Acl/Action.php @@ -21,6 +21,7 @@ use function strlen; /** * Class Action * @package Grav\Framework\Acl + * @implements IteratorAggregate */ class Action implements IteratorAggregate, Countable { @@ -37,7 +38,7 @@ class Action implements IteratorAggregate, Countable /** @var Action|null */ protected $parent; - /** @var Action[] */ + /** @var array */ protected $children = []; /** diff --git a/system/src/Grav/Framework/Acl/Permissions.php b/system/src/Grav/Framework/Acl/Permissions.php index fddc1a058..1494b10e1 100644 --- a/system/src/Grav/Framework/Acl/Permissions.php +++ b/system/src/Grav/Framework/Acl/Permissions.php @@ -9,20 +9,26 @@ namespace Grav\Framework\Acl; +use ArrayAccess; use ArrayIterator; +use Countable; +use IteratorAggregate; use RecursiveIteratorIterator; use RuntimeException; use Traversable; +use function count; /** * Class Permissions * @package Grav\Framework\Acl + * @implements ArrayAccess + * @implements IteratorAggregate */ -class Permissions implements \ArrayAccess, \Countable, \IteratorAggregate +class Permissions implements ArrayAccess, Countable, IteratorAggregate { - /** @var Action[] */ + /** @var array */ protected $instances = []; - /** @var Action[] */ + /** @var array */ protected $actions = []; /** @var array */ protected $nested = []; diff --git a/system/src/Grav/Framework/Acl/RecursiveActionIterator.php b/system/src/Grav/Framework/Acl/RecursiveActionIterator.php index d37f491b0..3b0e822cd 100644 --- a/system/src/Grav/Framework/Acl/RecursiveActionIterator.php +++ b/system/src/Grav/Framework/Acl/RecursiveActionIterator.php @@ -17,6 +17,7 @@ use RocketTheme\Toolbox\ArrayTraits\Iterator; /** * Class Action * @package Grav\Framework\Acl + * @implements RecursiveIterator */ class RecursiveActionIterator implements RecursiveIterator, \Countable { diff --git a/system/src/Grav/Framework/Collection/AbstractFileCollection.php b/system/src/Grav/Framework/Collection/AbstractFileCollection.php index 1be8d129a..77b3247f0 100644 --- a/system/src/Grav/Framework/Collection/AbstractFileCollection.php +++ b/system/src/Grav/Framework/Collection/AbstractFileCollection.php @@ -68,6 +68,7 @@ class AbstractFileCollection extends AbstractLazyCollection implements FileColle /** * @param Criteria $criteria * @return ArrayCollection + * @phpstan-return ArrayCollection * @todo Implement lazy matching */ public function matching(Criteria $criteria) @@ -93,6 +94,7 @@ class AbstractFileCollection extends AbstractLazyCollection implements FileColle foreach (array_reverse($orderings) as $field => $ordering) { $next = ClosureExpressionVisitor::sortByField($field, $ordering === Criteria::DESC ? -1 : 1, $next); } + /** @phpstan-ignore-next-line */ if (null === $next) { throw new RuntimeException('Criteria is missing orderings'); } @@ -162,6 +164,7 @@ class AbstractFileCollection extends AbstractLazyCollection implements FileColle * @param SeekableIterator $iterator * @param int $nestingLimit * @return array + * @phpstan-param SeekableIterator $iterator */ protected function doInitializeByIterator(SeekableIterator $iterator, $nestingLimit) { @@ -211,7 +214,6 @@ class AbstractFileCollection extends AbstractLazyCollection implements FileColle protected function doInitializeChildren(array $children, $nestingLimit) { $objects = []; - foreach ($children as $iterator) { $objects += $this->doInitializeByIterator($iterator, $nestingLimit); } diff --git a/system/src/Grav/Framework/Collection/AbstractIndexCollection.php b/system/src/Grav/Framework/Collection/AbstractIndexCollection.php index 79052ddcb..341c2e078 100644 --- a/system/src/Grav/Framework/Collection/AbstractIndexCollection.php +++ b/system/src/Grav/Framework/Collection/AbstractIndexCollection.php @@ -14,6 +14,7 @@ use Closure; use Grav\Framework\Compat\Serializable; use Grav\Framework\Flex\Interfaces\FlexObjectInterface; use InvalidArgumentException; +use Iterator; use function array_key_exists; use function array_slice; use function count; @@ -82,10 +83,8 @@ abstract class AbstractIndexCollection implements CollectionInterface #[\ReturnTypeWillChange] public function key() { - /** @phpstan-var TKey $key */ - $key = (string)key($this->entries); - - return $key; + /** @phpstan-var TKey */ + return (string)key($this->entries); } /** @@ -147,6 +146,7 @@ abstract class AbstractIndexCollection implements CollectionInterface * Required by interface ArrayAccess. * * {@inheritDoc} + * @phpstan-param TKey|null $offset */ #[\ReturnTypeWillChange] public function offsetExists($offset) @@ -158,6 +158,7 @@ abstract class AbstractIndexCollection implements CollectionInterface * Required by interface ArrayAccess. * * {@inheritDoc} + * @phpstan-param TKey|null $offset */ #[\ReturnTypeWillChange] public function offsetGet($offset) @@ -169,6 +170,7 @@ abstract class AbstractIndexCollection implements CollectionInterface * Required by interface ArrayAccess. * * {@inheritDoc} + * @phpstan-param TKey|null $offset */ #[\ReturnTypeWillChange] public function offsetSet($offset, $value) @@ -184,6 +186,7 @@ abstract class AbstractIndexCollection implements CollectionInterface * Required by interface ArrayAccess. * * {@inheritDoc} + * @phpstan-param TKey|null $offset */ #[\ReturnTypeWillChange] public function offsetUnset($offset) @@ -304,6 +307,7 @@ abstract class AbstractIndexCollection implements CollectionInterface * Required by interface IteratorAggregate. * * {@inheritDoc} + * @phpstan-return Iterator */ #[\ReturnTypeWillChange] public function getIterator() @@ -444,6 +448,7 @@ abstract class AbstractIndexCollection implements CollectionInterface * * @param int $size Size of each chunk. * @return array + * @phpstan-return array> */ public function chunk($size) { diff --git a/system/src/Grav/Framework/Collection/AbstractLazyCollection.php b/system/src/Grav/Framework/Collection/AbstractLazyCollection.php index d7e6f3191..5f7ad1b12 100644 --- a/system/src/Grav/Framework/Collection/AbstractLazyCollection.php +++ b/system/src/Grav/Framework/Collection/AbstractLazyCollection.php @@ -22,11 +22,15 @@ use Doctrine\Common\Collections\AbstractLazyCollection as BaseAbstractLazyCollec */ abstract class AbstractLazyCollection extends BaseAbstractLazyCollection implements CollectionInterface { - /** @var ArrayCollection The backed collection to use */ + /** + * @par ArrayCollection + * @phpstan-var ArrayCollection + */ protected $collection; /** * {@inheritDoc} + * @phpstan-return ArrayCollection */ public function reverse() { @@ -37,6 +41,7 @@ abstract class AbstractLazyCollection extends BaseAbstractLazyCollection impleme /** * {@inheritDoc} + * @phpstan-return ArrayCollection */ public function shuffle() { @@ -57,6 +62,8 @@ abstract class AbstractLazyCollection extends BaseAbstractLazyCollection impleme /** * {@inheritDoc} + * @phpstan-param array $keys + * @phpstan-return ArrayCollection */ public function select(array $keys) { @@ -67,6 +74,8 @@ abstract class AbstractLazyCollection extends BaseAbstractLazyCollection impleme /** * {@inheritDoc} + * @phpstan-param array $keys + * @phpstan-return ArrayCollection */ public function unselect(array $keys) { diff --git a/system/src/Grav/Framework/Collection/ArrayCollection.php b/system/src/Grav/Framework/Collection/ArrayCollection.php index 4a54b3cb9..892cfcb5a 100644 --- a/system/src/Grav/Framework/Collection/ArrayCollection.php +++ b/system/src/Grav/Framework/Collection/ArrayCollection.php @@ -30,7 +30,10 @@ class ArrayCollection extends BaseArrayCollection implements CollectionInterface */ public function reverse() { - return $this->createFrom(array_reverse($this->toArray())); + $keys = array_reverse($this->toArray()); + + /** @phpstan-var static */ + return $this->createFrom($keys); } /** @@ -43,8 +46,10 @@ class ArrayCollection extends BaseArrayCollection implements CollectionInterface { $keys = $this->getKeys(); shuffle($keys); + $keys = array_replace(array_flip($keys), $this->toArray()); - return $this->createFrom(array_replace(array_flip($keys), $this->toArray()) ?? []); + /** @phpstan-var static */ + return $this->createFrom($keys); } /** @@ -52,9 +57,11 @@ class ArrayCollection extends BaseArrayCollection implements CollectionInterface * * @param int $size Size of each chunk. * @return array + * @phpstan-return array> */ public function chunk($size) { + /** @phpstan-var array> */ return array_chunk($this->toArray(), $size, true); } @@ -63,9 +70,9 @@ class ArrayCollection extends BaseArrayCollection implements CollectionInterface * * Collection is returned in the order of $keys given to the function. * - * @param array $keys + * @param array $keys * @return static - * @phpstan-param array $keys + * @phpstan-param TKey[] $keys * @phpstan-return static */ public function select(array $keys) @@ -77,6 +84,7 @@ class ArrayCollection extends BaseArrayCollection implements CollectionInterface } } + /** @phpstan-var static */ return $this->createFrom($list); } @@ -85,11 +93,15 @@ class ArrayCollection extends BaseArrayCollection implements CollectionInterface * * @param array $keys * @return static + * @phpstan-param TKey[] $keys * @phpstan-return static */ public function unselect(array $keys) { - return $this->select(array_diff($this->getKeys(), $keys)); + $list = array_diff($this->getKeys(), $keys); + + /** @phpstan-var static */ + return $this->select($list); } /** diff --git a/system/src/Grav/Framework/Collection/CollectionInterface.php b/system/src/Grav/Framework/Collection/CollectionInterface.php index 0739109ba..def9427a1 100644 --- a/system/src/Grav/Framework/Collection/CollectionInterface.php +++ b/system/src/Grav/Framework/Collection/CollectionInterface.php @@ -43,6 +43,7 @@ interface CollectionInterface extends Collection, JsonSerializable * * @param int $size Size of each chunk. * @return array + * @phpstan-return array> */ public function chunk($size); diff --git a/system/src/Grav/Framework/File/Formatter/CsvFormatter.php b/system/src/Grav/Framework/File/Formatter/CsvFormatter.php index 9d0a9a882..072de1211 100644 --- a/system/src/Grav/Framework/File/Formatter/CsvFormatter.php +++ b/system/src/Grav/Framework/File/Formatter/CsvFormatter.php @@ -16,6 +16,7 @@ use Grav\Framework\File\Interfaces\FileFormatterInterface; use JsonSerializable; use RuntimeException; use stdClass; +use function count; use function is_array; use function is_object; use function is_scalar; diff --git a/system/src/Grav/Framework/File/Formatter/JsonFormatter.php b/system/src/Grav/Framework/File/Formatter/JsonFormatter.php index 6b19690c3..c76864533 100644 --- a/system/src/Grav/Framework/File/Formatter/JsonFormatter.php +++ b/system/src/Grav/Framework/File/Formatter/JsonFormatter.php @@ -117,6 +117,7 @@ class JsonFormatter extends AbstractFormatter * Returns recursion depth used in decode() function. * * @return int + * @phpstan-return positive-int */ public function getDecodeDepth(): int { diff --git a/system/src/Grav/Framework/Filesystem/Filesystem.php b/system/src/Grav/Framework/Filesystem/Filesystem.php index 9b077d780..d93f4c22a 100644 --- a/system/src/Grav/Framework/Filesystem/Filesystem.php +++ b/system/src/Grav/Framework/Filesystem/Filesystem.php @@ -176,6 +176,7 @@ class Filesystem implements FilesystemInterface * @param string $path * @param int $levels * @return string + * @phpstan-param positive-int $levels */ public function pathname(string $path, int $levels = 1): string { @@ -204,6 +205,7 @@ class Filesystem implements FilesystemInterface * @param string $path * @param int $levels * @return array + * @phpstan-param positive-int $levels */ protected function dirnameInternal(?string $scheme, string $path, int $levels = 1): array { diff --git a/system/src/Grav/Framework/Filesystem/Interfaces/FilesystemInterface.php b/system/src/Grav/Framework/Filesystem/Interfaces/FilesystemInterface.php index 0e280a837..f80b77244 100644 --- a/system/src/Grav/Framework/Filesystem/Interfaces/FilesystemInterface.php +++ b/system/src/Grav/Framework/Filesystem/Interfaces/FilesystemInterface.php @@ -31,6 +31,7 @@ interface FilesystemInterface * @param int $levels The number of parent directories to go up (>= 1). * @return string Returns parent path. * @throws RuntimeException + * @phpstan-param positive-int $levels * @api */ public function parent(string $path, int $levels = 1): string; @@ -64,6 +65,7 @@ interface FilesystemInterface * @param int $levels The number of parent directories to go up (>= 1). * @return string Returns path to the directory. * @throws RuntimeException + * @phpstan-param positive-int $levels * @api */ public function dirname(string $path, int $levels = 1): string; diff --git a/system/src/Grav/Framework/Flex/Flex.php b/system/src/Grav/Framework/Flex/Flex.php index ce285215c..e60dc50e1 100644 --- a/system/src/Grav/Framework/Flex/Flex.php +++ b/system/src/Grav/Framework/Flex/Flex.php @@ -123,6 +123,7 @@ class Flex implements FlexInterface * @param array|null $keys * @param string|null $keyField * @return FlexCollectionInterface|null + * @phpstan-return FlexCollectionInterface|null */ public function getCollection(string $type, array $keys = null, string $keyField = null): ?FlexCollectionInterface { @@ -137,6 +138,7 @@ class Flex implements FlexInterface * collection_class: Class to be used to create the collection. Defaults to ObjectCollection. * @return FlexCollectionInterface * @throws RuntimeException + * @phpstan-return FlexCollectionInterface */ public function getMixedCollection(array $keys, array $options = []): FlexCollectionInterface { diff --git a/system/src/Grav/Framework/Flex/FlexCollection.php b/system/src/Grav/Framework/Flex/FlexCollection.php index acacd7323..48d18ef0f 100644 --- a/system/src/Grav/Framework/Flex/FlexCollection.php +++ b/system/src/Grav/Framework/Flex/FlexCollection.php @@ -152,7 +152,11 @@ class FlexCollection extends ObjectCollection implements FlexCollectionInterface arsort($matching, SORT_NUMERIC); } - return $this->select(array_keys($matching)); + /** @var string[] $array */ + $array = array_keys($matching); + + /** @phpstan-var static */ + return $this->select($array); } /** @@ -163,7 +167,7 @@ class FlexCollection extends ObjectCollection implements FlexCollectionInterface { $criteria = Criteria::create()->orderBy($order); - /** @var FlexCollectionInterface $matching */ + /** @phpstan-var FlexCollectionInterface $matching */ $matching = $this->matching($criteria); return $matching; @@ -183,6 +187,7 @@ class FlexCollection extends ObjectCollection implements FlexCollectionInterface $criteria->andWhere($expr->eq($key, $value)); } + /** @phpstan-var static */ return $this->matching($criteria); } @@ -497,7 +502,11 @@ class FlexCollection extends ObjectCollection implements FlexCollectionInterface $list = $this->call('isAuthorized', [$action, $scope, $user]); $list = array_filter($list); - return $this->select(array_keys($list)); + /** @var string[] $keys */ + $keys = array_keys($list); + + /** @phpstan-var static */ + return $this->select($keys); } /** diff --git a/system/src/Grav/Framework/Flex/FlexDirectory.php b/system/src/Grav/Framework/Flex/FlexDirectory.php index 29f1490f8..c84e3d185 100644 --- a/system/src/Grav/Framework/Flex/FlexDirectory.php +++ b/system/src/Grav/Framework/Flex/FlexDirectory.php @@ -45,7 +45,6 @@ use function is_callable; /** * Class FlexDirectory * @package Grav\Framework\Flex - * @template T */ class FlexDirectory implements FlexDirectoryInterface { @@ -57,9 +56,15 @@ class FlexDirectory implements FlexDirectoryInterface protected $blueprint_file; /** @var Blueprint[] */ protected $blueprints; - /** @var FlexIndexInterface[] */ + /** + * @var FlexIndexInterface[] + * @phpstan-var FlexIndexInterface[] + */ protected $indexes = []; - /** @var FlexCollectionInterface|null */ + /** + * @var FlexCollectionInterface|null + * @phpstan-var FlexCollectionInterface|null + */ protected $collection; /** @var bool */ protected $enabled; @@ -318,7 +323,7 @@ class FlexDirectory implements FlexDirectoryInterface * @param array|null $keys Array of keys. * @param string|null $keyField Field to be used as the key. * @return FlexCollectionInterface - * @phpstan-return FlexCollectionInterface + * @phpstan-return FlexCollectionInterface */ public function getCollection(array $keys = null, string $keyField = null): FlexCollectionInterface { @@ -345,6 +350,7 @@ class FlexDirectory implements FlexDirectoryInterface * @param array|null $keys Array of keys. * @param string|null $keyField Field to be used as the key. * @return FlexIndexInterface + * @phpstan-return FlexIndexInterface */ public function getIndex(array $keys = null, string $keyField = null): FlexIndexInterface { @@ -353,7 +359,7 @@ class FlexDirectory implements FlexDirectoryInterface $index = clone $index; if (null !== $keys) { - /** @var FlexIndexInterface $index */ + /** @var FlexIndexInterface $index */ $index = $index->select($keys); } @@ -487,7 +493,7 @@ class FlexDirectory implements FlexDirectoryInterface */ public function createObject(array $data, string $key = '', bool $validate = false): FlexObjectInterface { - /** @var string|FlexObjectInterface $className */ + /** @phpstan-var class-string $className */ $className = $this->objectClassName ?: $this->getObjectClass(); return new $className($data, $key, $this, $validate); @@ -497,10 +503,11 @@ class FlexDirectory implements FlexDirectoryInterface * @param array $entries * @param string|null $keyField * @return FlexCollectionInterface + * @phpstan-return FlexCollectionInterface */ public function createCollection(array $entries, string $keyField = null): FlexCollectionInterface { - /** @var string|FlexCollectionInterface $className */ + /** phpstan-var class-string $className */ $className = $this->collectionClassName ?: $this->getCollectionClass(); return $className::createFromArray($entries, $this, $keyField); @@ -510,10 +517,11 @@ class FlexDirectory implements FlexDirectoryInterface * @param array $entries * @param string|null $keyField * @return FlexIndexInterface + * @phpstan-return FlexIndexInterface */ public function createIndex(array $entries, string $keyField = null): FlexIndexInterface { - /** @var string|FlexIndexInterface $className */ + /** @phpstan-var class-string $className */ $className = $this->indexClassName ?: $this->getIndexClass(); return $className::createFromArray($entries, $this, $keyField); @@ -560,6 +568,7 @@ class FlexDirectory implements FlexDirectoryInterface * @param array $entries * @param string|null $keyField * @return FlexCollectionInterface + * @phpstan-return FlexCollectionInterface */ public function loadCollection(array $entries, string $keyField = null): FlexCollectionInterface { @@ -895,6 +904,7 @@ class FlexDirectory implements FlexDirectoryInterface /** * @param string $keyField * @return FlexIndexInterface + * @phpstan-return FlexIndexInterface */ protected function loadIndex(string $keyField): FlexIndexInterface { @@ -924,7 +934,7 @@ class FlexDirectory implements FlexDirectoryInterface } if (!is_array($keys)) { - /** @var string|FlexIndexInterface $className */ + /** @phpstan-var class-string $className */ $className = $this->getIndexClass(); $keys = $className::loadEntriesFromStorage($storage); if (!$cache instanceof MemoryCache) { @@ -946,7 +956,7 @@ class FlexDirectory implements FlexDirectoryInterface // We need to do this in two steps as orderBy() calls loadIndex() again and we do not want infinite loop. $this->indexes['storage_key'] = $index = $this->createIndex($keys, 'storage_key'); if ($ordering) { - /** @var FlexCollectionInterface $collection */ + /** @var FlexCollectionInterface $collection */ $collection = $this->indexes['storage_key']->orderBy($ordering); $this->indexes['storage_key'] = $index = $collection->getIndex(); } diff --git a/system/src/Grav/Framework/Flex/FlexDirectoryForm.php b/system/src/Grav/Framework/Flex/FlexDirectoryForm.php index e1b5c4770..693ef120b 100644 --- a/system/src/Grav/Framework/Flex/FlexDirectoryForm.php +++ b/system/src/Grav/Framework/Flex/FlexDirectoryForm.php @@ -497,6 +497,7 @@ class FlexDirectoryForm implements FlexDirectoryFormInterface, JsonSerializable * Filter validated data. * * @param ArrayAccess|Data|null $data + * @phpstan-param ArrayAccess|Data|null $data */ protected function filterData($data = null): void { diff --git a/system/src/Grav/Framework/Flex/FlexForm.php b/system/src/Grav/Framework/Flex/FlexForm.php index 313745c55..5d7221847 100644 --- a/system/src/Grav/Framework/Flex/FlexForm.php +++ b/system/src/Grav/Framework/Flex/FlexForm.php @@ -598,6 +598,7 @@ class FlexForm implements FlexObjectFormInterface, JsonSerializable * * @param ArrayAccess|Data|null $data * @return void + * @phpstan-param ArrayAccess|Data|null $data */ protected function filterData($data = null): void { diff --git a/system/src/Grav/Framework/Flex/FlexIndex.php b/system/src/Grav/Framework/Flex/FlexIndex.php index 678617259..98b26679f 100644 --- a/system/src/Grav/Framework/Flex/FlexIndex.php +++ b/system/src/Grav/Framework/Flex/FlexIndex.php @@ -438,7 +438,7 @@ class FlexIndex extends ObjectIndex implements FlexCollectionInterface, FlexInde /** @var Debugger $debugger */ $debugger = Grav::instance()['debugger']; - /** @var FlexCollection $className */ + /** @phpstan-var class-string $className */ $className = $this->getFlexDirectory()->getCollectionClass(); $cachedMethods = $className::getCachedMethods(); diff --git a/system/src/Grav/Framework/Flex/FlexObject.php b/system/src/Grav/Framework/Flex/FlexObject.php index 5eccc8f5e..f77059225 100644 --- a/system/src/Grav/Framework/Flex/FlexObject.php +++ b/system/src/Grav/Framework/Flex/FlexObject.php @@ -69,13 +69,13 @@ class FlexObject implements FlexObjectInterface, FlexAuthorizeInterface private $_forms = []; /** @var Blueprint[] */ private $_blueprint = []; - /** @var array */ + /** @var array|null */ private $_meta; - /** @var array */ + /** @var array|null */ protected $_original; - /** @var string */ + /** @var string|null */ protected $storage_key; - /** @var int */ + /** @var int|null */ protected $storage_timestamp; /** @@ -776,7 +776,7 @@ class FlexObject implements FlexObjectInterface, FlexAuthorizeInterface $value = reset($result); $meta = $value['__META'] ?? null; if ($meta) { - /** @var FlexIndex $indexClass */ + /** @phpstan-var class-string $indexClass */ $indexClass = $this->getFlexDirectory()->getIndexClass(); $indexClass::updateObjectMeta($meta, $value, $storage); $this->_meta = $meta; diff --git a/system/src/Grav/Framework/Flex/Interfaces/FlexDirectoryInterface.php b/system/src/Grav/Framework/Flex/Interfaces/FlexDirectoryInterface.php index 07eab014a..1d9565745 100644 --- a/system/src/Grav/Framework/Flex/Interfaces/FlexDirectoryInterface.php +++ b/system/src/Grav/Framework/Flex/Interfaces/FlexDirectoryInterface.php @@ -105,6 +105,7 @@ interface FlexDirectoryInterface extends FlexAuthorizeInterface * @param array|null $keys Array of keys. * @param string|null $keyField Field to be used as the key. * @return FlexCollectionInterface + * @phpstan-return FlexCollectionInterface */ public function getCollection(array $keys = null, string $keyField = null): FlexCollectionInterface; @@ -116,6 +117,7 @@ interface FlexDirectoryInterface extends FlexAuthorizeInterface * @param array|null $keys Array of keys. * @param string|null $keyField Field to be used as the key. * @return FlexIndexInterface + * @phpstan-return FlexIndexInterface */ public function getIndex(array $keys = null, string $keyField = null): FlexIndexInterface; @@ -170,6 +172,7 @@ interface FlexDirectoryInterface extends FlexAuthorizeInterface * @param array $entries * @param string|null $keyField * @return FlexCollectionInterface + * @phpstan-return FlexCollectionInterface */ public function createCollection(array $entries, string $keyField = null): FlexCollectionInterface; @@ -177,6 +180,7 @@ interface FlexDirectoryInterface extends FlexAuthorizeInterface * @param array $entries * @param string|null $keyField * @return FlexIndexInterface + * @phpstan-return FlexIndexInterface */ public function createIndex(array $entries, string $keyField = null): FlexIndexInterface; @@ -199,6 +203,7 @@ interface FlexDirectoryInterface extends FlexAuthorizeInterface * @param array $entries * @param string|null $keyField * @return FlexCollectionInterface + * @phpstan-return FlexCollectionInterface */ public function loadCollection(array $entries, string $keyField = null): FlexCollectionInterface; diff --git a/system/src/Grav/Framework/Flex/Interfaces/FlexInterface.php b/system/src/Grav/Framework/Flex/Interfaces/FlexInterface.php index 3c5a103d2..cbd440bd2 100644 --- a/system/src/Grav/Framework/Flex/Interfaces/FlexInterface.php +++ b/system/src/Grav/Framework/Flex/Interfaces/FlexInterface.php @@ -59,6 +59,7 @@ interface FlexInterface extends Countable * @param array|null $keys * @param string|null $keyField * @return FlexCollectionInterface|null + * @phpstan-return FlexCollectionInterface|null */ public function getCollection(string $type, array $keys = null, string $keyField = null): ?FlexCollectionInterface; @@ -68,6 +69,7 @@ interface FlexInterface extends Countable * collection_class: Class to be used to create the collection. Defaults to ObjectCollection. * @return FlexCollectionInterface * @throws RuntimeException + * @phpstan-return FlexCollectionInterface */ public function getMixedCollection(array $keys, array $options = []): FlexCollectionInterface; diff --git a/system/src/Grav/Framework/Flex/Interfaces/FlexObjectInterface.php b/system/src/Grav/Framework/Flex/Interfaces/FlexObjectInterface.php index a1e3e3b92..a0f30c6e9 100644 --- a/system/src/Grav/Framework/Flex/Interfaces/FlexObjectInterface.php +++ b/system/src/Grav/Framework/Flex/Interfaces/FlexObjectInterface.php @@ -23,6 +23,7 @@ use RuntimeException; /** * Defines Flex Objects. * + * @extends ArrayAccess * @used-by \Grav\Framework\Flex\FlexObject * @since 1.6 */ diff --git a/system/src/Grav/Framework/Flex/Pages/FlexPageCollection.php b/system/src/Grav/Framework/Flex/Pages/FlexPageCollection.php index 94825681c..d27321827 100644 --- a/system/src/Grav/Framework/Flex/Pages/FlexPageCollection.php +++ b/system/src/Grav/Framework/Flex/Pages/FlexPageCollection.php @@ -13,6 +13,7 @@ namespace Grav\Framework\Flex\Pages; use Grav\Common\Page\Interfaces\PageInterface; use Grav\Framework\Flex\FlexCollection; +use Grav\Framework\Flex\Interfaces\FlexObjectInterface; use function array_search; use function assert; use function is_int; @@ -20,7 +21,7 @@ use function is_int; /** * Class FlexPageCollection * @package Grav\Plugin\FlexObjects\Types\FlexPages - * @template T of \Grav\Framework\Flex\Interfaces\FlexObjectInterface + * @template T of FlexObjectInterface * @extends FlexCollection */ class FlexPageCollection extends FlexCollection @@ -56,8 +57,10 @@ class FlexPageCollection extends FlexCollection */ public function withPublished(bool $bool = true) { + /** @var string[] $list */ $list = array_keys(array_filter($this->call('isPublished', [$bool]))); + /** @phpstan-var static */ return $this->select($list); } @@ -68,8 +71,10 @@ class FlexPageCollection extends FlexCollection */ public function withVisible(bool $bool = true) { + /** @var string[] $list */ $list = array_keys(array_filter($this->call('isVisible', [$bool]))); + /** @phpstan-var static */ return $this->select($list); } @@ -80,8 +85,10 @@ class FlexPageCollection extends FlexCollection */ public function withRoutable(bool $bool = true) { + /** @var string[] $list */ $list = array_keys(array_filter($this->call('isRoutable', [$bool]))); + /** @phpstan-var static */ return $this->select($list); } diff --git a/system/src/Grav/Framework/Flex/Pages/Traits/PageContentTrait.php b/system/src/Grav/Framework/Flex/Pages/Traits/PageContentTrait.php index 6aff73277..f534c132c 100644 --- a/system/src/Grav/Framework/Flex/Pages/Traits/PageContentTrait.php +++ b/system/src/Grav/Framework/Flex/Pages/Traits/PageContentTrait.php @@ -75,13 +75,13 @@ trait PageContentTrait 'template' => 'template', ]; - /** @var object */ + /** @var object|null */ protected $header; - /** @var string */ + /** @var string|null */ protected $_summary; - /** @var string */ + /** @var string|null */ protected $_content; /** diff --git a/system/src/Grav/Framework/Flex/Storage/SimpleStorage.php b/system/src/Grav/Framework/Flex/Storage/SimpleStorage.php index 6faac9d84..78a4ad206 100644 --- a/system/src/Grav/Framework/Flex/Storage/SimpleStorage.php +++ b/system/src/Grav/Framework/Flex/Storage/SimpleStorage.php @@ -30,7 +30,7 @@ class SimpleStorage extends AbstractFilesystemStorage protected $dataFolder; /** @var string */ protected $dataPattern; - /** @var string */ + /** @var string|null */ protected $prefix; /** @var array|null */ protected $data; diff --git a/system/src/Grav/Framework/Flex/Traits/FlexMediaTrait.php b/system/src/Grav/Framework/Flex/Traits/FlexMediaTrait.php index 62894c2ec..66c868852 100644 --- a/system/src/Grav/Framework/Flex/Traits/FlexMediaTrait.php +++ b/system/src/Grav/Framework/Flex/Traits/FlexMediaTrait.php @@ -165,6 +165,9 @@ trait FlexMediaTrait return $settings + ['accept' => '*', 'limit' => 1000, 'self' => true]; } + /** + * @return array + */ protected function getMediaFields(): array { // Load settings for the field. @@ -398,7 +401,7 @@ trait FlexMediaTrait } /** - * @return array + * @return array */ protected function getUpdatedMedia(): array { diff --git a/system/src/Grav/Framework/Form/Traits/FormTrait.php b/system/src/Grav/Framework/Form/Traits/FormTrait.php index d77a40274..32df48037 100644 --- a/system/src/Grav/Framework/Form/Traits/FormTrait.php +++ b/system/src/Grav/Framework/Form/Traits/FormTrait.php @@ -65,10 +65,10 @@ trait FormTrait private $sessionid; /** @var bool */ private $submitted; - /** @var ArrayAccess|Data|null */ + /** @var ArrayAccess|Data|null */ private $data; - /** @var array|UploadedFileInterface[] */ - private $files; + /** @var UploadedFileInterface[] */ + private $files = []; /** @var FormFlashInterface|null */ private $flash; /** @var string */ @@ -721,6 +721,7 @@ trait FormTrait * @param ArrayAccess|Data|null $data * @return void * @throws ValidationException + * @phpstan-param ArrayAccess|Data|null $data * @throws Exception */ protected function validateData($data = null): void @@ -735,6 +736,7 @@ trait FormTrait * * @param ArrayAccess|Data|null $data * @return void + * @phpstan-param ArrayAccess|Data|null $data */ protected function filterData($data = null): void { diff --git a/system/src/Grav/Framework/Media/Interfaces/MediaCollectionInterface.php b/system/src/Grav/Framework/Media/Interfaces/MediaCollectionInterface.php index e763f42d2..b3985f308 100644 --- a/system/src/Grav/Framework/Media/Interfaces/MediaCollectionInterface.php +++ b/system/src/Grav/Framework/Media/Interfaces/MediaCollectionInterface.php @@ -15,6 +15,8 @@ use Iterator; /** * Class implements media collection interface. + * @extends ArrayAccess + * @extends Iterator */ interface MediaCollectionInterface extends ArrayAccess, Countable, Iterator { diff --git a/system/src/Grav/Framework/Object/ArrayObject.php b/system/src/Grav/Framework/Object/ArrayObject.php index 2bbe93781..57b65261d 100644 --- a/system/src/Grav/Framework/Object/ArrayObject.php +++ b/system/src/Grav/Framework/Object/ArrayObject.php @@ -19,6 +19,7 @@ use Grav\Framework\Object\Property\ArrayPropertyTrait; /** * Array Objects keep the data in private array property. + * @implements ArrayAccess */ class ArrayObject implements NestedObjectInterface, ArrayAccess { diff --git a/system/src/Grav/Framework/Object/Base/ObjectCollectionTrait.php b/system/src/Grav/Framework/Object/Base/ObjectCollectionTrait.php index b39ebaa16..b110c5b57 100644 --- a/system/src/Grav/Framework/Object/Base/ObjectCollectionTrait.php +++ b/system/src/Grav/Framework/Object/Base/ObjectCollectionTrait.php @@ -20,6 +20,9 @@ use function is_object; /** * ObjectCollection Trait * @package Grav\Framework\Object + * + * @template TKey as array-key + * @template T as object */ trait ObjectCollectionTrait { @@ -211,14 +214,18 @@ trait ObjectCollectionTrait /** * Create a copy from this collection by cloning all objects in the collection. + * + * @return static */ public function copy() { $list = []; foreach ($this->getIterator() as $key => $value) { + /** @phpstan-ignore-next-line */ $list[$key] = is_object($value) ? clone $value : $value; } + /** @phpstan-var static */ return $this->createFrom($list); } @@ -334,6 +341,7 @@ trait ObjectCollectionTrait * * @param string $property * @return array + * @phpstan-return array */ public function group($property) { @@ -352,12 +360,12 @@ trait ObjectCollectionTrait * * @param string $property * @return static[] + * @phpstan-return array> */ public function collectionGroup($property) { $collections = []; foreach ($this->group($property) as $id => $elements) { - /** @var static $collection */ $collection = $this->createFrom($elements); $collections[$id] = $collection; diff --git a/system/src/Grav/Framework/Object/LazyObject.php b/system/src/Grav/Framework/Object/LazyObject.php index 309c0d6f6..752c5b2d7 100644 --- a/system/src/Grav/Framework/Object/LazyObject.php +++ b/system/src/Grav/Framework/Object/LazyObject.php @@ -22,6 +22,7 @@ use Grav\Framework\Object\Property\LazyPropertyTrait; * not exist or is not initialized. * * @package Grav\Framework\Object + * @implements ArrayAccess */ class LazyObject implements NestedObjectInterface, ArrayAccess { diff --git a/system/src/Grav/Framework/Object/ObjectCollection.php b/system/src/Grav/Framework/Object/ObjectCollection.php index 3fdebce91..af861c2ce 100644 --- a/system/src/Grav/Framework/Object/ObjectCollection.php +++ b/system/src/Grav/Framework/Object/ObjectCollection.php @@ -22,12 +22,13 @@ use function array_slice; * Class contains a collection of objects. * * @template TKey of array-key - * @template T + * @template T of object * @extends ArrayCollection * @implements NestedObjectCollectionInterface */ class ObjectCollection extends ArrayCollection implements NestedObjectCollectionInterface { + /** @phpstan-use ObjectCollectionTrait */ use ObjectCollectionTrait; use NestedPropertyCollectionTrait { NestedPropertyCollectionTrait::group insteadof ObjectCollectionTrait; @@ -65,6 +66,7 @@ class ObjectCollection extends ArrayCollection implements NestedObjectCollection */ public function limit($start, $limit = null) { + /** @phpstan-var static */ return $this->createFrom($this->slice($start, $limit)); } @@ -86,14 +88,11 @@ class ObjectCollection extends ArrayCollection implements NestedObjectCollection if ($orderings = $criteria->getOrderings()) { $next = null; - /** - * @var string $field - * @var string $ordering - */ foreach (array_reverse($orderings) as $field => $ordering) { $next = ObjectExpressionVisitor::sortByField($field, $ordering === Criteria::DESC ? -1 : 1, $next); } + /** @phpstan-ignore-next-line */ if ($next) { uasort($filtered, $next); } @@ -106,11 +105,13 @@ class ObjectCollection extends ArrayCollection implements NestedObjectCollection $filtered = array_slice($filtered, (int)$offset, $length); } + /** @phpstan-var static */ return $this->createFrom($filtered); } /** * @return array + * @phpstan-return array */ protected function getElements() { @@ -120,9 +121,11 @@ class ObjectCollection extends ArrayCollection implements NestedObjectCollection /** * @param array $elements * @return array + * @phpstan-return array */ protected function setElements(array $elements) { + /** @phpstan-var array */ return $elements; } } diff --git a/system/src/Grav/Framework/Object/ObjectIndex.php b/system/src/Grav/Framework/Object/ObjectIndex.php index b9b4973f7..bc1fad248 100644 --- a/system/src/Grav/Framework/Object/ObjectIndex.php +++ b/system/src/Grav/Framework/Object/ObjectIndex.php @@ -25,7 +25,7 @@ use function is_object; * * @template TKey of array-key * @template T of \Grav\Framework\Object\Interfaces\ObjectInterface - * @template C of \Grav\Framework\Collection\CollectionInterface + * @template C of ObjectCollectionInterface * @extends AbstractIndexCollection * @implements NestedObjectCollectionInterface */ @@ -95,6 +95,7 @@ abstract class ObjectIndex extends AbstractIndexCollection implements NestedObje * @param string $property Object property to be updated. * @param string $value New value. * @return ObjectCollectionInterface + * @phpstan-return C */ public function setProperty($property, $value) { @@ -105,6 +106,7 @@ abstract class ObjectIndex extends AbstractIndexCollection implements NestedObje * @param string $property Object property to be defined. * @param mixed $default Default value. * @return ObjectCollectionInterface + * @phpstan-return C */ public function defProperty($property, $default) { @@ -114,6 +116,7 @@ abstract class ObjectIndex extends AbstractIndexCollection implements NestedObje /** * @param string $property Object property to be unset. * @return ObjectCollectionInterface + * @phpstan-return C */ public function unsetProperty($property) { @@ -146,6 +149,7 @@ abstract class ObjectIndex extends AbstractIndexCollection implements NestedObje * @param mixed $value New value. * @param string|null $separator Separator, defaults to '.' * @return ObjectCollectionInterface + * @phpstan-return C */ public function setNestedProperty($property, $value, $separator = null) { @@ -157,6 +161,7 @@ abstract class ObjectIndex extends AbstractIndexCollection implements NestedObje * @param mixed $default Default value. * @param string|null $separator Separator, defaults to '.' * @return ObjectCollectionInterface + * @phpstan-return C */ public function defNestedProperty($property, $default, $separator = null) { @@ -167,6 +172,7 @@ abstract class ObjectIndex extends AbstractIndexCollection implements NestedObje * @param string $property Object property to be unset. * @param string|null $separator Separator, defaults to '.' * @return ObjectCollectionInterface + * @phpstan-return C */ public function unsetNestedProperty($property, $separator = null) { @@ -183,9 +189,11 @@ abstract class ObjectIndex extends AbstractIndexCollection implements NestedObje { $list = []; foreach ($this->getIterator() as $key => $value) { + /** @phpstan-ignore-next-line */ $list[$key] = is_object($value) ? clone $value : $value; } + /** @phpstan-var static */ return $this->createFrom($list); } @@ -200,6 +208,7 @@ abstract class ObjectIndex extends AbstractIndexCollection implements NestedObje /** * @param array $ordering * @return ObjectCollectionInterface + * @phpstan-return C */ public function orderBy(array $ordering) { @@ -232,6 +241,7 @@ abstract class ObjectIndex extends AbstractIndexCollection implements NestedObje * * @param string $property * @return ObjectCollectionInterface[] + * @phpstan-return C[] */ public function collectionGroup($property) { @@ -239,13 +249,15 @@ abstract class ObjectIndex extends AbstractIndexCollection implements NestedObje } /** - * {@inheritDoc} + * @param Criteria $criteria + * @return ObjectCollectionInterface + * @phpstan-return C */ public function matching(Criteria $criteria) { - /** @var ObjectCollectionInterface $collection */ $collection = $this->loadCollection($this->getEntries()); + /** @phpstan-var C */ return $collection->matching($criteria); } diff --git a/system/src/Grav/Framework/Object/PropertyObject.php b/system/src/Grav/Framework/Object/PropertyObject.php index dbeb5c432..fcd364c6c 100644 --- a/system/src/Grav/Framework/Object/PropertyObject.php +++ b/system/src/Grav/Framework/Object/PropertyObject.php @@ -19,6 +19,8 @@ use Grav\Framework\Object\Property\ObjectPropertyTrait; /** * Property Objects keep their data in protected object properties. + * + * @implements ArrayAccess */ class PropertyObject implements NestedObjectInterface, ArrayAccess { diff --git a/system/src/Grav/Framework/Pagination/AbstractPagination.php b/system/src/Grav/Framework/Pagination/AbstractPagination.php index 2e6f815f8..392bb7710 100644 --- a/system/src/Grav/Framework/Pagination/AbstractPagination.php +++ b/system/src/Grav/Framework/Pagination/AbstractPagination.php @@ -234,6 +234,7 @@ class AbstractPagination implements PaginationInterface /** * @return ArrayIterator + * @phpstan-return ArrayIterator */ #[\ReturnTypeWillChange] public function getIterator() diff --git a/system/src/Grav/Framework/Pagination/Interfaces/PaginationInterface.php b/system/src/Grav/Framework/Pagination/Interfaces/PaginationInterface.php index 56d336195..b2f5c352b 100644 --- a/system/src/Grav/Framework/Pagination/Interfaces/PaginationInterface.php +++ b/system/src/Grav/Framework/Pagination/Interfaces/PaginationInterface.php @@ -16,6 +16,7 @@ use IteratorAggregate; /** * Interface PaginationInterface * @package Grav\Framework\Pagination\Interfaces + * @extends IteratorAggregate */ interface PaginationInterface extends Countable, IteratorAggregate { diff --git a/system/src/Grav/Framework/Psr7/Response.php b/system/src/Grav/Framework/Psr7/Response.php index 6cb67e0e8..a5c2c8a8a 100644 --- a/system/src/Grav/Framework/Psr7/Response.php +++ b/system/src/Grav/Framework/Psr7/Response.php @@ -53,6 +53,7 @@ class Response implements ResponseInterface * @param int $options Json encoding options * @param int $depth Json encoding max depth * @return static + * @phpstan-param positive-int $depth */ public function withJson($data, int $status = null, int $options = 0, int $depth = 512): ResponseInterface { diff --git a/system/src/Grav/Framework/Session/SessionInterface.php b/system/src/Grav/Framework/Session/SessionInterface.php index 113e94ccf..a441791bd 100644 --- a/system/src/Grav/Framework/Session/SessionInterface.php +++ b/system/src/Grav/Framework/Session/SessionInterface.php @@ -16,6 +16,7 @@ use RuntimeException; /** * Class Session * @package Grav\Framework\Session + * @extends IteratorAggregate */ interface SessionInterface extends IteratorAggregate { @@ -107,6 +108,7 @@ interface SessionInterface extends IteratorAggregate * Retrieve an external iterator * * @return ArrayIterator Return an ArrayIterator of $_SESSION + * @phpstan-return ArrayIterator */ #[\ReturnTypeWillChange] public function getIterator();