{"id":21558504,"url":"https://github.com/andrewdalpino/dataloader-php","last_synced_at":"2025-04-10T10:42:24.571Z","repository":{"id":56947949,"uuid":"110200395","full_name":"andrewdalpino/DataLoader-PHP","owner":"andrewdalpino","description":"A speed layer that enables query batching, de-duplication, and caching for efficient data fetching over any storage backend.","archived":false,"fork":false,"pushed_at":"2018-02-28T04:52:03.000Z","size":41,"stargazers_count":9,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-09-23T03:24:48.673Z","etag":null,"topics":["buffer","cache","dataloader","deduplication","graphql","optimization","php","storage"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andrewdalpino.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-11-10T03:56:35.000Z","updated_at":"2024-09-06T13:55:16.000Z","dependencies_parsed_at":"2022-08-21T07:20:53.517Z","dependency_job_id":null,"html_url":"https://github.com/andrewdalpino/DataLoader-PHP","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewdalpino%2FDataLoader-PHP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewdalpino%2FDataLoader-PHP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewdalpino%2FDataLoader-PHP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewdalpino%2FDataLoader-PHP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrewdalpino","download_url":"https://codeload.github.com/andrewdalpino/DataLoader-PHP/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248199616,"owners_count":21063718,"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":["buffer","cache","dataloader","deduplication","graphql","optimization","php","storage"],"created_at":"2024-11-24T08:15:00.522Z","updated_at":"2025-04-10T10:42:24.553Z","avatar_url":"https://github.com/andrewdalpino.png","language":"PHP","readme":"# DataLoader PHP\r\nA thin caching and data access layer that goes over your existing storage layer and infrastructure. DataLoader PHP uses  buffering and cache memoization to optimize requests to the storage layer, prevent overfetching, and prevent N+1 access pattern issues. Based on the [Facebook Javascript reference implementation](https://github.com/facebook/dataloader).\r\n\r\n### Features\r\n- Fast in-memory buffering, deduplication, and memoization out of the box\r\n- Simple, lightweight, and no dependencies\r\n- Storage layer agnostic (use with Redis, MySQL, MongoDB, a REST endpoint, anything you want)\r\n\r\n## Installation\r\nInstall DataLoader PHP using composer:\r\n```sh\r\ncomposer require andrewdalpino/dataloader-php\r\n```\r\n\r\n## Getting Started\r\nFirst, you need to create a batch function that will perform the duty of fetching the buffered entities from storage (Redis, REST endpoint, etc.) when necessary. The batch function takes an array of buffered keys as its only argument and **must** return an array or iterable object.\r\n\r\n```php\r\n$batchFunction = function ($keys) {\r\n    return Redis::mget(...$keys);\r\n};\r\n```\r\n\r\n```php\r\n$loader = new BatchingDataLoader($batchFunction);\r\n```\r\n\r\nOptionally, you can specify a cache key function that tells DataLoader how to key the loaded entities. The cache key function takes the `$entity` to be keyed as an argument as well as its index in the returned array. If you do not specify a cache key function then DataLoader will attempt to use `$entity-\u003eid`, `$entity['id']`, or fallback to the index of the returned array.\r\n\r\n```php\r\n$cacheKeyFunction = function ($entity, $index) {\r\n    return $entity['id'];\r\n};\r\n\r\n$loader = new BatchingDataLoader($batchFunction, $cacheKeyFunction);\r\n```\r\n\r\n### Example\r\nThe following is an example of how you could build a User loader in [Laravel](https://laravel.com/) using an  [Eloquent](https://laravel.com/docs/5.5/eloquent) model as the fetching API.\r\n\r\n```php\r\nuse AndrewDalpino\\DataLoader\\BatchingDataLoader;\r\nuse App\\User;\r\n\r\n// Required batch function to load users with supplied array of buffered $keys.\r\n$batchFunction = function ($keys) {\r\n    return User::findMany($keys);\r\n};\r\n\r\n// Optional cache key function returns the primary key of the user entity.\r\n$cacheKeyFunction = function ($user, $index) {\r\n    return $user-\u003eid;\r\n};\r\n\r\n$userLoader = new BatchingDataLoader($batchFunction, $cacheKeyFunction);\r\n```\r\n\r\n## Usage\r\nFirst you must buffer the keys of the entities you wish to load in the future by calling the batch method on the DataLoader object. The `batch()` function takes either a single integer or string `$key` or an array of `$keys` and will tell DataLoader to hold them in the buffer until the next `load()` operation is called.\r\n\r\n```php\r\n$userLoader-\u003ebatch(1);\r\n\r\n$userLoader-\u003ebatch([1, 2, 3, 4, 5]);\r\n```\r\n\r\nIt is important to call `batch()` on every entity you plan to load during the request cycle. DataLoader will **not** make additional requests to the storage backend if the keys are not in the buffer.\r\n\r\nOnce you have finished the batching stage, you may call `load()` to load the entities by key. The `load()` and `loadMany()` methods take a single `$key` or an array of `$keys` and return a single entity or an array of entities respectively.\r\n\r\n```php\r\n$userLoader-\u003ebatch(['a', 'b', 'c', 'd', 'e']);\r\n\r\n$user = $userLoader-\u003eload('a'); // Returns the user with primary key 'a'.\r\n\r\n$users = $userLoader-\u003eloadMany(['b', 'c', 'd', 'e']); // Returns an array of users.\r\n\r\n$users = $userLoader-\u003eloadMany(['b', 'c']); // Additional loads don't hit the database.\r\n\r\n$user = $userLoader-\u003eload('z'); // Returns null.\r\n\r\n$users = $userLoader-\u003eloadMany(['y', 'z']); // Return an empty array.\r\n```\r\n\r\n### Example\r\nThe following example demonstrates how DataLoader could be used in a [Webonyx GraphQL](https://github.com/webonyx/graphql-php) resolve function paired with the Webonyx *Deferred* mechanism to fulfill GraphQL queries. In this example, imagine that the user loader has been built and injected via an application container and accessed by its UserLoader facade.\r\n\r\n```php\r\nuse GraphQL\\Type\\Definition\\ObjectType;\r\nuse GraphQL\\Deferred;\r\nuse UserLoader;\r\n\r\n$postType = new ObjectType([\r\n    'fields' =\u003e [\r\n        'author' =\u003e [\r\n            'type' =\u003e 'UserNode',\r\n            'resolve' =\u003e function($post) {\r\n                UserLoader::batch($post-\u003eauthor_id);\r\n\r\n                return new Deferred(function () use ($post) {\r\n                    return UserLoader::load($post-\u003eauthor_id);\r\n                });\r\n            }\r\n        ],\r\n    ],\r\n]);\r\n```\r\n\r\nIn this example, whenever the *author* field on a Post node is requested in a GraphQL query, the `UserLoader` will batch the user entity supporting that data, and then wait until the resolvers have all been called to fetch the data via the Deferred callback. It is clearer to see how we avoid any N+1 access pattern issues by employing this mechanism.\r\n\r\n### Loading entities from outside of the batch function\r\nSometimes, the batch function is not the most efficient route to accessing a particular entity. Under other circumstances, such as non-primary key lookups, it's just not possible.\r\n\r\nWhen you need to load an entity into the cache from another source, other than the batch function, you may do so by calling the `prime()` method on the data loader instance. The `prime()` method takes an `$entity` to be primed as an argument. Each primed entity will be keyed by the same cache key function as the ones loaded with the batch function.\r\n\r\n```php\r\n$friend = User::find(1);\r\n\r\n$userLoader-\u003eprime($friend);\r\n```\r\n\r\n### Flushing the cache\r\nYou may flush the entire in-memory cache by calling the `flush()` method on the cache instance.\r\n\r\n```php\r\n$userLoader-\u003eflush();\r\n```\r\n\r\n## Runtime Configuration\r\nYou can tweak the runtime performance of DataLoader by supplying an array of options as the third parameter to the constructor. The options available are listed below with their default values.\r\n\r\n```php\r\n$options = [\r\n    'batch_size' =\u003e 1000 // The max number of entities to batch load in a single round trip from storage.\r\n];\r\n\r\n$loader = new BatchingDataLoader($batchFunction, $cacheKeyFunction, $options);\r\n```\r\n\r\n## Requirements\r\n- PHP 7.1.3 or above\r\n\r\n## License\r\nMIT\r\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewdalpino%2Fdataloader-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrewdalpino%2Fdataloader-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewdalpino%2Fdataloader-php/lists"}