vendor/doctrine/orm/lib/Doctrine/ORM/EntityRepository.php line 237

  1. <?php
  3. declare(strict_types=1);
  5. namespace Doctrine\ORM;
  7. use BadMethodCallException;
  8. use Doctrine\Common\Collections\AbstractLazyCollection;
  9. use Doctrine\Common\Collections\Criteria;
  10. use Doctrine\Common\Collections\Selectable;
  11. use Doctrine\Common\Persistence\PersistentObject;
  12. use Doctrine\DBAL\LockMode;
  13. use Doctrine\Deprecations\Deprecation;
  14. use Doctrine\Inflector\Inflector;
  15. use Doctrine\Inflector\InflectorFactory;
  16. use Doctrine\ORM\Exception\NotSupported;
  17. use Doctrine\ORM\Mapping\ClassMetadata;
  18. use Doctrine\ORM\Query\ResultSetMappingBuilder;
  19. use Doctrine\ORM\Repository\Exception\InvalidMagicMethodCall;
  20. use Doctrine\Persistence\ObjectRepository;
  22. use function array_slice;
  23. use function class_exists;
  24. use function lcfirst;
  25. use function sprintf;
  26. use function str_starts_with;
  27. use function substr;
  29. /**
  30.  * An EntityRepository serves as a repository for entities with generic as well as
  31.  * business specific methods for retrieving entities.
  32.  *
  33.  * This class is designed for inheritance and users can subclass this class to
  34.  * write their own repositories with business-specific methods to locate entities.
  35.  *
  36.  * @template T of object
  37.  * @template-implements Selectable<int,T>
  38.  * @template-implements ObjectRepository<T>
  39.  */
  40. class EntityRepository implements ObjectRepository, Selectable
  41. {
  42.     /**
  43.      * @internal This property will be private in 3.0, call {@see getEntityName()} instead.
  44.      *
  45.      * @var string
  46.      * @psalm-var class-string<T>
  47.      */
  48.     protected $_entityName;
  50.     /**
  51.      * @internal This property will be private in 3.0, call {@see getEntityManager()} instead.
  52.      *
  53.      * @var EntityManagerInterface
  54.      */
  55.     protected $_em;
  57.     /**
  58.      * @internal This property will be private in 3.0, call {@see getClassMetadata()} instead.
  59.      *
  60.      * @var ClassMetadata
  61.      * @psalm-var ClassMetadata<T>
  62.      */
  63.     protected $_class;
  65.     /** @var Inflector|null */
  66.     private static $inflector;
  68.     /** @psalm-param ClassMetadata<T> $class */
  69.     public function __construct(EntityManagerInterface $em, ClassMetadata $class)
  70.     {
  71.         $this->_entityName = $class->name;
  72.         $this->_em         = $em;
  73.         $this->_class      = $class;
  74.     }
  76.     /**
  77.      * Creates a new QueryBuilder instance that is prepopulated for this entity name.
  78.      *
  79.      * @param string      $alias
  80.      * @param string|null $indexBy The index for the from.
  81.      *
  82.      * @return QueryBuilder
  83.      */
  84.     public function createQueryBuilder($alias, $indexBy = null)
  85.     {
  86.         return $this->_em->createQueryBuilder()
  87.             ->select($alias)
  88.             ->from($this->_entityName, $alias, $indexBy);
  89.     }
  91.     /**
  92.      * Creates a new result set mapping builder for this entity.
  93.      *
  94.      * The column naming strategy is "INCREMENT".
  95.      *
  96.      * @param string $alias
  97.      *
  98.      * @return ResultSetMappingBuilder
  99.      */
  100.     public function createResultSetMappingBuilder($alias)
  101.     {
  102.         $rsm = new ResultSetMappingBuilder($this->_em, ResultSetMappingBuilder::COLUMN_RENAMING_INCREMENT);
  103.         $rsm->addRootEntityFromClassMetadata($this->_entityName, $alias);
  105.         return $rsm;
  106.     }
  108.     /**
  109.      * Creates a new Query instance based on a predefined metadata named query.
  110.      *
  111.      * @deprecated
  112.      *
  113.      * @param string $queryName
  114.      *
  115.      * @return Query
  116.      */
  117.     public function createNamedQuery($queryName)
  118.     {
  119.         Deprecation::trigger(
  120.             'doctrine/orm',
  121.             'https://github.com/doctrine/orm/issues/8592',
  122.             'Named Queries are deprecated, here "%s" on entity %s. Move the query logic into EntityRepository',
  123.             $queryName,
  124.             $this->_class->name
  125.         );
  127.         return $this->_em->createQuery($this->_class->getNamedQuery($queryName));
  128.     }
  130.     /**
  131.      * Creates a native SQL query.
  132.      *
  133.      * @deprecated
  134.      *
  135.      * @param string $queryName
  136.      *
  137.      * @return NativeQuery
  138.      */
  139.     public function createNativeNamedQuery($queryName)
  140.     {
  141.         Deprecation::trigger(
  142.             'doctrine/orm',
  143.             'https://github.com/doctrine/orm/issues/8592',
  144.             'Named Native Queries are deprecated, here "%s" on entity %s. Move the query logic into EntityRepository',
  145.             $queryName,
  146.             $this->_class->name
  147.         );
  149.         $queryMapping = $this->_class->getNamedNativeQuery($queryName);
  150.         $rsm          = new Query\ResultSetMappingBuilder($this->_em);
  151.         $rsm->addNamedNativeQueryMapping($this->_class, $queryMapping);
  153.         return $this->_em->createNativeQuery($queryMapping['query'], $rsm);
  154.     }
  156.     /**
  157.      * Clears the repository, causing all managed entities to become detached.
  158.      *
  159.      * @deprecated 2.8 This method is being removed from the ORM and won't have any replacement
  160.      *
  161.      * @return void
  162.      */
  163.     public function clear()
  164.     {
  165.         Deprecation::trigger(
  166.             'doctrine/orm',
  167.             'https://github.com/doctrine/orm/issues/8460',
  168.             'Calling %s() is deprecated and will not be supported in Doctrine ORM 3.0.',
  169.             __METHOD__
  170.         );
  172.         if (! class_exists(PersistentObject::class)) {
  173.             throw NotSupported::createForPersistence3(sprintf(
  174.                 'Partial clearing of entities for class %s',
  175.                 $this->_class->rootEntityName
  176.             ));
  177.         }
  179.         $this->_em->clear($this->_class->rootEntityName);
  180.     }
  182.     /**
  183.      * Finds an entity by its primary key / identifier.
  184.      *
  185.      * @param mixed    $id          The identifier.
  186.      * @param int|null $lockMode    One of the \Doctrine\DBAL\LockMode::* constants
  187.      *                              or NULL if no specific lock mode should be used
  188.      *                              during the search.
  189.      * @param int|null $lockVersion The lock version.
  190.      * @psalm-param LockMode::*|null $lockMode
  191.      *
  192.      * @return object|null The entity instance or NULL if the entity can not be found.
  193.      * @psalm-return ?T
  194.      */
  195.     public function find($id, $lockMode = null, $lockVersion = null)
  196.     {
  197.         return $this->_em->find($this->_entityName, $id, $lockMode, $lockVersion);
  198.     }
  200.     /**
  201.      * Finds all entities in the repository.
  202.      *
  203.      * @psalm-return list<T> The entities.
  204.      */
  205.     public function findAll()
  206.     {
  207.         return $this->findBy([]);
  208.     }
  210.     /**
  211.      * Finds entities by a set of criteria.
  212.      *
  213.      * @param int|null $limit
  214.      * @param int|null $offset
  215.      * @psalm-param array<string, mixed> $criteria
  216.      * @psalm-param array<string, string>|null $orderBy
  217.      *
  218.      * @return object[] The objects.
  219.      * @psalm-return list<T>
  220.      */
  221.     public function findBy(array $criteria, ?array $orderBy = null, $limit = null, $offset = null)
  222.     {
  223.         $persister = $this->_em->getUnitOfWork()->getEntityPersister($this->_entityName);
  225.         return $persister->loadAll($criteria, $orderBy, $limit, $offset);
  226.     }
  228.     /**
  229.      * Finds a single entity by a set of criteria.
  230.      *
  231.      * @psalm-param array<string, mixed> $criteria
  232.      * @psalm-param array<string, string>|null $orderBy
  233.      *
  234.      * @return object|null The entity instance or NULL if the entity can not be found.
  235.      * @psalm-return ?T
  236.      */
  237.     public function findOneBy(array $criteria, ?array $orderBy = null)
  238.     {
  239.         $persister = $this->_em->getUnitOfWork()->getEntityPersister($this->_entityName);
  241.         return $persister->load($criteria, null, null, [], null, 1, $orderBy);
  242.     }
  244.     /**
  245.      * Counts entities by a set of criteria.
  246.      *
  247.      * @psalm-param array<string, mixed> $criteria
  248.      *
  249.      * @return int The cardinality of the objects that match the given criteria.
  250.      *
  251.      * @todo Add this method to `ObjectRepository` interface in the next major release
  252.      */
  253.     public function count(array $criteria)
  254.     {
  255.         return $this->_em->getUnitOfWork()->getEntityPersister($this->_entityName)->count($criteria);
  256.     }
  258.     /**
  259.      * Adds support for magic method calls.
  260.      *
  261.      * @param string  $method
  262.      * @param mixed[] $arguments
  263.      * @psalm-param list<mixed> $arguments
  264.      *
  265.      * @return mixed The returned value from the resolved method.
  266.      *
  267.      * @throws BadMethodCallException If the method called is invalid.
  268.      */
  269.     public function __call($method, $arguments)
  270.     {
  271.         if (str_starts_with($method, 'findBy')) {
  272.             return $this->resolveMagicCall('findBy', substr($method, 6), $arguments);
  273.         }
  275.         if (str_starts_with($method, 'findOneBy')) {
  276.             return $this->resolveMagicCall('findOneBy', substr($method, 9), $arguments);
  277.         }
  279.         if (str_starts_with($method, 'countBy')) {
  280.             return $this->resolveMagicCall('count', substr($method, 7), $arguments);
  281.         }
  283.         throw new BadMethodCallException(sprintf(
  284.             'Undefined method "%s". The method name must start with ' .
  285.             'either findBy, findOneBy or countBy!',
  286.             $method
  287.         ));
  288.     }
  290.     /**
  291.      * @return string
  292.      * @psalm-return class-string<T>
  293.      */
  294.     protected function getEntityName()
  295.     {
  296.         return $this->_entityName;
  297.     }
  299.     /**
  300.      * {@inheritDoc}
  301.      */
  302.     public function getClassName()
  303.     {
  304.         return $this->getEntityName();
  305.     }
  307.     /** @return EntityManagerInterface */
  308.     protected function getEntityManager()
  309.     {
  310.         return $this->_em;
  311.     }
  313.     /**
  314.      * @return ClassMetadata
  315.      * @psalm-return ClassMetadata<T>
  316.      */
  317.     protected function getClassMetadata()
  318.     {
  319.         return $this->_class;
  320.     }
  322.     /**
  323.      * Select all elements from a selectable that match the expression and
  324.      * return a new collection containing these elements.
  325.      *
  326.      * @return AbstractLazyCollection
  327.      * @psalm-return AbstractLazyCollection<int, T>&Selectable<int, T>
  328.      */
  329.     public function matching(Criteria $criteria)
  330.     {
  331.         $persister = $this->_em->getUnitOfWork()->getEntityPersister($this->_entityName);
  333.         return new LazyCriteriaCollection($persister, $criteria);
  334.     }
  336.     /**
  337.      * Resolves a magic method call to the proper existent method at `EntityRepository`.
  338.      *
  339.      * @param string $method The method to call
  340.      * @param string $by     The property name used as condition
  341.      * @psalm-param list<mixed> $arguments The arguments to pass at method call
  342.      *
  343.      * @return mixed
  344.      *
  345.      * @throws InvalidMagicMethodCall If the method called is invalid or the
  346.      *                                requested field/association does not exist.
  347.      */
  348.     private function resolveMagicCall(string $method, string $by, array $arguments)
  349.     {
  350.         if (! $arguments) {
  351.             throw InvalidMagicMethodCall::onMissingParameter($method . $by);
  352.         }
  354.         if (self::$inflector === null) {
  355.             self::$inflector = InflectorFactory::create()->build();
  356.         }
  358.         $fieldName = lcfirst(self::$inflector->classify($by));
  360.         if (! ($this->_class->hasField($fieldName) || $this->_class->hasAssociation($fieldName))) {
  361.             throw InvalidMagicMethodCall::becauseFieldNotFoundIn(
  362.                 $this->_entityName,
  363.                 $fieldName,
  364.                 $method . $by
  365.             );
  366.         }
  368.         return $this->$method([$fieldName => $arguments[0]], ...array_slice($arguments, 1));
  369.     }
  370. }