Cómo usar Query Scopes en Laravel

Una de las características más poderosas de Laravel son los query scopes ya que son fáciles de usar, los query scopes facilitan reutilizar una condición de consulta en cualquier parte de tu aplicación sin repetirla. Un scope local vive en un modelo concreto; si quieres la misma condición en varios modelos, la pones en un trait.

Aquí hay un ejemplo de código de cómo crear un query scope en Laravel:

<?php
namespace App\Models;
 
use Illuminate\Database\Eloquent\Model;
 
class User extends Model
{
    /**
     * Scope a query to only include active users.
     *
     * @param  \Illuminate\Database\Eloquent\Builder  $query
     * @return void
     */
    public function scopeActive($query)
    {
        $query->where('active', 1);
    }
}

En el ejemplo anterior, creamos un query scope llamado Active en el modelo User, donde basicamente lo que hace agregar una condición WHERE para extraer solo los usuarios que esten activos.

La forma de usarlo sería la siguiente:

User::active()->get()

Consideraciones para usar los query scopes

Para definir y usar correctamente los query scope, debemos seguir algunas reglas:

• Todos los scopes deben recibir la variable $query.
• Con la forma clásica, el nombre del método comienza con la palabra scope seguido del nombre que queremos llamarlo.
• Desde Laravel 12.4 también puedes marcar el método con el atributo #[Scope] (Illuminate\Database\Eloquent\Attributes\Scope) y llamarlo sin prefijo, por ejemplo protected function active(Builder $query): void. Es la forma que muestra la documentación de Laravel 13, y se usa igual: User::active()->get().

En un próximo artículo voy a tratar de explicar una forma de organizar los scopes y hacer que sean "IDE friendly"

Para más información visiten este enlace: https://laravel.com/docs/13.x/eloquent#query-scopes

El paso siguiente natural es el global scope, que hace esto mismo pero automático. Los dos, y el resto de lo que aparece cuando la app ya está en marcha, están en Laravel en producción.

Fuentes

• Eloquent: Getting Started | Laravel 13.x (documentación oficial de Laravel)
• CHANGELOG.md de laravel/framework 12.x (changelog oficial; el atributo #[Scope] llegó en la v12.4.0)
• Illuminate/Database/Eloquent/Model.php en laravel/framework 13.x (código fuente de Laravel)