Add @internal annotations; simplify ScopeCarrierInterface and ConsumerInterface

psalm.xml

@@ -1,7 +1,6 @@
 <?xml version="1.0"?>
 <psalm
     errorLevel="4"
-    resolveFromConfigFile="true"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns="https://getpsalm.org/schema/config"
     xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
@@ -12,4 +11,11 @@
             <directory name="vendor" />
         </ignoreFiles>
     </projectFiles>
+    <issueHandlers>
+        <UndefinedAttributeClass>
+            <errorLevel type="suppress">
+                <referencedClass name="JetBrains\PhpStorm\ExpectedValues" />
+            </errorLevel>
+        </UndefinedAttributeClass>
+    </issueHandlers>
 </psalm>

src/Command/Database/Delete.php

@@ -53,19 +53,4 @@ public function execute(): void
 
         parent::execute();
     }
-
-    public function register(
-        string $key,
-        mixed $value,
-        int $stream = self::DATA
-    ): void {
-        if ($stream !== self::SCOPE) {
-            return;
-        }
-        if (empty($value)) {
-            return;
-        }
-
-        $this->setScope($key, $value);
-    }
 }

src/Command/Database/Update.php

@@ -8,6 +8,7 @@
 use Cycle\ORM\Command\StoreCommand;
 use Cycle\ORM\Command\Traits\ErrorTrait;
 use Cycle\ORM\Command\Traits\ScopeTrait;
+use Cycle\ORM\Context\ConsumerInterface;
 use Cycle\ORM\Exception\CommandException;
 use Cycle\ORM\Heap\State;
 use Cycle\Database\DatabaseInterface;
@@ -17,7 +18,7 @@
  *
  * This is conditional command, it would not be executed when no fields are given!
  */
-final class Update extends StoreCommand implements ScopeCarrierInterface
+final class Update extends StoreCommand implements ScopeCarrierInterface, ConsumerInterface
 {
     use ErrorTrait;
     use ScopeTrait;
@@ -98,17 +99,8 @@ public function execute(): void
         parent::execute();
     }
 
-    public function register(string $key, mixed $value, int $stream = self::DATA): void
+    public function register(string $key, mixed $value): void
     {
-        if ($stream === self::SCOPE) {
-            if (empty($value)) {
-                return;
-            }
-
-            $this->setScope($key, $value);
-
-            return;
-        }
         $this->state->register($key, $value);
     }
 }

src/Command/ScopeCarrierInterface.php

@@ -4,13 +4,12 @@
 
 namespace Cycle\ORM\Command;
 
-use Cycle\ORM\Context\ConsumerInterface;
 use Cycle\ORM\Exception\CommandException;
 
 /**
  * Command indicates the ability to accept the forwarded scope values.
  */
-interface ScopeCarrierInterface extends CommandInterface, ConsumerInterface
+interface ScopeCarrierInterface extends CommandInterface
 {
     /**
      * Wait for the scope value. Command must not be ready until the value come.

src/Command/Traits/ErrorTrait.php

@@ -4,7 +4,11 @@
 
 namespace Cycle\ORM\Command\Traits;
 
-// describes why command has been locked up
+/**
+ * Describes why command has been locked up
+ *
+ * @internal
+ */
 trait ErrorTrait
 {
     public function __toError()

src/Command/Traits/ScopeTrait.php

@@ -6,6 +6,9 @@
 
 use Cycle\ORM\Exception\CommandException;
 
+/**
+ * @internal
+ */
 trait ScopeTrait
 {
     protected array $scope = [];
@@ -45,6 +48,9 @@ public function getAffectedRows(): int
 
     public function setScope(string $key, mixed $value): void
     {
+        if ($value === null) {
+            return;
+        }
         $this->scope[$key] = $value;
         // Indicate that context value is not required anymore.
         unset($this->waitScope[$key]);

src/Context/ConsumerInterface.php

@@ -4,28 +4,19 @@
 
 namespace Cycle\ORM\Context;
 
-use JetBrains\PhpStorm\ExpectedValues;
-
 /**
  * Provides the ability to accept the forwarded key value.
  */
 interface ConsumerInterface
 {
-    // Value destinations.
-    public const DATA = 1;
-    public const SCOPE = 2;
-
     /**
      * Accept the value forwarded by another object.
      *
      * @param string $key    Key name to accept the value.
      * @param mixed  $value  The key value.
-     * @param int    $stream One of the context types (data context, scope context).
      */
     public function register(
         string $key,
-        mixed $value,
-        #[ExpectedValues(valuesFromClass: self::class)]
-        int $stream = self::DATA
+        mixed $value
     ): void;
 }

src/Heap/Node.php

@@ -130,9 +130,9 @@ public function getInitialData(): array
         return $this->data;
     }
 
-    public function register(string $key, mixed $value, int $stream = self::DATA): void
+    public function register(string $key, mixed $value): void
     {
-        $this->getState()->register($key, $value, $stream);
+        $this->getState()->register($key, $value);
     }
 
     /**

src/Heap/State.php

@@ -166,11 +166,8 @@ public function hasValue(string $key, bool $allowNull = true): bool
         return array_key_exists($key, $this->data) || array_key_exists($key, $this->transactionData);
     }
 
-    public function register(
-        string $key,
-        mixed $value,
-        int $stream = self::DATA
-    ): void {
+    public function register(string $key, mixed $value): void
+    {
         $this->freeWaitingField($key);
 
         \Cycle\ORM\Transaction\Pool::DEBUG && print sprintf(

src/Mapper/DatabaseMapper.php

@@ -8,7 +8,6 @@
 use Cycle\ORM\Command\Database\Delete;
 use Cycle\ORM\Command\Database\Insert;
 use Cycle\ORM\Command\Database\Update;
-use Cycle\ORM\Context\ConsumerInterface;
 use Cycle\ORM\EntityRegistryInterface;
 use Cycle\ORM\Heap\Node;
 use Cycle\ORM\Heap\State;
@@ -139,7 +138,7 @@ public function queueUpdate(object $entity, Node $node, State $state): CommandIn
 
         foreach ($this->primaryKeys as $pk) {
             // set update criteria right now
-            $update->register($pk, $fromData[$pk], ConsumerInterface::SCOPE);
+            $update->setScope($pk, $fromData[$pk]);
         }
 
         return $update;
@@ -154,7 +153,7 @@ public function queueDelete(object $entity, Node $node, State $state): CommandIn
         $fromData = $node->getInitialData();
         foreach ($this->primaryKeys as $pk) {
             // set update criteria right now
-            $delete->register($pk, $fromData[$pk], ConsumerInterface::SCOPE);
+            $delete->setScope($pk, $fromData[$pk]);
         }
 
         return $delete;

src/Mapper/Proxy/ClasslessProxyFactory.php

@@ -6,6 +6,9 @@
 
 use Cycle\ORM\RelationMap;
 
+/**
+ * @internal
+ */
 class ClasslessProxyFactory
 {
     /**

src/Mapper/Proxy/ClasslessProxyTrait.php

@@ -8,6 +8,9 @@
 use Cycle\ORM\RelationMap;
 use RuntimeException;
 
+/**
+ * @internal
+ */
 trait ClasslessProxyTrait
 {
     public RelationMap $__cycle_orm_rel_map;

src/Mapper/Proxy/EntityProxyTrait.php

@@ -10,6 +10,9 @@
 use Cycle\ORM\RelationMap;
 use RuntimeException;
 
+/**
+ * @internal
+ */
 trait EntityProxyTrait
 {
     public RelationMap $__cycle_orm_rel_map;

src/Mapper/Proxy/Hydrator/ClassPropertiesExtractor.php

@@ -7,6 +7,9 @@
 use ReflectionClass;
 use ReflectionProperty;
 
+/**
+ * @internal
+ */
 class ClassPropertiesExtractor
 {
     public const KEY_FIELDS = 'class';

src/Mapper/Proxy/Hydrator/ClosureHydrator.php

@@ -8,6 +8,9 @@
 use Cycle\ORM\Reference\ReferenceInterface;
 use Cycle\ORM\RelationMap;
 
+/**
+ * @internal
+ */
 class ClosureHydrator
 {
     /**

src/Mapper/Proxy/Hydrator/PropertyMap.php

@@ -4,6 +4,9 @@
 
 namespace Cycle\ORM\Mapper\Proxy\Hydrator;
 
+/**
+ * @internal
+ */
 class PropertyMap
 {
     public const PUBLIC_CLASS = '';

src/Mapper/Proxy/ProxyEntityFactory.php

@@ -11,6 +11,9 @@
 use Cycle\ORM\RelationMap;
 use Doctrine\Instantiator\Instantiator;
 
+/**
+ * @internal
+ */
 class ProxyEntityFactory
 {
     /**

src/Mapper/Traits/SingleTableTrait.php

@@ -6,6 +6,9 @@
 
 use Cycle\ORM\SchemaInterface;
 
+/**
+ * @internal
+ */
 trait SingleTableTrait
 {
     protected string $discriminator = '_type';

src/Parser/CompositeTypecast.php

@@ -4,6 +4,9 @@
 
 namespace Cycle\ORM\Parser;
 
+/**
+ * @internal
+ */
 final class CompositeTypecast implements TypecastInterface
 {
     /** @var TypecastInterface[] */

src/Parser/Traits/DuplicateTrait.php

@@ -7,6 +7,8 @@
 /**
  * Trait provides ability for Node to ensure that given data is unique in selection. Primary key
  * would be used to tie duplicate nodes together.
+ *
+ * @internal
  */
 trait DuplicateTrait
 {

src/Parser/Typecast.php

@@ -9,6 +9,9 @@
 use Cycle\Database\DatabaseInterface;
 use Throwable;
 
+/**
+ * @internal
+ */
 final class Typecast implements TypecastInterface
 {
     private const RULES = ['int', 'bool', 'float', 'datetime'];

src/Relation/AbstractRelation.php

@@ -13,6 +13,9 @@
 use Cycle\ORM\SchemaInterface;
 use Cycle\ORM\Select\SourceInterface;
 
+/**
+ * @internal
+ */
 abstract class AbstractRelation implements ActiveRelationInterface, \Stringable
 {
     /**

src/Relation/ActiveRelationInterface.php

@@ -9,6 +9,8 @@
 
 /**
  * Manages single branch type between parent entity and other objects.
+ *
+ * @internal
  */
 interface ActiveRelationInterface extends RelationInterface
 {

src/Relation/BelongsTo.php

@@ -16,6 +16,8 @@
  * Provides ability to link to the parent object.
  * Will claim branch up to the parent object and it's relations. To disable
  * branch walk-through use RefersTo relation.
+ *
+ * @internal
  */
 class BelongsTo extends AbstractRelation implements DependencyInterface
 {

src/Relation/DependencyInterface.php

@@ -6,6 +6,8 @@
 
 /**
  * Identical to RelationInterface but defines "left" side of the graph (relation to parent objects).
+ *
+ * @internal
  */
 interface DependencyInterface extends RelationInterface
 {

src/Relation/Embedded.php

@@ -19,6 +19,8 @@
 
 /**
  * Embeds one object to another.
+ *
+ * @internal
  */
 final class Embedded implements SameRowRelationInterface
 {

src/Relation/HasMany.php

@@ -17,6 +17,8 @@
 
 /**
  * Provides the ability to own the collection of entities.
+ *
+ * @internal
  */
 class HasMany extends AbstractRelation
 {

src/Relation/HasOne.php

@@ -12,6 +12,8 @@
 
 /**
  * Provides the ability to own and forward context values to child entity.
+ *
+ * @internal
  */
 class HasOne extends AbstractRelation
 {

src/Relation/ManyToMany.php

@@ -24,6 +24,9 @@
 use SplObjectStorage;
 use Traversable;
 
+/**
+ * @internal
+ */
 class ManyToMany extends Relation\AbstractRelation
 {
     /** @var string[] */

src/Relation/Morphed/BelongsToMorphed.php

@@ -15,6 +15,9 @@
 use Cycle\ORM\Transaction\Pool;
 use Cycle\ORM\Transaction\Tuple;
 
+/**
+ * @internal
+ */
 class BelongsToMorphed extends BelongsTo
 {
     private string $morphKey;