Метод sole

Метод sole применяется к запросу Eloquent или Query Builder и возвращает единственную модель или объект, удовлетворяющий условиям выборки. Если запрос не возвращает ни одной записи, метод выбрасывает исключение Illuminate\Database\Eloquent\ModelNotFoundException (или Illuminate\Database\RecordsNotFoundException для Query Builder). Если запрос возвращает более одной записи, выбрасывается исключение Illuminate\Database\MultipleRecordsFoundException. Метод полезен в ситуациях, когда по логике приложения должен существовать ровно один результат.

Синтаксис

<?php
	Model::where($column, $operator, $value)->sole();
?>

Пример

Давайте найдём пользователя с уникальным email-адресом:

<?php
	namespace App\Http\Controllers;
	
	use App\Models\User;
	use Illuminate\Database\MultipleRecordsFoundException;
	use Illuminate\Database\Eloquent\ModelNotFoundException;
	
	class UserController extends Controller
	{
		public function show()
		{
			try {
				$user = User::where('email', 'user@example.com')->sole();
				echo $user->name;
			} catch (ModelNotFoundException $e) {
				echo "User not found";
			} catch (MultipleRecordsFoundException $e) {
				echo "Multiple users found";
			}
		}
	}
?>

Результат выполнения кода:

"John Doe"

Пример

Давайте попробуем найти пользователя по ID, который должен быть уникальным:

<?php
	namespace App\Http\Controllers;
	
	use App\Models\User;
	
	class UserController extends Controller
	{
		public function show()
		{
			$user = User::where('id', 1)->sole();
			echo $user->name;
		}
	}
?>

Результат выполнения кода:

"Jane Smith"

Пример

Если запрос возвращает более одной записи, метод sole выбрасывает исключение:

<?php
	namespace App\Http\Controllers;
	
	use App\Models\User;
	use Illuminate\Database\MultipleRecordsFoundException;
	
	class UserController extends Controller
	{
		public function show()
		{
			try {
				$user = User::where('status', 'active')->sole();
				echo $user->name;
			} catch (MultipleRecordsFoundException $e) {
				echo "Expected only one user, but found multiple";
			}
		}
	}
?>

Результат выполнения кода:

"Expected only one user, but found multiple"

Пример

Если запрос не возвращает ни одной записи, также выбрасывается исключение:

<?php
	namespace App\Http\Controllers;
	
	use App\Models\User;
	use Illuminate\Database\Eloquent\ModelNotFoundException;
	
	class UserController extends Controller
	{
		public function show()
		{
			try {
				$user = User::where('id', 999)->sole();
				echo $user->name;
			} catch (ModelNotFoundException $e) {
				echo "User with ID 999 not found";
			}
		}
	}
?>

Результат выполнения кода:

"User with ID 999 not found"

Пример

Метод sole можно использовать с Query Builder для работы с таблицами напрямую:

<?php
	namespace App\Http\Controllers;
	
	use Illuminate\Support\Facades\DB;
	use Illuminate\Database\RecordsNotFoundException;
	use Illuminate\Database\MultipleRecordsFoundException;
	
	class UserController extends Controller
	{
		public function show()
		{
			try {
				$user = DB::table('users')
					->where('email', 'admin@example.com')
					->sole();
				echo $user->name;
			} catch (RecordsNotFoundException $e) {
				echo "User not found";
			} catch (MultipleRecordsFoundException $e) {
				echo "Multiple users found";
			}
		}
	}
?>

Результат выполнения кода:

"Admin"

Смотрите также

метод first,
который возвращает первую запись из результата запроса
метод firstOrFail,
который возвращает первую запись или выбрасывает исключение
метод find,
который находит запись по первичному ключу
метод get,
который выполняет запрос и возвращает коллекцию всех записей