Added ICollection::fetchChecked()

docs/collection.md

@@ -11,21 +11,22 @@ In Orm, we use coding standard which assumes that
 
 Collection itself is **immutable**, all methods that modify the collection return a new `ICollection` instance. Collection provides following methods:
 
-| Function                                      | Description |
-| ---                                           | ---         |
-| `getBy(array $conds): ?IEntity`               | applies an additional filtering and returns the first result's entity or a `null`
-| `getByChecked(array $conds): IEntity`         | applies an additional filtering and returns the first result's entity or a throws `NoResultException`
-| `getById($primaryValue): ?IEntity`            | applies filtering by `id` property and returns the first result's entity or a `null`
-| `getByIdChecked($primaryValue): IEntity`      | applies filtering by `id` property and returns the first result's entity or a throws `NoResultException`
-| `findBy(array $conds): ICollection`           | applies an additional filtering
-| `orderBy($property, $direction): ICollection` | applies an additional ordering
+| Function                                               | Description |
+|--------------------------------------------------------| ---         |
+| `getBy(array $conds): ?IEntity`                        | applies an additional filtering and returns the first result's entity or a `null`
+| `getByChecked(array $conds): IEntity`                  | applies an additional filtering and returns the first result's entity or a throws `NoResultException`
+| `getById($primaryValue): ?IEntity`                     | applies filtering by `id` property and returns the first result's entity or a `null`
+| `getByIdChecked($primaryValue): IEntity`               | applies filtering by `id` property and returns the first result's entity or a throws `NoResultException`
+| `findBy(array $conds): ICollection`                    | applies an additional filtering
+| `orderBy($property, $direction): ICollection`          | applies an additional ordering
 | `orderBy($propertyExpression, $direction): ICollection` | applies an additional ordering using collection function
-| `orderBy(array $properties): ICollection`     | applies an additional multiple ordering
-| `resetOrderBy(): ICollection`                 | removes all defined orderings
-| `limitBy($limit, $offset): ICollection`       | limits the collection and sets the starting offset
-| `fetch(): ?IEntity`                           | returns the next unprocessed result's entity, repeated calls iterate over the whole result-set
-| `fetchAll(): IEntity[]`                       | returns the all result's entities as an array
-| `fetchPairs($key, $value): array`             | process the whole result and returns it as an associative array
+| `orderBy(array $properties): ICollection`              | applies an additional multiple ordering
+| `resetOrderBy(): ICollection`                          | removes all defined orderings
+| `limitBy($limit, $offset): ICollection`                | limits the collection and sets the starting offset
+| `fetch(): ?IEntity`                                    | returns the next unprocessed result's entity, repeated calls iterate over the whole result-set
+| `fetchChecked(): IEntity`                              | returns the next unprocessed result's entity, repeated calls iterate over the whole result-set or a throws `NoResultException`
+| `fetchAll(): IEntity[]`                                | returns the all result's entities as an array
+| `fetchPairs($key, $value): array`                      | process the whole result and returns it as an associative array
 
 #### Single result fetching
 

src/Collection/ArrayCollection.php

@@ -102,11 +102,7 @@ public function getBy(array $conds): ?IEntity
 	/** {@inheritDoc} */
 	public function getByChecked(array $conds): IEntity
 	{
-		$entity = $this->getBy($conds);
-		if ($entity === null) {
-			throw new NoResultException();
-		}
-		return $entity;
+		return $this->findBy($conds)->fetchChecked();
 	}
 
 
@@ -181,6 +177,16 @@ public function fetch(): ?IEntity
 	}
 
 
+	public function fetchChecked(): IEntity
+	{
+		$entity = $this->fetch();
+		if ($entity === null) {
+			throw new NoResultException();
+		}
+		return $entity;
+	}
+
+
 	public function fetchAll()
 	{
 		return iterator_to_array($this->getIterator());

src/Collection/DbalCollection.php

@@ -97,11 +97,7 @@ public function getBy(array $conds): ?IEntity
 	/** {@inheritDoc} */
 	public function getByChecked(array $conds): IEntity
 	{
-		$entity = $this->getBy($conds);
-		if ($entity === null) {
-			throw new NoResultException();
-		}
-		return $entity;
+		return $this->findBy($conds)->fetchChecked();
 	}
 
 
@@ -192,6 +188,16 @@ public function fetch(): ?IEntity
 	}
 
 
+	public function fetchChecked(): IEntity
+	{
+		$entity = $this->fetch();
+		if ($entity === null) {
+			throw new NoResultException();
+		}
+		return $entity;
+	}
+
+
 	public function fetchAll()
 	{
 		return iterator_to_array($this->getIterator());

src/Collection/EmptyCollection.php

@@ -75,6 +75,12 @@ public function fetch(): ?IEntity
 	}
 
 
+	public function fetchChecked(): IEntity
+	{
+		throw new NoResultException();
+	}
+
+
 	public function fetchAll()
 	{
 		return [];

src/Collection/HasManyCollection.php

@@ -81,11 +81,7 @@ public function getBy(array $conds): ?IEntity
 
 	public function getByChecked(array $conds): IEntity
 	{
-		$entity = $this->getBy($conds);
-		if ($entity === null) {
-			throw new NoResultException();
-		}
-		return $entity;
+		return $this->findBy($conds)->fetchChecked();
 	}
 
 
@@ -157,6 +153,16 @@ public function fetch(): ?IEntity
 	}
 
 
+	public function fetchChecked(): IEntity
+	{
+		$entity = $this->fetch();
+		if ($entity === null) {
+			throw new NoResultException();
+		}
+		return $entity;
+	}
+
+
 	public function fetchAll()
 	{
 		return iterator_to_array($this->getIterator());

src/Collection/ICollection.php

@@ -169,6 +169,14 @@ public function limitBy(int $limit, int $offset = null): ICollection;
 	public function fetch(): ?IEntity;
 
 
+	/**
+	 * Fetches the first row., throw if none found.
+	 * @throws NoResultException
+	 * @phpstan-return E
+	 */
+	public function fetchChecked(): IEntity;
+
+
 	/**
 	 * Fetches all records.
 	 * @return IEntity[]

tests/cases/integration/Collection/collection.phpt

@@ -348,6 +348,17 @@ class CollectionTest extends DataTestCase
 		Assert::type(EmptyCollection::class, $c8);
 		Assert::same($c8->count(), $c7->countStored());
 	}
+
+
+	public function testFetchChecked(): void
+	{
+		Assert::throws(function (): void {
+			$this->orm->books->findBy(['id' => 923])->fetchChecked();
+		}, NoResultException::class);
+
+		$book = $this->orm->books->findAll()->fetchChecked();
+		Assert::type(Book::class, $book);
+	}
 }