How do query scopes work in Laravel?

Question

I'm watching the Laracasts: Laravel 5.4 from Scratch series, and have come across the concept of query scopes.

In the video, we set up a class like this:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Task extends Model
{

    public function scopeIncomplete($query)
    {

        return $query->where('completed', 0);

    }
}

My first question:

Why is a method like: public function scopeIncomplete($query) called like this: App\Task::incomplete() with the :: operator?

Isn't that a non-static method being called statically?

My second question:

Where does $query come from?

From what I can understand this is the "existing" query, but it is called like this: App\Task::incomplete()->where('id', '>', 1)->get();

So I'm not really sure where this variable is coming from.

Maybe it's explained more in depth later but I can't wrap my head around how this works.

Answer 1

This is pretty broad since it is covering two large topics on Eloquent.

---

The first refers to Eloquent's use of the facade pattern to pass static calls to non-static methods.

The facade pattern utilizes the IoC container to pass a method call to a bound, or new, instance of a class.

The facade pattern makes use of overloading and the magic method __callStatic.

---

The second question refers to Eloquent's overloading that passes the unregistered method calls to a query builder object (specifically \Illuminate\Database\Eloquent\Builder). This is what allows for where() and various other Query Builder methods to be called on the Eloquent model itself. Inside the Model class, you can see:

/**
 * Handle dynamic method calls into the model.
 *
 * @param  string  $method
 * @param  array  $parameters
 * @return mixed
 */
public function __call($method, $parameters)
{
    if (in_array($method, ['increment', 'decrement'])) {
        return $this->$method(...$parameters);
    }

    return $this->newQuery()->$method(...$parameters);
}

Since where() or incomplete() are not defined in Model, they'll be passed to the Builder class, which is returned by Model::newQuery().

Inside the Builder __call method, you have:

    if (method_exists($this->model, $scope = 'scope'.ucfirst($method))) {
        return $this->callScope([$this->model, $scope], $parameters);
    }

So this is checking for the scopes defined inside the model and passing the $parameters which includes this Builder instance.

So in summary, the call for Model::incomplete() will go:

Model __call() -> Builder __call() -> Model scopeIncomplete(Builder $builder)