refactor: rename constrain to scope

Author: tntrex

src/Factory.php

@@ -15,9 +15,9 @@
 use Cycle\ORM\Exception\TypecastException;
 use Cycle\ORM\Mapper\Mapper;
 use Cycle\ORM\Relation\RelationInterface;
-use Cycle\ORM\Select\ConstrainInterface;
 use Cycle\ORM\Select\LoaderInterface;
 use Cycle\ORM\Select\Repository;
+use Cycle\ORM\Select\ScopeInterface;
 use Cycle\ORM\Select\Source;
 use Cycle\ORM\Select\SourceInterface;
 use Spiral\Core\Container;
@@ -39,9 +39,9 @@ final class Factory implements FactoryInterface
     /** @var array<string, string> */
     private $defaults = [
         Schema::REPOSITORY => Repository::class,
-        Schema::SOURCE     => Source::class,
-        Schema::MAPPER     => Mapper::class,
-        Schema::CONSTRAIN  => null,
+        Schema::SOURCE => Source::class,
+        Schema::MAPPER => Mapper::class,
+        Schema::SCOPE => null,
     ];
 
     /**
@@ -86,8 +86,8 @@ public function mapper(
         return $this->factory->make(
             $class,
             [
-                'orm'    => $orm,
-                'role'   => $role,
+                'orm' => $orm,
+                'role' => $role,
                 'schema' => $schema->define($role, Schema::SCHEMA)
             ]
         );
@@ -107,8 +107,8 @@ public function loader(
         return $this->config->getLoader($schema[Relation::TYPE])->resolve(
             $this->factory,
             [
-                'orm'    => $orm,
-                'name'   => $relation,
+                'orm' => $orm,
+                'name' => $relation,
                 'target' => $schema[Relation::TARGET],
                 'schema' => $schema[Relation::SCHEMA]
             ]
@@ -130,8 +130,8 @@ public function relation(
         return $this->config->getRelation($type)->resolve(
             $this->factory,
             [
-                'orm'    => $orm,
-                'name'   => $relation,
+                'orm' => $orm,
+                'name' => $relation,
                 'target' => $relSchema[Relation::TARGET],
                 'schema' => $relSchema[Relation::SCHEMA] + [Relation::LOAD => $relSchema[Relation::LOAD] ?? null],
             ]
@@ -165,8 +165,8 @@ public function repository(
             $class,
             [
                 'select' => $select,
-                'orm'    => $orm,
-                'role'   => $role,
+                'orm' => $orm,
+                'role' => $role,
             ]
         );
     }
@@ -194,17 +194,17 @@ public function source(
             $schema->define($role, Schema::TABLE)
         );
 
-        $constrain = $schema->define($role, Schema::CONSTRAIN) ?? $this->defaults[Schema::CONSTRAIN];
+        $scope = $schema->define($role, Schema::SCOPE) ?? $this->defaults[Schema::SCOPE];
 
-        if ($constrain === null) {
+        if ($scope === null) {
             return $source;
         }
 
-        if (!is_subclass_of($constrain, ConstrainInterface::class)) {
-            throw new TypecastException($constrain . ' does not implement ' . ConstrainInterface::class);
+        if (!is_subclass_of($scope, ScopeInterface::class)) {
+            throw new TypecastException($scope . ' does not implement ' . ScopeInterface::class);
         }
 
-        return $source->withConstrain(is_object($constrain) ? $constrain : $this->factory->make($constrain));
+        return $source->withScope(is_object($scope) ? $scope : $this->factory->make($scope));
     }
 
     /**

src/ORM.php

@@ -265,7 +265,7 @@ public function getRepository($entity): RepositoryInterface
 
         if ($this->schema->define($role, Schema::TABLE) !== null) {
             $select = new Select($this, $role);
-            $select->constrain($this->getSource($role)->getConstrain());
+            $select->scope($this->getSource($role)->getScope());
         }
 
         return $this->repositories[$role] = $this->factory->repository($this, $this->schema, $role, $select);

src/Relation/Pivoted/PivotedPromise.php

@@ -44,9 +44,9 @@ final class PivotedPromise implements PromiseInterface
 
     /**
      * @param ORMInterface $orm
-     * @param string       $target
-     * @param array        $relationSchema
-     * @param mixed        $innerKey
+     * @param string $target
+     * @param array $relationSchema
+     * @param mixed $innerKey
      */
     public function __construct(ORMInterface $orm, string $target, array $relationSchema, $innerKey)
     {
@@ -113,9 +113,9 @@ public function __resolve()
 
         /** @var ManyToManyLoader $loader */
         $loader = $loader->withContext($loader, [
-            'constrain' => $this->orm->getSource($this->target)->getConstrain(),
-            'as'        => $this->target,
-            'method'    => JoinableLoader::POSTLOAD
+            'scope' => $this->orm->getSource($this->target)->getScope(),
+            'as' => $this->target,
+            'method' => JoinableLoader::POSTLOAD
         ]);
 
         $query = $loader->configureQuery($query, [$this->innerKey]);

src/SchemaInterface.php

@@ -18,21 +18,26 @@ interface SchemaInterface
     /*
      * Various segments of schema.
      */
-    public const ROLE         = 0;
-    public const ENTITY       = 1;
-    public const MAPPER       = 2;
-    public const SOURCE       = 3;
-    public const REPOSITORY   = 4;
-    public const DATABASE     = 5;
-    public const TABLE        = 6;
-    public const PRIMARY_KEY  = 7;
+    public const ROLE = 0;
+    public const ENTITY = 1;
+    public const MAPPER = 2;
+    public const SOURCE = 3;
+    public const REPOSITORY = 4;
+    public const DATABASE = 5;
+    public const TABLE = 6;
+    public const PRIMARY_KEY = 7;
     public const FIND_BY_KEYS = 8;
-    public const COLUMNS      = 9;
-    public const RELATIONS    = 10;
-    public const CHILDREN     = 11;
-    public const CONSTRAIN    = 12;
-    public const TYPECAST     = 13;
-    public const SCHEMA       = 14;
+    public const COLUMNS = 9;
+    public const RELATIONS = 10;
+    public const CHILDREN = 11;
+    public const SCOPE = 12;
+    public const TYPECAST = 13;
+    public const SCHEMA = 14;
+
+    /**
+     * @deprecated use {@see SchemaInterface::SCOPE} instead
+     */
+    public const CONSTRAIN = self::SCOPE;
 
     /**
      * Return all roles defined within the schema.
@@ -63,7 +68,7 @@ public function defines(string $role): bool;
      * Example: $schema->define(User::class, SchemaInterface::DATABASE);
      *
      * @param string $role
-     * @param int    $property See ORM constants.
+     * @param int $property See ORM constants.
      * @return mixed
      *
      * @throws SchemaException

src/Select.php

@@ -17,6 +17,7 @@
 use Cycle\ORM\Select\JoinableLoader;
 use Cycle\ORM\Select\QueryBuilder;
 use Cycle\ORM\Select\RootLoader;
+use Cycle\ORM\Select\ScopeInterface;
 use IteratorAggregate;
 use Spiral\Database\Query\SelectQuery;
 use Spiral\Pagination\PaginableInterface;
@@ -114,18 +115,28 @@ public function __clone()
     }
 
     /**
-     * Create new Selector with applied scope. By default no constrain used.
+     * Create new Selector with applied scope. By default no scope used.
      *
-     * @param ConstrainInterface|null $constrain
+     * @param ScopeInterface|null $scope
      * @return Select
      */
-    public function constrain(ConstrainInterface $constrain = null): self
+    public function scope(?ScopeInterface $scope): self
     {
-        $this->loader->setConstrain($constrain);
+        $this->loader->setScope($scope);
 
         return $this;
     }
 
+    /**
+     * @deprecated Will be dropped in next major release. Use {@see scope()} instead.
+     * @param ConstrainInterface|null $constrain
+     * @return Select
+     */
+    public function constrain(?ConstrainInterface $constrain = null): self
+    {
+        return $this->scope($constrain);
+    }
+
     /**
      * Get Query proxy.
      *

src/Select/AbstractLoader.php

@@ -20,6 +20,7 @@
 use Cycle\ORM\Schema;
 use Cycle\ORM\Select\Traits\AliasTrait;
 use Cycle\ORM\Select\Traits\ChainTrait;
+use Cycle\ORM\Select\Traits\ScopeTrait;
 use Spiral\Database\Query\SelectQuery;
 
 /**
@@ -45,23 +46,24 @@ abstract class AbstractLoader implements LoaderInterface
 {
     use ChainTrait;
     use AliasTrait;
+    use ScopeTrait;
 
     // Loading methods for data loaders.
-    public const INLOAD    = 1;
-    public const POSTLOAD  = 2;
-    public const JOIN      = 3;
+    public const INLOAD = 1;
+    public const POSTLOAD = 2;
+    public const JOIN = 3;
     public const LEFT_JOIN = 4;
 
-    /** @var ORMInterface|SourceProviderInterface @internal */
+    /** @var ORMInterface @internal */
     protected $orm;
 
     /** @var string */
     protected $target;
 
     /** @var array */
     protected $options = [
-        'load'      => false,
-        'constrain' => true,
+        'load' => false,
+        'scope' => true,
     ];
 
     /** @var LoaderInterface[] */
@@ -75,12 +77,14 @@ abstract class AbstractLoader implements LoaderInterface
 
     /**
      * @param ORMInterface $orm
-     * @param string       $target
+     * @param string $target
      */
     public function __construct(ORMInterface $orm, string $target)
     {
         $this->orm = $orm;
         $this->target = $target;
+
+        $this->setScope($this->getSource()->getScope());
     }
 
     /**
@@ -132,6 +136,8 @@ public function getSource(): SourceInterface
      */
     public function withContext(LoaderInterface $parent, array $options = []): LoaderInterface
     {
+        $options = $this->prepareOptions($options);
+
         // check that given options are known
         if (!empty($wrong = array_diff(array_keys($options), array_keys($this->options)))) {
             throw new LoaderException(
@@ -154,9 +160,9 @@ public function withContext(LoaderInterface $parent, array $options = []): Loade
      * Load the relation.
      *
      * @param string $relation Relation name, or chain of relations separated by.
-     * @param array  $options  Loader options (to be applied to last chain element only).
-     * @param bool   $join     When set to true loaders will be forced into JOIN mode.
-     * @param bool   $load     Load relation data.
+     * @param array $options Loader options (to be applied to last chain element only).
+     * @param bool $join When set to true loaders will be forced into JOIN mode.
+     * @param bool $load Load relation data.
      * @return LoaderInterface Must return loader for a requested relation.
      *
      * @throws LoaderException
@@ -279,7 +285,7 @@ abstract protected function initNode(): AbstractNode;
      */
     protected function configureQuery(SelectQuery $query): SelectQuery
     {
-        $query = $this->applyConstrain($query);
+        $query = $this->applyScope($query);
 
         foreach ($this->join as $loader) {
             $query = $loader->configureQuery($query);
@@ -294,12 +300,6 @@ protected function configureQuery(SelectQuery $query): SelectQuery
         return $query;
     }
 
-    /**
-     * @param SelectQuery $query
-     * @return SelectQuery
-     */
-    abstract protected function applyConstrain(SelectQuery $query): SelectQuery;
-
     /**
      * Define schema option associated with the entity.
      *
@@ -325,4 +325,14 @@ protected function getEagerRelations(): \Generator
             }
         }
     }
+
+    protected function prepareOptions(array $options): array
+    {
+        if (array_key_exists('constrain', $options) && !array_key_exists('scope', $options)) {
+            $options['scope'] = $options['constrain'];
+        }
+        unset($options['constrain']);
+
+        return $options;
+    }
 }

src/Select/ConstrainInterface.php

@@ -11,15 +11,15 @@
 
 namespace Cycle\ORM\Select;
 
-/**
- * Provides the ability to modify the selector and/or entity loader. Can be used to implement multi-table inheritance.
- */
-interface ConstrainInterface
-{
+use function class_alias;
+
+class_alias(ScopeInterface::class, __NAMESPACE__ . '\ConstrainInterface');
+
+if (false) {
     /**
-     * Configure query and loader pair using proxy strategy.
-     *
-     * @param QueryBuilder $query
+     * @deprecated Use {@see ScopeInterface} instead.
      */
-    public function apply(QueryBuilder $query);
+    interface ConstrainInterface extends ScopeInterface
+    {
+    }
 }