Add return types on public classes and interfaces

UPGRADE.md

@@ -8,7 +8,12 @@ awareness about deprecated code.
 
 # Upgrade to 2.0
 
-You need PHP 8.1 or newer to use this library. 
+You need PHP 8.1 or newer to use this library.
+
+## BC BREAK: Add return types to all the methods
+
+All return types defined in phpdoc `@return` are now defined in the method signature,
+they must be added to your code if you extend the classes or implement the interfaces.
 
 ## Loggers have to implement the PSR-3 contracts
 

phpcs.xml.dist

@@ -56,11 +56,6 @@
         <exclude-pattern>src/*</exclude-pattern>
     </rule>
 
-    <rule ref="SlevomatCodingStandard.TypeHints.ReturnTypeHint.MissingNativeTypeHint">
-        <!-- Adding return types is a BC break in most cases. -->
-        <exclude-pattern>src/*</exclude-pattern>
-    </rule>
-
     <rule ref="Squiz.Classes.ClassFileName.NoMatch">
         <exclude-pattern>tests/*</exclude-pattern>
     </rule>

psalm-baseline.xml

@@ -1,28 +1,24 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<files psalm-version="5.18.0@b113f3ed0259fd6e212d87c3df80eec95a6abf19">
+<files psalm-version="5.23.1@8471a896ccea3526b26d082f4461eeea467f10a4">
   <file src="src/Executor/PHPCRExecutor.php">
     <UndefinedClass>
-      <code>DocumentManagerInterface</code>
+      <code><![CDATA[DocumentManagerInterface]]></code>
+      <code><![CDATA[DocumentManagerInterface]]></code>
     </UndefinedClass>
-    <UndefinedDocblockClass>
-      <code>DocumentManagerInterface</code>
-    </UndefinedDocblockClass>
   </file>
   <file src="src/Purger/PHPCRPurger.php">
     <UndefinedClass>
       <code><![CDATA[$this->dm]]></code>
-      <code>DocumentManager</code>
-      <code>NodeHelper</code>
-      <code>private</code>
+      <code><![CDATA[DocumentManager]]></code>
+      <code><![CDATA[DocumentManagerInterface|null]]></code>
+      <code><![CDATA[NodeHelper]]></code>
+      <code><![CDATA[private]]></code>
     </UndefinedClass>
-    <UndefinedDocblockClass>
-      <code>DocumentManagerInterface|null</code>
-    </UndefinedDocblockClass>
   </file>
   <file src="src/ReferenceRepository.php">
     <UndefinedClass>
-      <code>PhpcrDocumentManager</code>
-      <code>PhpcrDocumentManager</code>
+      <code><![CDATA[PhpcrDocumentManager]]></code>
+      <code><![CDATA[PhpcrDocumentManager]]></code>
     </UndefinedClass>
   </file>
 </files>

src/AbstractFixture.php

@@ -22,10 +22,7 @@
      */
     protected $referenceRepository;
 
-    /**
-     * {@inheritDoc}
-     */
-    public function setReferenceRepository(ReferenceRepository $referenceRepository)
+    public function setReferenceRepository(ReferenceRepository $referenceRepository): void
     {
         $this->referenceRepository = $referenceRepository;
     }
@@ -45,10 +42,8 @@
      * @see ReferenceRepository::setReference()
      *
      * @param object $object - managed object
-     *
-     * @return void
      */
-    public function setReference(string $name, object $object)
+    public function setReference(string $name, object $object): void
     {
         $this->getReferenceRepository()->setReference($name, $object);
     }
@@ -63,11 +58,9 @@
      *
      * @param object $object - managed object
      *
-     * @return void
-     *
      * @throws BadMethodCallException - if repository already has a reference by $name.
      */
-    public function addReference(string $name, object $object)
+    public function addReference(string $name, object $object): void
     {
         $this->getReferenceRepository()->addReference($name, $object);
     }
@@ -80,12 +73,11 @@
      *
      * @psalm-param class-string<T> $class
      *
-     * @return object
      * @psalm-return T
      *
      * @template T of object
      */
-    public function getReference(string $name, string $class)
+    public function getReference(string $name, string $class): object
     {
         return $this->getReferenceRepository()->getReference($name, $class);
     }
@@ -97,10 +89,8 @@
      * @see ReferenceRepository::hasReference()
      *
      * @psalm-param class-string $class
-     *
-     * @return bool
      */
-    public function hasReference(string $name, string $class)
+    public function hasReference(string $name, string $class): bool
     {
         return $this->getReferenceRepository()->hasReference($name, $class);
     }

src/DependentFixtureInterface.php

@@ -15,5 +15,5 @@ interface DependentFixtureInterface
      *
      * @psalm-return array<class-string<FixtureInterface>>
      */
-    public function getDependencies();
+    public function getDependencies(): array;
 }

src/Executor/AbstractExecutor.php

@@ -45,39 +45,33 @@
         $this->referenceRepository = new ReferenceRepository($manager);
     }
 
-    /** @return ReferenceRepository */
-    public function getReferenceRepository()
+    public function getReferenceRepository(): ReferenceRepository
     {
         return $this->referenceRepository;
     }
 
-    public function setReferenceRepository(ReferenceRepository $referenceRepository)
+    public function setReferenceRepository(ReferenceRepository $referenceRepository): void
     {
         $this->referenceRepository = $referenceRepository;
     }
 
     /**
      * Sets the Purger instance to use for this executor instance.
-     *
-     * @return void
      */
-    public function setPurger(PurgerInterface $purger)
+    public function setPurger(PurgerInterface $purger): void
     {
         $this->purger = $purger;
     }
 
-    /** @return PurgerInterface */
-    public function getPurger()
+    public function getPurger(): PurgerInterface
     {
         return $this->purger;
     }
 
     /**
      * Load a fixture with the given persistence manager.
-     *
-     * @return void
      */
-    public function load(ObjectManager $manager, FixtureInterface $fixture)
+    public function load(ObjectManager $manager, FixtureInterface $fixture): void
     {
         if ($this->logger) {
             $prefix = '';
@@ -100,11 +94,9 @@
     /**
      * Purges the database before loading.
      *
-     * @return void
-     *
      * @throws Exception if the purger is not defined.
      */
-    public function purge()
+    public function purge(): void
     {
         if ($this->purger === null) {
             throw new Exception(
@@ -123,8 +115,6 @@
      *
      * @param FixtureInterface[] $fixtures Array of fixtures to execute.
      * @param bool               $append   Whether to append the data fixtures or purge the database before loading.
-     *
-     * @return void
      */
-    abstract public function execute(array $fixtures, bool $append = false);
+    abstract public function execute(array $fixtures, bool $append = false): void;
 }

src/Executor/MongoDBExecutor.php

@@ -38,16 +38,13 @@
 
     /**
      * Retrieve the DocumentManager instance this executor instance is using.
-     *
-     * @return DocumentManager
      */
-    public function getObjectManager()
+    public function getObjectManager(): DocumentManager
     {
         return $this->dm;
     }
 
-    /** @inheritDoc */
-    public function setReferenceRepository(ReferenceRepository $referenceRepository)
+    public function setReferenceRepository(ReferenceRepository $referenceRepository): void
     {
         $this->dm->getEventManager()->removeEventListener(
             $this->listener->getSubscribedEvents(),
@@ -60,7 +57,7 @@
     }
 
     /** @inheritDoc */
-    public function execute(array $fixtures, bool $append = false)
+    public function execute(array $fixtures, bool $append = false): void
     {
         if ($append === false) {
             $this->purge();

src/Executor/ORMExecutor.php

@@ -16,10 +16,10 @@ class ORMExecutor extends AbstractExecutor
     use ORMExecutorCommon;
 
     /** @inheritDoc */
-    public function execute(array $fixtures, bool $append = false)
+    public function execute(array $fixtures, bool $append = false): void
     {
         $executor = $this;
-        $this->em->wrapInTransaction(static function (EntityManagerInterface $em) use ($executor, $fixtures, $append) {
+        $this->em->wrapInTransaction(static function (EntityManagerInterface $em) use ($executor, $fixtures, $append): void {
             if ($append === false) {
                 $executor->purge();
             }

src/Executor/ORMExecutorCommon.php

@@ -43,16 +43,13 @@
 
     /**
      * Retrieve the EntityManagerInterface instance this executor instance is using.
-     *
-     * @return EntityManagerInterface
      */
-    public function getObjectManager()
+    public function getObjectManager(): EntityManagerInterface
     {
         return $this->originalManager;
     }
 
-    /** @inheritDoc */
-    public function setReferenceRepository(ReferenceRepository $referenceRepository)
+    public function setReferenceRepository(ReferenceRepository $referenceRepository): void
     {
         $this->em->getEventManager()->removeEventListener(
             $this->listener->getSubscribedEvents(),

src/Executor/PHPCRExecutor.php

@@ -32,18 +32,17 @@
         $this->setPurger($purger);
     }
 
-    /** @return DocumentManagerInterface */
-    public function getObjectManager()
+    public function getObjectManager(): DocumentManagerInterface
     {
         return $this->dm;
     }
 
     /** @inheritDoc */
-    public function execute(array $fixtures, bool $append = false)
+    public function execute(array $fixtures, bool $append = false): void
     {
         $that = $this;
 
-        $function = static function ($dm) use ($append, $that, $fixtures) {
+        $function = static function ($dm) use ($append, $that, $fixtures): void {
             if ($append === false) {
                 $that->purge();
             }

src/FixtureInterface.php

@@ -14,5 +14,5 @@ interface FixtureInterface
     /**
      * Load data fixtures with the passed EntityManager
      */
-    public function load(ObjectManager $manager);
+    public function load(ObjectManager $manager): void;
 }

src/Loader.php

@@ -72,7 +72,7 @@
      *
      * @return array $fixtures Array of loaded fixture object instances.
      */
-    public function loadFromDirectory(string $dir)
+    public function loadFromDirectory(string $dir): array
     {
         if (! is_dir($dir)) {
             throw new InvalidArgumentException(sprintf('"%s" does not exist', $dir));
@@ -93,7 +93,7 @@
      *
      * @return array $fixtures Array of loaded fixture object instances.
      */
-    public function loadFromFile(string $fileName)
+    public function loadFromFile(string $fileName): array
     {
         if (! is_readable($fileName)) {
             throw new InvalidArgumentException(sprintf('"%s" does not exist or is not readable', $fileName));
@@ -106,20 +106,16 @@
 
     /**
      * Has fixture?
-     *
-     * @return bool
      */
-    public function hasFixture(FixtureInterface $fixture)
+    public function hasFixture(FixtureInterface $fixture): bool
     {
         return isset($this->fixtures[$fixture::class]);
     }
 
     /**
      * Get a specific fixture instance
-     *
-     * @return FixtureInterface
      */
-    public function getFixture(string $className)
+    public function getFixture(string $className): FixtureInterface
     {
         if (! isset($this->fixtures[$className])) {
             throw new InvalidArgumentException(sprintf(
@@ -134,7 +130,7 @@
     /**
      * Add a fixture object instance to the loader.
      */
-    public function addFixture(FixtureInterface $fixture)
+    public function addFixture(FixtureInterface $fixture): void
     {
         $fixtureClass = $fixture::class;
 
@@ -196,10 +192,8 @@
      * class.
      *
      * @psalm-param class-string<object> $className
-     *
-     * @return bool
      */
-    public function isTransient(string $className)
+    public function isTransient(string $className): bool
     {
         $rc = new ReflectionClass($className);
         if ($rc->isAbstract()) {
@@ -213,10 +207,8 @@
 
     /**
      * Creates the fixture object from the class.
-     *
-     * @return FixtureInterface
      */
-    protected function createFixture(string $class)
+    protected function createFixture(string $class): FixtureInterface
     {
         return new $class();
     }
@@ -252,10 +244,8 @@
 
     /**
      * Orders fixtures by dependencies
-     *
-     * @return void
      */
-    private function orderFixturesByDependencies()
+    private function orderFixturesByDependencies(): void
     {
         /** @psalm-var array<class-string<DependentFixtureInterface>, int> */
         $sequenceForClasses = [];

src/OrderedFixtureInterface.php

@@ -13,8 +13,6 @@ interface OrderedFixtureInterface
 {
     /**
      * Get the order of this fixture
-     *
-     * @return int
      */
-    public function getOrder();
+    public function getOrder(): int;
 }