Contextual Attributes in Laravel

As of Laravel v11.14.0 you can use contextual attributes to add custom logic to dependency injection.

This useful feature has been utilised internally in Laravel to provide us with useful attributes like #[CurrentUser] and #[Cache('apc')].

In this article I will share some useful contextual attributes that I've been using.

While writing applications using Laravel, I have found myself wanting to inject a query builder for a specific model.

This would then play together nicely with static analysis tools like PHPStan.

Query Builder

Lets say we want to inject a query builder for a specific model, like so:

ControllerAttribute

namespace App\Http\Controllers;

final class UserController {
  /** @param  Builder<User>  $users */
  public function __construct(
    #[QueryBuilder(User::class)]
    private readonly Builder $users,
  ) {}

  public function index()
  {
    return $this->users
      ->whereNotNull('email_verified_at')
      ->get();
  }
}

namespace App\Attributes;

use Attribute;
use Illuminate\Container\Container;
use Illuminate\Contracts\Container\BindingResolutionException;
use Illuminate\Contracts\Container\ContextualAttribute;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;

/**
 * @template T of Model
 */
#[Attribute(Attribute::TARGET_PARAMETER)]
final class QueryBuilder implements ContextualAttribute
{
  /** @param class-string<T> $model */
  public function __construct(
    public string $model,
  ) {}

  /**
   * Resolve a query builder for the model.
   *
   * @param  self<T>  $attribute
   * @return Builder<T>
   *
   * @throws BindingResolutionException
   */
  public static function resolve(self $attribute, Container $container): Builder
  {
    $model = $container->make($attribute->model);

    if (! $model instanceof $attribute->model) {
      throw new BindingResolutionException(
        sprintf('Model [%s] is not an instance of [%s].',
          $attribute->model, Model::class
        )
      );
    }

    return $model->newQuery();
  }
}