{"id":15025077,"url":"https://github.com/larachimp/mango-repo","last_synced_at":"2025-04-12T12:32:14.417Z","repository":{"id":47046624,"uuid":"84470262","full_name":"LaraChimp/mango-repo","owner":"LaraChimp","description":":peach: Repository Pattern for Laravel made simple.","archived":true,"fork":false,"pushed_at":"2021-09-15T20:39:34.000Z","size":109,"stargazers_count":31,"open_issues_count":0,"forks_count":8,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2025-03-29T22:13:50.056Z","etag":null,"topics":["annotations","database","laravel","orm","pattern","query-filter","repository"],"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/LaraChimp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-09T17:30:22.000Z","updated_at":"2025-03-02T12:13:14.000Z","dependencies_parsed_at":"2022-08-28T08:20:12.289Z","dependency_job_id":null,"html_url":"https://github.com/LaraChimp/mango-repo","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LaraChimp%2Fmango-repo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LaraChimp%2Fmango-repo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LaraChimp%2Fmango-repo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LaraChimp%2Fmango-repo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LaraChimp","download_url":"https://codeload.github.com/LaraChimp/mango-repo/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248566588,"owners_count":21125693,"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":["annotations","database","laravel","orm","pattern","query-filter","repository"],"created_at":"2024-09-24T20:01:29.391Z","updated_at":"2025-04-12T12:32:14.077Z","avatar_url":"https://github.com/LaraChimp.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch2 align=\"center\"\u003e\n   \u003cimg src=\"https://raw.githubusercontent.com/LaraChimp/art-work/master/packages/mango-repo/mango-repo-art.png\"\u003e Mango Repo\n\u003c/h2\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://packagist.org/packages/larachimp/mango-repo\"\u003e\u003cimg src=\"https://poser.pugx.org/larachimp/mango-repo/v/stable\" alt=\"Latest Stable Version\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://packagist.org/packages/larachimp/mango-repo\"\u003e\u003cimg src=\"https://poser.pugx.org/larachimp/mango-repo/v/unstable\" alt=\"Latest Unstable Version\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://travis-ci.org/LaraChimp/mango-repo\"\u003e\u003cimg src=\"https://travis-ci.org/LaraChimp/mango-repo.svg?branch=master\" alt=\"Build Status\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://styleci.io/repos/84470262\"\u003e\u003cimg src=\"https://styleci.io/repos/84470262/shield?branch=master\" alt=\"StyleCI\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://packagist.org/packages/larachimp/mango-repo\"\u003e\u003cimg src=\"https://poser.pugx.org/larachimp/mango-repo/license\" alt=\"License\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://packagist.org/packages/larachimp/mango-repo\"\u003e\u003cimg src=\"https://poser.pugx.org/larachimp/mango-repo/downloads\" alt=\"Total Downloads\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://insight.sensiolabs.com/projects/f21891ce-4b48-4507-aa4b-a25474571473\" alt=\"medal\"\u003e\u003cimg src=\"https://insight.sensiolabs.com/projects/f21891ce-4b48-4507-aa4b-a25474571473/mini.png\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Introduction\nMango Repo is an Eloquent Repository package that aims at bringing an easy to use and fluent API. Getting started with repository pattern can be \nquite overwhelming. This is especially true for newcomers to Eloquent who are getting the grasp of active record. Behind the scenes Mango Repo \ntries to use as much of the Eloquent API as possible and keeping things simple.\n\n## License\nMango Repo is open-sourced software licensed under the [MIT license](http://opensource.org/licenses/MIT).\n\n## Version Compatibility\n\n Laravel  | MangoRepo\n:---------|:----------\n 5.0.x    | 0.2.x\n 5.1.x    | 0.2.x\n 5.2.x    | 0.2.x\n 5.3.x    | 0.2.x\n 5.4.x    | 0.2.x\n 5.5.x    | 0.2.x\n 5.6.x    | 0.3.x\n 5.7.x    | 0.3.x\n 5.8.x    | 0.4.x\n 6.x      | 1.x\n 7.x      | 2.x\n 8.x      | 3.x\n \n### Installation\nInstall Mango Repo as you would with any other dependency managed by Composer:\n\n```bash\n$ composer require larachimp/mango-repo\n```\n\n### Configuration\n\u003e If you are using Laravel \u003e= 5.5, you can skip service registration \n\u003e thanks to Laravel auto package discovery feature.\n\nAfter installing Mango repo all you need is to register the ```LaraChimp\\MangoRepo\\MangoRepoServiceProvider``` and ```LaraChimp\\PineAnnotations\\PineAnnotationsServiceProvider``` \nin your `config/app.php` configuration file:\n\n```php\n'providers' =\u003e [\n    // Other service providers...\n\n    LaraChimp\\PineAnnotations\\PineAnnotationsServiceProvider::class,\n    LaraChimp\\MangoRepo\\MangoRepoServiceProvider::class,\n],\n```\n\nOptionally you can register the annotations reader alias.\n\n```php\n'aliases' =\u003e [\n    ...\n    'AnnotationsReader' =\u003e LaraChimp\\PineAnnotations\\Facades\\Reader::class,\n],\n```\n\nFor more information check out the [PineAnnotations package](https://github.com/LaraChimp/pine-annotations) for more information on the annotation reader.\n\n### Creating a repository class\nUse the ```mango:make``` command to create your repository classes. This command will take as argument the repository class namesapce (from App) and \na ```--model``` option which allows you to specify the full namespace of the Eloquent model to which the repository will be tied.\n\n```bash\n$ php artisan mango:make \"Repositories\\Posts\" --model=\"App\\Models\\Post\"\n```\n\nThe above command will generate the following repository class in the ```app/Repositories``` directory:\n\n```php\n\u003c?php\n\nnamespace App\\Repositories;\n\nuse LaraChimp\\MangoRepo\\Repositories\\EloquentRepository;\n\nclass Posts extends EloquentRepository\n{\n    /**\n     * The target Eloquent Model.\n     */\n    const TARGET = \\App\\Models\\Post::class;\n}\n```\n\nNotice the ```const TARGET``` which specifies the Eloquent model the repository will make use of. If you would like to keep things a little bit\nsimpler, the ```mango:make``` command allows you to specify an optional ```--annotated``` option which generates a repository class that uses annotations\nfor specifying the Eloquent model:\n\n```bash\n$ php artisan mango:make \"Repositories\\Posts\" --model=\"App\\Models\\Post\" --annotated\n```\n\nThe above command will generate the following repository class in the ```app/Repositories``` directory:\n\n```php\n\u003c?php\n\nnamespace App\\Repositories;\n\nuse LaraChimp\\MangoRepo\\Annotations\\EloquentModel;\nuse LaraChimp\\MangoRepo\\Repositories\\EloquentRepository;\n\n/**\n * @EloquentModel(target=\"App\\Models\\Post\")\n */\nclass Posts extends EloquentRepository\n{\n    //\n}\n```\n\n### Using the repository\nAfter creating your repository class, you may use it by resolving it via Laravel's Service container; either by dependency injection or by using the ```app()```\nmethod.\n\nIn the following controller, we injected our ```Posts``` repository in the constructor and used it from our index method:\n\n```php\n\u003c?php\n\nnamespace App\\Http\\Controllers;\n\nuse App\\Repositories\\Posts;\n\nclass PostController extends Controller \n{\n    /**\n     * Posts repository instance.\n     * \n     * @var Posts\n     */\n    protected $posts;\n    \n    public function __construct(Posts $posts) \n    {\n        $this-\u003eposts = $posts;\n    }\n    \n    public function index()\n    {\n        $allPosts = $this-\u003eposts-\u003eall();\n        //\n    }\n}\n```\n\n\u003e Take note that the repository class can be injected in not only controllers' constructors, but also methods and any service which is resolved by the service container.\n\nYou can also use the ```app()```, ```app()-\u003emake()``` or ```resolve()``` method to resolve an instance of your repository class and use it as you please:\n\n```php\n\u003c?php\n\nnamespace App\\Http\\Controllers;\n\nuse App\\Repositories\\Posts;\n\nclass PostController extends Controller \n{\n    public function index()\n    {\n        $posts = app()-\u003emake(Posts::class)-\u003eall();\n        //\n    }\n}\n```\n\nAlthough resolving repository classes from the service container seems the most efficient way to building up an instance, you may prefer to instantiate\nyour repository classes manually for some reasons. To achieve this call the ```boot()``` method on the new instance before using it.\n\nThe ```boot()``` method will take care of loading the repository class dependencies for us:\n\n```php\n$posts = (new \\App\\Repositories\\Posts())-\u003eboot();\n```\n\n### Available Methods\nOut of the box, repository classes comes with these methods already written for you. However, you are free to add your own methods or override \nexisting methods in your repository class for building your own custom API and business logic.\n\nTo keep things as simple as possible, for many of theses methods, Mango Repo makes use of the same methods available on the Eloquent model.\nHence, Mango Repo's API tries to be as close to Eloquent's API as possible.\n\n#### ```all()```\nGet all of the models from the database: \n\n```php\n$users = app(\\App\\Repositories\\Users::class)-\u003eall();\n\n// Illuminate\\Database\\Eloquent\\Collection\n```\nor:\n```php\n$users = app(\\App\\Repositories\\Users::class)-\u003eall(['name', 'email']);\n\n// Illuminate\\Database\\Eloquent\\Collection instance\n```\n\n#### ```paginate()```\nPaginate the models from the database:\n\n```php\n$users = app(\\App\\Repositories\\Users::class)-\u003epaginate(10, ['name', 'email']);\n\n// Illuminate\\Contracts\\Pagination\\LengthAwarePaginator instance\n```\n\n#### ```simplePaginate()```\nPaginate the models from the database into a simple paginator:\n\n```php\n$users = app(\\App\\Repositories\\Users::class)-\u003esimplePaginate(10, ['name', 'email']);\n\n// Illuminate\\Contracts\\Pagination\\Paginator\n```\n\n#### ```create()```\nSave a new model and return the instance:\n\n```php\n$user = app(\\App\\Repositories\\Users::class)-\u003ecreate([\n            'name'     =\u003e 'John Doe', \n            'email'    =\u003e 'john@doe.com'\n            'password' =\u003e Hash::make('secret')\n         ]);\n \n // Illuminate\\Database\\Eloquent\\Model\n```\n\n#### ```update()```\nUpdate a model in the database. The update method accepts as its second argument\neither the model instance or the model id:\n\n```php\napp(\\App\\Repositories\\Users::class)-\u003eupdate(['name' =\u003e 'John Smith'], $userId);\n\n// bool\n```\nor:\n```php\napp(App\\Repositories\\Users::class)-\u003eupdate(['name' =\u003e 'John Smith'], $user);\n\n// bool\n```\n\n#### ```delete()```\nDelete a record from the database.The delete method accepts as its first argument \neither the model instance or the model id:\n\n```php\napp(\\App\\Repositories\\Users::class)-\u003edelete($userId);\n\n// bool\n```\nor:\n```php\napp(\\App\\Repositories\\Users::class)-\u003edelete($user);\n\n// bool\n```\n\n#### ```find()```\nFind a Model in the Database using the ID:\n\n```php\napp(\\App\\Repositories\\Users::class)-\u003efind($userId);\n\n// Illuminate\\Database\\Eloquent\\Model\n```\nor:\n```php\napp(\\App\\Repositories\\Users::class)-\u003efind($user_id, ['name', 'email']);\n\n// Illuminate\\Database\\Eloquent\\Model\n```\n\n#### ```findOrFail()```\nFind a model in the database or throw an exception:\n\n```php\napp(\\App\\Repositories\\Users::class)-\u003efindOrFail($userId);\n\n// Illuminate\\Database\\Eloquent\\Model\n```\nor:\n```php\napp(\\App\\Repositories\\Users::class)-\u003efindOrFail($userId, ['name', 'email']);\n\n// Illuminate\\Database\\Eloquent\\Model\n```\n\n#### ```findBy()```\nFind a model or models using some criteria:\n\n```php\napp(\\App\\Repositories\\Users::class)-\u003efindBy(['last_name' =\u003e 'Doe']);\n\n// Illuminate\\Database\\Eloquent\\Collection\n```\nor:\n```php\napp(\\App\\Repositories\\Users::class)-\u003efindBy(['last_name' =\u003e 'Doe'], ['last_name', 'email']);\n\n// Illuminate\\Database\\Eloquent\\Collection\n```\n\n#### ```getModel()```\nGets the Eloquent model instance:\n\n```php\napp(\\App\\Repositories\\Users::class)-\u003egetModel();\n\n// Illuminate\\Database\\Eloquent\\Model\n```\n\n### Model Repository Scoping\nMango Repo do not make use of long and tedious \"Criterias classes\" for filtering queries, instead any repository class \ncreated using the ```mango:make``` command can be \"Model Scoped\". In simpler terms this only means that you may access \n[Local Query Scopes](https://laravel.com/docs/master/eloquent#local-scopes) defined on your models directly on the repository class.\n\nHence, you define your query scopes once on your model classes and use them directly on your repository classes for query filtering.\n\nConsider the following example:\n\n```php\n\u003c?php\n\nnamespace LaraChimp\\MangoRepo\\Tests\\Fixtures\\Models;\n\nuse Illuminate\\Database\\Eloquent\\Model;\nuse Illuminate\\Database\\Eloquent\\Builder;\n\nclass User extends Model\n{\n    //...\n    \n    /**\n     * Apply an is active scope filter to the model.\n     *\n     * @param Builder $query\n     *\n     * @return Builder\n     */\n    public function scopeActive($query)\n    {\n        return $query-\u003ewhere('is_active', true);\n    }\n}\n```\n\nSince we've defined a local scope ```Active``` on our User Model, we don't have to rewrite the same scope twice within our\nrepository class. We simple use it directly on the repository class. Yes as simple as that!\n\n```php\n$activeUsers = app(\\App\\Repositories\\Users::class)-\u003eactive()-\u003eget();\n\n// Illuminate\\Database\\Eloquent\\Collection\n```\n\nYou may even chain scopes and apply other filters as you would for any Eloquent model instance:\n\n```php\n $users = app(\\App\\Repositories\\Users::class)-\u003epopular()-\u003eactive()-\u003eorderBy('created_at')-\u003eget();\n \n // Illuminate\\Database\\Eloquent\\Collection\n```\n\n### Going Further\nWe think we've done a good job here at creating a simple but yet rich boilerplate for creating repository classes and in most cases\nyou would probably just create repository classes using the ```mango:make``` command like a breeze. However, if you still are not satisfied\nand require creating your custom repository classes that do not need to be Model Scoped and so on; fear not we've got you covered.\n\nFirst start by creating a class that implements ```LaraChimp\\MangoRepo\\Contracts\\RepositoryInterface```. Now you may implement all the\nmethods available as you wish.\n\n```php\n\u003c?php\n\nnamespace Acme\\Company;\n\nuse LaraChimp\\MangoRepo\\Contracts\\RepositoryInterface;\n\nclass MyCompanyRepo implements RepositoryInterface\n{\n    public function all($columns = ['*'])\n    {\n        // ...\n    }\n    \n    // ...\n}\n```\n\nRemember you do not need to implement these methods again, you may use the ```LaraChimp\\MangoRepo\\Concerns\\IsRepositorable``` trait \nwhich already implements those method for you:\n\n```php\n\u003c?php\n\nnamespace Acme\\Company;\n\nuse LaraChimp\\MangoRepo\\Concerns\\IsRepositorable;\nuse LaraChimp\\MangoRepo\\Contracts\\RepositoryInterface;\n\nclass MyCompanyRepo implements RepositoryInterface\n{\n    use IsRepositorable;\n    \n    // ...\n}\n```\n\nIf you would like the repository to be bootable use the ```LaraChimp\\MangoRepo\\Concerns\\IsRepositoryBootable``` trait, and for Model Scoping\nuse ```LaraChimp\\MangoRepo\\Concerns\\IsRepositoryScopable``` :\n\n```php\n\u003c?php\n\nnamespace Acme\\Company;\n\nuse LaraChimp\\MangoRepo\\Concerns;\nuse LaraChimp\\MangoRepo\\Contracts\\RepositoryInterface;\n\nclass MyCompanyRepo implements RepositoryInterface\n{\n    use Concerns\\IsRepositorable,\n        Concerns\\IsRepositoryBootable,\n        Concerns\\IsRepositoryScopable;\n    \n    // ...\n}\n```\n\n### Credits\nBig Thanks to all developers who worked hard to create something amazing!\n\n[![LaraChimp](https://img.shields.io/badge/Author-LaraChimp-blue.svg?style=flat-square)](https://github.com/LaraChimp)\n\n#### Creator\nTwitter: [@PercyMamedy](https://twitter.com/PercyMamedy)\n\nGitHub: [percymamedy](https://github.com/percymamedy)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flarachimp%2Fmango-repo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flarachimp%2Fmango-repo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flarachimp%2Fmango-repo/lists"}