{"id":25391609,"url":"https://github.com/awes-io/repository","last_synced_at":"2025-10-11T10:14:11.403Z","repository":{"id":34913533,"uuid":"189577393","full_name":"awes-io/repository","owner":"awes-io","description":"🖖Repository Pattern in Laravel. The package allows to filter by request out-of-the-box, as well as to integrate customized criteria and any kind of filters.","archived":false,"fork":false,"pushed_at":"2023-04-25T05:12:00.000Z","size":141,"stargazers_count":171,"open_issues_count":16,"forks_count":22,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-08-29T06:39:41.337Z","etag":null,"topics":["criteria","filters","laravel","pattern","php","repository","scope"],"latest_commit_sha":null,"homepage":"","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/awes-io.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":"contributing.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null},"funding":{"patreon":"awesdotio","open_collective":"awesdotio"}},"created_at":"2019-05-31T10:41:49.000Z","updated_at":"2025-07-25T23:55:34.000Z","dependencies_parsed_at":"2024-01-29T11:11:05.261Z","dependency_job_id":null,"html_url":"https://github.com/awes-io/repository","commit_stats":{"total_commits":73,"total_committers":5,"mean_commits":14.6,"dds":0.1917808219178082,"last_synced_commit":"6835ce5ba805a7075fb64fd7db36093a95e2b6ad"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/awes-io/repository","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awes-io%2Frepository","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awes-io%2Frepository/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awes-io%2Frepository/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awes-io%2Frepository/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/awes-io","download_url":"https://codeload.github.com/awes-io/repository/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awes-io%2Frepository/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279006838,"owners_count":26084203,"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","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["criteria","filters","laravel","pattern","php","repository","scope"],"created_at":"2025-02-15T15:56:07.788Z","updated_at":"2025-10-11T10:14:11.380Z","avatar_url":"https://github.com/awes-io.png","language":"PHP","funding_links":["https://patreon.com/awesdotio","https://opencollective.com/awesdotio","https://www.patreon.com/join/awesdotio"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://www.awes.io/?utm_source=github\u0026utm_medium=repository\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n        \u003cimg width=\"100\" src=\"https://static.awes.io/promo/Logo_sign_color.svg\" alt=\"Awes.io logo\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eRepository\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003eRepository Pattern in Laravel. The package allows to filter by request out-of-the-box, as well as to integrate customized criteria and any kind of filters.\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://www.awes.io/?utm_source=github\u0026amp;utm_medium=shields\"\u003e\n        \u003cimg src=\"https://repo.pkgkit.com/4GBWO/awes-io/repository/badges/master/coverage.svg\" alt=\"Coverage report\" \u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://www.awes.io/?utm_source=github\u0026amp;utm_medium=shields\"\u003e\n        \u003cimg src=\"https://www.pkgkit.com/4GBWO/awes-io/repository/version.svg\" alt=\"Last version\" \u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://www.awes.io/?utm_source=github\u0026amp;utm_medium=shields\"\u003e\n        \u003cimg src=\"https://repo.pkgkit.com/4GBWO/awes-io/repository/badges/master/build.svg\" alt=\"Build status\" \u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://www.awes.io/?utm_source=github\u0026amp;utm_medium=shields\"\u003e\n        \u003cimg src=\"https://www.pkgkit.com/4GBWO/awes-io/repository/downloads.svg\" alt=\"Downloads\" \u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://www.awes.io/?utm_source=github\u0026amp;utm_medium=shields\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/license/awes-io/repository.svg\" alt=\"License\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://www.awes.io/?utm_source=github\u0026amp;utm_medium=shields\"\u003e\n        \u003cimg src=\"https://www.pkgkit.com/4GBWO/awes-io/repository/status.svg\" alt=\"CDN Ready\" /\u003e \n    \u003c/a\u003e\n    \u003ca href=\"https://www.awes.io/?utm_source=github\u0026amp;utm_medium=shields\" target=\"_blank\"\u003e\n        \u003cimg src=\"https://static.pkgkit.com/badges/laravel.svg\" alt=\"laravel\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://www.awes.io/?utm_source=github\u0026amp;utm_medium=shields\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/last-commit/awes-io/repository.svg\" alt=\"Last commit\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/awes-io/awes-io\"\u003e\n        \u003cimg src=\"https://ga-beacon.appspot.com/UA-134431636-1/awes-io/repository\" alt=\"Analytics\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://www.pkgkit.com/?utm_source=github\u0026amp;utm_medium=shields\"\u003e\n        \u003cimg src=\"https://www.pkgkit.com/badges/hosted.svg\" alt=\"Hosted by Package Kit\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://www.patreon.com/join/awesdotio\"\u003e\n        \u003cimg src=\"https://static.pkgkit.com/badges/patreon.svg\" alt=\"Patreon\" /\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n##\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://static.awes.io/github/repository-cover.png\" alt=\"Repository Laravel\" /\u003e\n\u003c/p\u003e\n\n\n## Table of Contents\n\n- \u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e\n- \u003ca href=\"#configuration\"\u003eConfiguration\u003c/a\u003e\n- \u003ca href=\"#overview\"\u003eOverview\u003c/a\u003e\n- \u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e\n    - \u003ca href=\"#create-a-model\"\u003eCreate a Model\u003c/a\u003e\n    - \u003ca href=\"#create-a-repository\"\u003eCreate a Repository\u003c/a\u003e\n    - \u003ca href=\"#use-built-in-methods\"\u003eUse built-in methods\u003c/a\u003e\n    - \u003ca href=\"#create-a-criteria\"\u003eCreate a Criteria\u003c/a\u003e\n    - \u003ca href=\"#scope-filter-and-order\"\u003eScope, Filter, and Order\u003c/a\u003e\n    - \u003ca href=\"#artisan-commands\"\u003eArtisan Commands\u003c/a\u003e\n- \u003ca href=\"#testing\"\u003eTesting\u003c/a\u003e\n\n## Installation\n\nVia Composer\n\n``` bash\n$ composer require awes-io/repository\n```\n\nThe package will automatically register itself.\n\n## Configuration\n\nFirst publish config:\n\n```bash\nphp artisan vendor:publish --provider=\"AwesIO\\Repository\\RepositoryServiceProvider\" --tag=\"config\"\n```\n\n```php\n// $repository-\u003esmartPaginate() related parameters\n'smart_paginate' =\u003e [\n    // name of request parameter to take paginate by value from\n    'request_parameter' =\u003e 'limit',\n    // default paginate by value\n    'default_limit' =\u003e 15,\n    // max paginate by value\n    'max_limit' =\u003e 100,\n]\n```\n\n## Overview\n\n\n##### Package allows you to filter data based on incoming request parameters:\n\n```\nhttps://example.com/news?title=Title\u0026custom=value\u0026orderBy=name_desc\n```\n\nIt will automatically apply built-in constraints onto the query as well as any custom scopes and criteria you need:\n\n```php\nprotected $searchable = [\n    // where 'title' equals 'Title'\n    'title',\n];\n\nprotected $scopes = [\n    // and custom parameter used in your scope\n    'custom' =\u003e MyScope::class,\n];\n```\n\n```php\nclass MyScope extends ScopeAbstract\n{\n    public function scope($builder, $value, $scope)\n    {\n        return $builder-\u003ewhere($scope, $value)-\u003eorWhere(...);\n    }\n}\n```\n\nOrdering by any field is available:\n\n```php\nprotected $scopes = [\n    // orderBy field\n    'orderBy' =\u003e OrderByScope::class,\n];\n```\n\nPackage can also apply any custom criteria:\n\n```php\nreturn $this-\u003enews-\u003ewithCriteria([\n    new MyCriteria([\n        'category_id' =\u003e '1', 'name' =\u003e 'Name'\n    ])\n    ...\n])-\u003eget();\n```\n\n## Usage\n\n### Create a Model\n\nCreate your model:\n\n```php\nnamespace App;\n\nuse Illuminate\\Database\\Eloquent\\Model;\n\nclass News extends Model \n{\n    ...\n}\n```\n\n### Create a Repository\n\nExtend it from `AwesIO\\Repository\\Eloquent\\BaseRepository` and provide `entity()` method to return full model class name:\n\n```php\nnamespace App;\n\nuse AwesIO\\Repository\\Eloquent\\BaseRepository;\n\nclass NewsRepository extends BaseRepository\n{\n    public function entity()\n    {\n        return News::class;\n    }\n}\n```\n\n### Use built-in methods\n\n```php\nuse App\\NewsRepository;\n\nclass NewsController extends BaseController \n{\n    protected $news;\n\n    public function __construct(NewsRepository $news)\n    {\n        $this-\u003enews = $news;\n    }\n    ....\n}\n```\n\nExecute the query as a \"select\" statement or get all results:\n\n```php\n$news = $this-\u003enews-\u003eget();\n```\n\nExecute the query and get the first result:\n\n```php\n$news = $this-\u003enews-\u003efirst();\n```\n\nFind a model by its primary key:\n\n```php\n$news = $this-\u003enews-\u003efind(1);\n```\n\nAdd basic where clauses and execute the query:\n\n```php\n$news = $this-\u003enews-\u003e-\u003efindWhere([\n        // where id equals 1\n        'id' =\u003e '1',\n        // other \"where\" operations\n        ['news_category_id', '\u003c', '3'],\n        ...\n    ]);\n```\n\nPaginate the given query:\n\n```php\n$news = $this-\u003enews-\u003epaginate(15);\n```\n\nPaginate the given query into a simple paginator:\n\n```php\n$news = $this-\u003enews-\u003esimplePaginate(15);\n```\n\nPaginate the given query by 'limit' request parameter:\n\n```php\n$news = $this-\u003enews-\u003esmartPaginate();\n```\n\nAdd an \"order by\" clause to the query:\n\n```php\n$news = $this-\u003enews-\u003eorderBy('title', 'desc')-\u003eget();\n```\n\nSave a new model and return the instance:\n\n```php\n$news = $this-\u003enews-\u003ecreate($request-\u003eall());\n```\n\nUpdate a record:\n\n```php\n$this-\u003enews-\u003eupdate($request-\u003eall(), $id);\n```\n\nDelete a record by id:\n\n```php\n$this-\u003enews-\u003edestroy($id);\n```\n\nAttach models to the parent:\n\n```php\n$this-\u003enews-\u003eattach($parentId, $relationship, $idsToAttach);\n```\n\nDetach models from the relationship:\n\n```php\n$this-\u003enews-\u003edetach($parentId, $relationship, $idsToDetach);\n```\n\nFind model or throw an exception if not found:\n\n```php\n$this-\u003enews-\u003efindOrFail($id);\n```\n\nExecute the query and get the first result or throw an exception:\n\n```php\n$this-\u003enews-\u003efirstOrFail();\n```\n\n### Create a Criteria\n\nCriteria are a way to build up specific query conditions.\n\n```php\nuse AwesIO\\Repository\\Contracts\\CriterionInterface;\n\nclass MyCriteria implements CriterionInterface {\n\n    protected $conditions;\n    \n    public function __construct(array $conditions)\n    {\n        $this-\u003econditions = $conditions;\n    }\n\n    public function apply($entity)\n    {\n        foreach ($this-\u003econditions as $field =\u003e $value) {\n            $entity = $entity-\u003ewhere($field, '=', $value);\n        }\n        return $entity;\n    }\n}\n```\n\nMultiple Criteria can be applied:\n\n```php\nuse App\\NewsRepository;\n\nclass NewsController extends BaseController \n{\n    protected $news;\n\n    public function __construct(NewsRepository $news)\n    {\n        $this-\u003enews = $news;\n    }\n\n    public function index()\n    {\n        return $this-\u003enews-\u003ewithCriteria([\n            new MyCriteria([\n                'category_id' =\u003e '1', 'name' =\u003e 'Name'\n            ]),\n            new WhereAdmin(),\n            ...\n        ])-\u003eget();\n    }\n}\n```\n\n### Scope, Filter and Order\n\nIn your repository define which fields can be used to scope your queries by setting `$searchable` property.\n\n```php\nprotected $searchable = [\n    // where 'title' equals parameter value\n    'title',\n    // orWhere equals\n    'body' =\u003e 'or',\n    // where like\n    'author' =\u003e 'like',\n    // orWhere like\n    'email' =\u003e 'orLike',\n];\n```\n\nSearch by searchables:\n\n```php\npublic function index($request)\n{\n    return $this-\u003enews-\u003escope($request)-\u003eget();\n}\n```\n\n```\nhttps://example.com/news?title=Title\u0026body=Text\u0026author=\u0026email=gmail\n```\n\nAlso several serchables enabled by default:\n\n```php\nprotected $scopes = [\n    // orderBy field\n    'orderBy' =\u003e OrderByScope::class,\n    // where created_at date is after\n    'begin' =\u003e WhereDateGreaterScope::class,\n    // where created_at date is before\n    'end' =\u003e WhereDateLessScope::class,\n];\n```\n\n```php\n$this-\u003enews-\u003escope($request)-\u003eget();\n```\n\nEnable ordering for specific fields by adding `$orderable` property to your model class:\n\n```php\npublic $orderable = ['email'];\n```\n\n```\nhttps://example.com/news?orderBy=email_desc\u0026begin=2019-01-24\u0026end=2019-01-26\n```\n\n`orderBy=email_desc` will order by email in descending order, `orderBy=email` - in ascending\n\nYou can also build your own custom scopes. In your repository override `scope()` method:\n\n```php\npublic function scope($request)\n{\n    // apply build-in scopes\n    parent::scope($request);\n\n    // apply custom scopes\n    $this-\u003eentity = (new NewsScopes($request))-\u003escope($this-\u003eentity);\n\n    return $this;\n}\n```\n\nCreate your `scopes` class and extend `ScopesAbstract`\n\n```php\nuse AwesIO\\Repository\\Scopes\\ScopesAbstract;\n\nclass NewsScopes extends ScopesAbstract\n{\n    protected $scopes = [\n        // here you can add field-scope mappings\n        'field' =\u003e MyScope::class,\n    ];\n}\n```\n\nNow you can build any scopes you need:\n\n```php\nuse AwesIO\\Repository\\Scopes\\ScopeAbstract;\n\nclass MyScope extends ScopeAbstract\n{\n    public function scope($builder, $value, $scope)\n    {\n        return $builder-\u003ewhere($scope, $value);\n    }\n}\n```\n\n### Artisan Commands\n\nPackage provides useful artisan command:\n\n```bash\nphp artisan repository:generate Models/Order --scope=Search\n```\n\n#### It'll generate several classes for ```App\\Models\\Order```:\n\nMain repository: ```App\\Repositories\\Orders\\OrdersRepository```\n\nMain scopes class: ```App\\Repositories\\Orders\\Scopes\\OrdersScopes```\n\nIndividual search scope class: ```App\\Repositories\\Orders\\Scopes\\SearchOrdersScope```\n\n## Testing\n\nThe coverage of the package is \u003ca href=\"https://www.awes.io/?utm_source=github\u0026amp;utm_medium=shields\"\u003e\u003cimg src=\"https://repo.pkgkit.com/4GBWO/awes-io/repository/badges/master/coverage.svg\" alt=\"Coverage report\"\u003e\u003c/a\u003e.\n                                   \nYou can run the tests with:\n\n```bash\ncomposer test\n```\n\n## Contributing\n\nPlease see [contributing.md](contributing.md) for details and a todolist.\n\n## Credits\n\n- [Galymzhan Begimov](https://github.com/begimov)\n- [All Contributors](contributing.md)\n\n## License\n\n[MIT](http://opensource.org/licenses/MIT)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawes-io%2Frepository","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fawes-io%2Frepository","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawes-io%2Frepository/lists"}