{"id":29193129,"url":"https://github.com/safemood/laravel-magic-scopes","last_synced_at":"2025-07-02T02:07:41.560Z","repository":{"id":296790636,"uuid":"896762598","full_name":"Safemood/laravel-magic-scopes","owner":"Safemood","description":"Laravel Magic Scopes auto-generates  query scopes for your models — no code needed, just magic 🔮.","archived":false,"fork":false,"pushed_at":"2025-06-16T20:31:50.000Z","size":85,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-26T19:49:58.062Z","etag":null,"topics":["laravel","opensource","php"],"latest_commit_sha":null,"homepage":"https://kbouzidi.com","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Safemood.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"Khalil Bouzidi"}},"created_at":"2024-12-01T08:34:50.000Z","updated_at":"2025-06-16T20:31:48.000Z","dependencies_parsed_at":"2025-06-03T07:45:53.692Z","dependency_job_id":null,"html_url":"https://github.com/Safemood/laravel-magic-scopes","commit_stats":null,"previous_names":["safemood/laravel-magic-scopes"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Safemood/laravel-magic-scopes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Safemood%2Flaravel-magic-scopes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Safemood%2Flaravel-magic-scopes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Safemood%2Flaravel-magic-scopes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Safemood%2Flaravel-magic-scopes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Safemood","download_url":"https://codeload.github.com/Safemood/laravel-magic-scopes/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Safemood%2Flaravel-magic-scopes/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263061405,"owners_count":23407606,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["laravel","opensource","php"],"created_at":"2025-07-02T02:07:41.046Z","updated_at":"2025-07-02T02:07:41.532Z","avatar_url":"https://github.com/Safemood.png","language":"PHP","funding_links":["https://github.com/sponsors/Khalil Bouzidi"],"categories":[],"sub_categories":[],"readme":"# Laravel Magic Scopes\n\n\n\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/safemood/laravel-magic-scopes.svg?style=flat-square)](https://packagist.org/packages/safemood/laravel-magic-scopes)\n[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/safemood/laravel-magic-scopes/run-tests.yml?branch=main\u0026label=tests\u0026style=flat-square)](https://github.com/safemood/laravel-magic-scopes/actions?query=workflow%3Arun-tests+branch%3Amain)\n[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/safemood/laravel-magic-scopes/fix-php-code-style-issues.yml?branch=main\u0026label=code%20style\u0026style=flat-square)](https://github.com/safemood/laravel-magic-scopes/actions?query=workflow%3A\"Fix+PHP+code+style+issues\"+branch%3Amain)\n[![Total Downloads](https://img.shields.io/packagist/dt/safemood/laravel-magic-scopes.svg?style=flat-square)](https://packagist.org/packages/safemood/laravel-magic-scopes)\n\nLaravel Magic Scopes auto-generates  query scopes for your models — no code needed, just magic 🔮.\n\n---\n\n## Table of Contents\n\n- [Laravel Magic Scopes](#laravel-magic-scopes)\n  - [Table of Contents](#table-of-contents)\n  - [Installation](#installation)\n  - [Usage](#usage)\n    - [What It can do](#what-it-can-do)\n    - [Boolean Field Scopes](#boolean-field-scopes)\n    - [Enum Field Scopes](#enum-field-scopes)\n    - [Foreign Key Scopes](#foreign-key-scopes)\n    - [JSON Field Scopes](#json-field-scopes)\n    - [Number Field Scopes](#number-field-scopes)\n    - [Date Field Scopes](#date-field-scopes)\n  - [Extend](#extend)\n  - [Testing](#testing)\n  - [Changelog](#changelog)\n  - [Contributing](#contributing)\n  - [Security Vulnerabilities](#security-vulnerabilities)\n  - [Credits](#credits)\n  - [License](#license)\n\n\n---\n\n## Installation\n\nYou can install the package via composer:\n\n```bash\ncomposer require safemood/laravel-magic-scopes\n```\n\nYou can publish the config file with:\n\n```bash\nphp artisan vendor:publish --tag=\"magic-scopes-config\"\n```\n\nThis is the contents of the published config file:\n\n```php\n\u003c?php\n\ndeclare(strict_types=1);\n\nreturn [\n \n    'resolvers' =\u003e [\n        \\Safemood\\MagicScopes\\Resolvers\\BooleanFieldScopeResolver::class,\n        \\Safemood\\MagicScopes\\Resolvers\\DateFieldScopeResolver::class,\n        \\Safemood\\MagicScopes\\Resolvers\\EnumFieldScopeResolver::class,\n        \\Safemood\\MagicScopes\\Resolvers\\ForeignKeyFieldScopeResolver::class,\n        \\Safemood\\MagicScopes\\Resolvers\\JsonFieldScopeResolver::class,\n        \\Safemood\\MagicScopes\\Resolvers\\NumberFieldScopeResolver::class,\n        \\Safemood\\MagicScopes\\Resolvers\\StringFieldScopeResolver::class,\n    ],\n];\n\n```\n\n## Usage\n\nSimply use the HasMagicScopes trait in your Eloquent model:\n\n```php\nuse Safemood\\MagicScopes\\Traits\\HasMagicScopes;\n\nclass Post extends Model\n{\n    use HasMagicScopes;\n\n}\n\n```\n---\n### What It can do\n\n```php\n$posts = Post::where('views', '\u003e', 216) // query\n    -\u003enotPublished()                    // magic scope\n    -\u003erecent()                         // real scope\n    -\u003ecreatedAfter('2025-05-01')      // magic scope\n    -\u003eget();\n```\n---\n\n### Boolean Field Scopes\n\n```php\nPost::published()-\u003eget();             // where('is_published', true)\nPost::notPublished()-\u003eget();          // where('is_published', false)\n\nPost::hasFeaturedImage()-\u003eget();      // where('has_featured_image', true)\nPost::hasNotFeaturedImage()-\u003eget();   // where('has_featured_image', false)\n\nPost::sticky()-\u003eget();                // where('is_sticky', true)\nPost::notSticky()-\u003eget();             // where('is_sticky', false)\n\n```\n\n---\n\n### Enum Field Scopes\n\n```php\nPost::statusIs('published')-\u003eget();       // where('status', 'published')\nPost::typeIs('announcement')-\u003eget();      // where('type', 'announcement')\n```\n---\n\n### Foreign Key Scopes\n\n```php\nPost::forUser(1)-\u003eget();                  // where('user_id', 1)\nPost::forCategory([1, 2])-\u003eget();         // whereIn('category_id', [1, 2])\n\nPost::withUser()-\u003eget();                 // with('user')\nPost::withUser([1, 2])-\u003eget();           // with(['user' =\u003e fn ($q) =\u003e $q-\u003ewhereIn('id', [1, 2])])\n\nPost::withAuthor(10)-\u003eget();             // with(['author' =\u003e fn ($q) =\u003e $q-\u003ewhere('id', 10)])\n\n NOTE: \n The relationships ('user', 'author') must be properly defined on the `Post` model  (at least for now 😉)\n```\n---\n\n### JSON Field Scopes\n\n```php\nPost::rentRequestsContains('rooms_count', 2)-\u003eget();   // whereJsonContains('rent_requests-\u003erooms_count', 2)\nPost::rentContains('city', 'Tunis')-\u003eget();            // whereJsonContains('rent-\u003ecity', 'Tunis')\nPost::settingsContains('timezone', 'UTC')-\u003eget();      // whereJsonContains('settings-\u003etimezone', 'UTC')\n```\n---\n\n### Number Field Scopes\n\n```php\nPost::whereViewsGreaterThan(50)-\u003eget();     // where('views', '\u003e', 50)\nPost::whereScoreEquals(90)-\u003eget();          // where('score', '=', 90)\nPost::wherePriceBetween(100, 200)-\u003eget();   // whereBetween('price', [100, 200])\nPost::whereDownloadsEquals(10)-\u003eget();      // where('downloads', '=', 10)\n```\n---\n\n### Date Field Scopes\n\n```php\nPost::reviewedAt('2024-05-10')-\u003eget(); // Equivalent to: whereDate('reviewed_at', '2024-05-10')\n\nPost::reviewedBefore('2024-05-15')-\u003eget(); // Equivalent to: whereDate('reviewed_at', '\u003c', '2024-05-15')\n\nPost::reviewedAfter('2024-05-15')-\u003eget(); // Equivalent to: whereDate('reviewed_at', '\u003e', '2024-05-15')\n\nPost::reviewedBetween('2024-05-10', '2024-05-20')-\u003eget(); // Equivalent to: whereBetween('reviewed_at', ['2024-05-10', '2024-05-20'])\n```\n\n\n## Extend\n\nYou can create your own custom scope resolver if you want to control how scopes are resolved from method names.\n\nHere's how to create a custom ScopeResolver:\n\n⚠️ **Important:**  \nCustom resolvers should not match the same method as another resolver. \nIf multiple resolvers match, an exception is thrown to avoid conflicts.\n\n\n```php\n\u003c?php\n\ndeclare(strict_types=1);\n\nnamespace Safemood\\MagicScopes\\Resolvers;\n\nuse Illuminate\\Database\\Eloquent\\Builder;\nuse Illuminate\\Database\\Eloquent\\Model;\nuse Illuminate\\Support\\Str;\nuse Safemood\\MagicScopes\\Contracts\\ScopeResolverContract;\n\nclass CustomScopeResolver implements ScopeResolverContract\n{\n    public function matches(string $method, Builder $builder): bool\n    {\n        return Str::startWith($method, 'customPrefix');\n    }\n\n   public function apply(Builder $query, string $method, array $parameters, Model $model): Builder\n    {\n        $column = 'your_column_name'; // extract from method name\n        $value = $parameters[0] ?? null; // get the value, depending on your logic\n\n        $builder-\u003ewhere($column, $value); // Apply basic WHERE condition\n\n        return $query; // Always return the original query builder after applying conditions\n    }\n}\n```\n\n\n## Testing\n\n```bash\ncomposer test\n```\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.\n\n## Contributing\n\nPlease see [CONTRIBUTING](CONTRIBUTING.md) for details.\n\n## Security Vulnerabilities\n\nPlease review [our security policy](../../security/policy) on how to report security vulnerabilities.\n\n## Credits\n\n- [Khalil Bouzidi](https://github.com/Safemood)\n- [All Contributors](../../contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsafemood%2Flaravel-magic-scopes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsafemood%2Flaravel-magic-scopes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsafemood%2Flaravel-magic-scopes/lists"}