makeabledk/laravel-querykit

v4.1.0 2024-04-08 21:57 UTC

Requires

• php: ^8.1
• illuminate/support: ^9.0|^10.0|^11.0

Requires (Dev)

• nesbot/carbon: ^2.72.3
• orchestra/testbench: ^7.0|^8.0|^9.0
• phpunit/phpunit: ^9.6|^10.5

CC-BY-SA-4.0

README

This package provides a handy way to query eloquent-scopes on model instances in Laravel.

Traditionally you may find yourself having a scopeAccepted and then additionally a ìsAccepted helper method on your model.

Well, Bon Voyage code-duplication. QueryKit is here to the rescue! 🔥

--

Makeable is web- and mobile app agency located in Aarhus, Denmark.

Installation

You can install this package via composer:

composer require makeabledk/laravel-querykit

For Laravel version prior 5.5: Add the service provider to your config/app.php:

'providers' => [
    ...
    Makeable\QueryKit\QueryKitServiceProvider::class,
];

Usage

Whenever you have a query scope on an Eloquent Model, you can apply the following trait to add QueryKit:

class Job extends Eloquent {
    use \Makeable\QueryKit\QueryKit;

    public function scopeHired($query)
    {
        return $query->whereIn('status', ['started', 'finished']);
    }
}

Out of the box Laravel offers us a convenient way to query against our database:

Job::hired()->first(); // a job with either 'started' or 'finished' status

But with query-kit you are now also able to check if a model instance passes a given scope:

$startedJob->passesScope('hired'); // true
$pendingJob->passesScope('hired'); // false

Pretty cool, right?

Much more advanced functionality is supported than this simple example.

See Currently supported methods further down.

Provided methods on QueryKit

passesScope

/**
 * Check if a model passes the given scope
 *
 * @param $name
 * @param array ...$args
 * @return bool
 */
public function passesScope($name, ...$args)

failsScope

/**
 * Check if a model fails the given scope
 *
 * @param $name
 * @param array ...$args
 * @return bool
 */
public function failsScope($name, ...$args)

Currently supported methods

As of this moment QueryKit supports the following query methods

• orWhere
• orWhereIn
• orWhereBetween
• orWhereDate
• orWhereDay
• orWhereMonth
• orWhereNotBetween
• orWhereNotIn
• orWhereNotNull
• orWhereNull
• orWhereTime
• orWhereYear
• where
• whereIn
• whereBetween
• whereDate
• whereDay
• whereMonth
• whereNotBetween
• whereNotIn
• whereNotNull
• whereNull
• whereTime
• whereYear
• whereColumn

QueryKit tries to support most of the argument types that Eloquent Builder supports, but there might exceptions.

Also, do note that advanced joins and relations queries won't work.

Extending QueryKit

Say that you want to add functionality for Laravel QueryBuilder's 'whereBetween' method:

Create a WhereBetween that implements \Makeable\QueryKit\Contracts\QueryConstraint.

class WhereBetween implements \Makeable\QueryKit\Contracts\QueryConstraint
{
    public function __construct(...$args)
    {
        // Accept scope arguments here
    }

    public function check($model)
    {
        // Return boolean
    }
}

Next register the constraint in your AppServiceProvider's register method:

public function register()
{
    \Makeable\QueryKit\Builder\Builder::registerConstraint(WhereBetween::class);
}

You can also use the above method to override the existing implementations.

Related packages

Make sure to checkout our makeabledk/laravel-eloquent-status package that streamlines the way you handle model-state across your application.

Testing

You can run the tests with:

composer test

Contributing

We are happy to receive pull requests for additional functionality. Please see CONTRIBUTING for details.

Credits

• Rasmus Christoffer Nielsen
• All Contributors

License

Attribution-ShareAlike 4.0 International. Please see License File for more information.