protonemedia/laravel-eloquent-where-not

Laravel package to invert Eloquent scopes.

1.2.0 2022-02-04 09:46 UTC

This package is auto-updated.

Last update: 2022-07-01 00:13:29 UTC


README

Latest Version on Packagist run-tests Quality Score Total Downloads Buy us a tree

Included in Laravel 9.2.0!

As of Laravel 9.2.0, you may use the native whereNot method. This package will be maintained for some time for Laravel 8 users but will be deprecated eventually.

📺 Want to see this package in action? Join the live stream on December 10 at 13:30 CET: https://youtu.be/fAY75SLQj3w

Requirements

  • PHP 7.4+
  • Laravel 8.0 or 9.0

This package is tested with GitHub Actions using MySQL 5.7, PostgreSQL 10.8 and SQLite.

Features

  • Flip/invert your scope, or really any query constraint.
  • Zero third-party dependencies.

Related package: Laravel Eloquent Scope as Select

Support

We proudly support the community by developing Laravel packages and giving them away for free. Keeping track of issues and pull requests takes time, but we're happy to help! If this package saves you time or if you're relying on it professionally, please consider supporting the maintenance and development.

Blogpost

If you want to know more about the background of this package, please read the blogpost: Apply the opposite of your Eloquent scope to the Query Builder with a Laravel package.

Installation

You can install the package via composer:

composer require protonemedia/laravel-eloquent-where-not

Add the macro to the query builder, for example, in your AppServiceProvider. By default, the name of the macro is whereNot, but you can customize it with the first parameter of the addMacro method.

use ProtoneMedia\LaravelEloquentWhereNot\WhereNot;

public function boot()
{
    WhereNot::addMacro();

    // or use a custom method name:
    WhereNot::addMacro('not');
}

Short API description

For a more practical explanation, check out the usage section below.

Call the whereNot method with a Closure:

Post::whereNot(function ($query) {
    $query->onFrontPage();
})->get();

The example above can be shortened by using a string, which should be the name of the scope:

Post::whereNot('onFrontPage')->get();

You can use an array to call multiple scopes:

Post::whereNot(['popular', 'published'])->get();

Use an associative array to call dynamic scopes:

Post::whereNot(['ofType' => 'announcement'])->get();

If your dynamic scopes require multiple arguments, you can use an associative array:

Post::whereNot(['publishedBetween' => [2010, 2020]])->get();

You can also mix dynamic and non-dynmaic scopes:

Post::whereNot([
    'published',
    'ofType' => 'announcement'
])->get();

Usage

Imagine you have a Post Eloquent model with a query scope that constraints the query to all posts that should make the front page.

class Post extends Model
{
    public function user()
    {
        return $this->belongsTo(User::class);
    }

    public function comments()
    {
        return $this->hasMany(Comment::class);
    }

    public function scopeOnFrontPage($query)
    {
        $query->where('is_public', 1)
            ->where('votes', '>', 100)
            ->has('comments', '>=', 20)
            ->whereHas('user', fn($user) => $user->isAdmin())
            ->whereYear('published_at', date('Y'));
    }
}

Now you can fetch all posts for your front page by calling the scope method on the query:

$posts = Post::onFrontPage()->get();

But what if you want to fetch all posts that didn't make the front page? Using the power of this package, you can re-use your scope!

$posts = Post::whereNot(function($query) {
    $query->onFrontPage();
})->get();

With short closures, a feature which was introduced in PHP 7.4, this can be even shorter:

$posts = Post::whereNot(fn ($query) => $query->onFrontPage())->get();

Shortcuts

Instead of using a Closure, there are some shortcuts you could use (see also: Short API description):

Using a string instead of a Closure:

Post::whereNot(function ($query) {
    $query->published();
});

// is the same as:

Post::whereNot('published');

Using an array instead of Closure, to support multiple scopes and dynamic scopes:

Post::whereNot(function ($query) {
    $query->ofType('announcement');
});

// is the same as:

Post::whereNot(['ofType' => 'announcement']);

Testing

composer test

Changelog

Please see CHANGELOG for more information about what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Other Laravel packages

  • Laravel Analytics Event Tracking: Laravel package to easily send events to Google Analytics.
  • Laravel Blade On Demand: Laravel package to compile Blade templates in memory.
  • Laravel Cross Eloquent Search: Laravel package to search through multiple Eloquent models.
  • Laravel Eloquent Scope as Select: Stop duplicating your Eloquent query scopes and constraints in PHP. This package lets you re-use your query scopes and constraints by adding them as a subquery.
  • Laravel FFMpeg: This package provides an integration with FFmpeg for Laravel. The storage of the files is handled by Laravel's Filesystem.
  • Laravel Form Components: Blade components to rapidly build forms with Tailwind CSS Custom Forms and Bootstrap 4. Supports validation, model binding, default values, translations, includes default vendor styling and fully customizable!
  • Laravel Paddle: Paddle.com API integration for Laravel with support for webhooks/events.
  • Laravel Verify New Email: This package adds support for verifying new email addresses: when a user updates its email address, it won't replace the old one until the new one is verified.
  • Laravel WebDAV: WebDAV driver for Laravel's Filesystem.

Security

If you discover any security related issues, please email pascal@protone.media instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

Treeware

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.