{"id":19881366,"url":"https://github.com/overblog/dataloader-php","last_synced_at":"2025-05-15T01:07:23.924Z","repository":{"id":12944813,"uuid":"73012600","full_name":"overblog/dataloader-php","owner":"overblog","description":"DataLoaderPhp is a generic utility to be used as part of your application's data fetching layer to provide a simplified and consistent API over various remote data sources such as databases or web services via batching and caching.","archived":false,"fork":false,"pushed_at":"2025-01-03T09:18:38.000Z","size":147,"stargazers_count":202,"open_issues_count":8,"forks_count":22,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-05-08T01:18:22.380Z","etag":null,"topics":["batch","cache","dataloader","graphql","php"],"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/overblog.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2016-11-06T19:09:20.000Z","updated_at":"2025-03-29T19:07:35.000Z","dependencies_parsed_at":"2023-12-15T09:48:03.756Z","dependency_job_id":"83a14cc3-9c1d-4bd6-b109-9fa48fd4c348","html_url":"https://github.com/overblog/dataloader-php","commit_stats":{"total_commits":73,"total_committers":12,"mean_commits":6.083333333333333,"dds":0.6301369863013699,"last_synced_commit":"333f5eb46b892e93774bc27bc5f47f186e06d03a"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/overblog%2Fdataloader-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/overblog%2Fdataloader-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/overblog%2Fdataloader-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/overblog%2Fdataloader-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/overblog","download_url":"https://codeload.github.com/overblog/dataloader-php/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254207743,"owners_count":22032749,"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":["batch","cache","dataloader","graphql","php"],"created_at":"2024-11-12T17:14:00.267Z","updated_at":"2025-05-15T01:07:18.908Z","avatar_url":"https://github.com/overblog.png","language":"PHP","readme":"# DataLoaderPHP\n\nDataLoaderPHP is a generic utility to be used as part of your application's data\nfetching layer to provide a simplified and consistent API over various remote\ndata sources such as databases or web services via batching and caching.\n\n[![GitHub Actions][GA master image]][GA master]\n[![Code Coverage][Coverage image]][CodeCov Master]\n[![Latest Stable Version](https://poser.pugx.org/overblog/dataloader-php/version)](https://packagist.org/packages/overblog/dataloader-php)\n\n## Requirements\n\nThis library requires PHP \u003e= 7.3 to work.\n\n## Getting Started\n\nFirst, install DataLoaderPHP using composer.\n\n```sh\ncomposer require \"overblog/dataloader-php\"\n```\n\nTo get started, create a `DataLoader` object.\n\n## Batching\n\nBatching is not an advanced feature, it's DataLoader's primary feature.\nCreate loaders by providing a batch loading function.\n\n\n```php\nuse Overblog\\DataLoader\\DataLoader;\n\n$myBatchGetUsers = function ($keys) { /* ... */ };\n$promiseAdapter = new MyPromiseAdapter();\n\n$userLoader = new DataLoader($myBatchGetUsers, $promiseAdapter);\n```\n\nA batch loading callable / callback accepts an Array of keys, and returns a Promise which\nresolves to an Array of values.\n\nThen load individual values from the loader. DataLoaderPHP will coalesce all\nindividual loads which occur within a single frame of execution (using `await` method) \nand then call your batch function with all requested keys.\n\n```php\n$userLoader-\u003eload(1)\n  -\u003ethen(function ($user) use ($userLoader) { return $userLoader-\u003eload($user-\u003einvitedByID); })\n  -\u003ethen(function ($invitedBy) { echo \"User 1 was invited by $invitedBy\"; });\n\n// Elsewhere in your application\n$userLoader-\u003eload(2)\n  -\u003ethen(function ($user) use ($userLoader) { return $userLoader-\u003eload($user-\u003einvitedByID); })\n  -\u003ethen(function ($invitedBy) { echo \"User 2 was invited by $invitedBy\"; });\n\n// Synchronously waits on the promise to complete, if not using EventLoop.\n$userLoader-\u003eawait(); // or `DataLoader::await()`\n```\nA naive application may have issued four round-trips to a backend for the\nrequired information, but with DataLoaderPHP this application will make at most\ntwo.\n\nDataLoaderPHP allows you to decouple unrelated parts of your application without\nsacrificing the performance of batch data-loading. While the loader presents an\nAPI that loads individual values, all concurrent requests will be coalesced and\npresented to your batch loading function. This allows your application to safely\ndistribute data fetching requirements throughout your application and maintain\nminimal outgoing data requests.\n\n#### Batch Function\n\nA batch loading function accepts an Array of keys, and returns a Promise which\nresolves to an Array of values. There are a few constraints that must be upheld:\n\n * The Array of values must be the same length as the Array of keys.\n * Each index in the Array of values must correspond to the same index in the Array of keys.\n\nFor example, if your batch function was provided the Array of keys: `[ 2, 9, 6, 1 ]`,\nand loading from a back-end service returned the values:\n\n```php\n[\n  ['id' =\u003e 9, 'name' =\u003e 'Chicago'],\n  ['id' =\u003e 1, 'name' =\u003e 'New York'],\n  ['id' =\u003e 2, 'name' =\u003e 'San Francisco']  \n]\n```\n\nOur back-end service returned results in a different order than we requested, likely\nbecause it was more efficient for it to do so. Also, it omitted a result for key `6`,\nwhich we can interpret as no value existing for that key.\n\nTo uphold the constraints of the batch function, it must return an Array of values\nthe same length as the Array of keys, and re-order them to ensure each index aligns\nwith the original keys `[ 2, 9, 6, 1 ]`:\n\n```php\n[\n  ['id' =\u003e 2, 'name' =\u003e 'San Francisco'],\n  ['id' =\u003e 9, 'name' =\u003e 'Chicago'],\n  null,\n  ['id' =\u003e 1, 'name' =\u003e 'New York']\n]\n```\n\n\n### Caching (current PHP instance)\n\nDataLoader provides a memoization cache for all loads which occur in a single\nrequest to your application. After `-\u003eload()` is called once with a given key,\nthe resulting value is cached to eliminate redundant loads.\n\nIn addition to relieving pressure on your data storage, caching results per-request\nalso creates fewer objects which may relieve memory pressure on your application:\n\n```php\n$userLoader =  new DataLoader(...);\n$promise1A = $userLoader-\u003eload(1);\n$promise1B = $userLoader-\u003eload(1);\nvar_dump($promise1A === $promise1B); // bool(true)\n```\n\n#### Clearing Cache\n\nIn certain uncommon cases, clearing the request cache may be necessary.\n\nThe most common example when clearing the loader's cache is necessary is after\na mutation or update within the same request, when a cached value could be out of\ndate and future loads should not use any possibly cached value.\n\nHere's a simple example using SQL UPDATE to illustrate.\n\n```php\nuse Overblog\\DataLoader\\DataLoader;\n\n// Request begins...\n$userLoader = new DataLoader(...);\n\n// And a value happens to be loaded (and cached).\n$userLoader-\u003eload(4)-\u003ethen(...);\n\n// A mutation occurs, invalidating what might be in cache.\n$sql = 'UPDATE users WHERE id=4 SET username=\"zuck\"';\nif (true === $conn-\u003equery($sql)) {\n  $userLoader-\u003eclear(4);\n}\n\n// Later the value load is loaded again so the mutated data appears.\n$userLoader-\u003eload(4)-\u003ethen(...);\n\n// Request completes.\n```\n\n#### Caching Errors\n\nIf a batch load fails (that is, a batch function throws or returns a rejected\nPromise), then the requested values will not be cached. However if a batch\nfunction returns an `Error` instance for an individual value, that `Error` will\nbe cached to avoid frequently loading the same `Error`.\n\nIn some circumstances you may wish to clear the cache for these individual Errors:\n\n```php\n$userLoader-\u003eload(1)-\u003ethen(null, function ($exception) {\n  if (/* determine if error is transient */) {\n    $userLoader-\u003eclear(1);\n  }\n  throw $exception;\n});\n```\n\n#### Disabling Cache\n\nIn certain uncommon cases, a DataLoader which *does not* cache may be desirable.\nCalling `new DataLoader(myBatchFn, new Option(['cache' =\u003e false ]))` will ensure that every\ncall to `-\u003eload()` will produce a *new* Promise, and requested keys will not be\nsaved in memory.\n\nHowever, when the memoization cache is disabled, your batch function will\nreceive an array of keys which may contain duplicates! Each key will be\nassociated with each call to `-\u003eload()`. Your batch loader should provide a value\nfor each instance of the requested key.\n\nFor example:\n\n```php\n$myLoader = new DataLoader(function ($keys) {\n  echo json_encode($keys);\n  return someBatchLoadFn($keys);\n}, $promiseAdapter, new Option(['cache' =\u003e false ]));\n\n$myLoader-\u003eload('A');\n$myLoader-\u003eload('B');\n$myLoader-\u003eload('A');\n\n// [ 'A', 'B', 'A' ]\n```\n\nMore complex cache behavior can be achieved by calling `-\u003eclear()` or `-\u003eclearAll()`\nrather than disabling the cache completely. For example, this DataLoader will\nprovide unique keys to a batch function due to the memoization cache being\nenabled, but will immediately clear its cache when the batch function is called\nso later requests will load new values.\n\n```php\n$myLoader = new DataLoader(function($keys) use ($identityLoader) {\n  $identityLoader-\u003eclearAll();\n  return someBatchLoadFn($keys);\n}, $promiseAdapter);\n```\n\n\n## API\n\n#### class DataLoader\n\nDataLoaderPHP creates a public API for loading data from a particular\ndata back-end with unique keys such as the `id` column of a SQL table or\ndocument name in a MongoDB database, given a batch loading function.\n\nEach `DataLoaderPHP` instance contains a unique memoized cache. Use caution when\nused in long-lived applications or those which serve many users with different\naccess permissions and consider creating a new instance per web request.\n\n##### `new DataLoader(callable $batchLoadFn, PromiseAdapterInterface $promiseAdapter [, Option $options])`\n\nCreate a new `DataLoaderPHP` given a batch loading instance and options.\n\n- *$batchLoadFn*: A callable / callback which accepts an Array of keys, and returns a Promise which resolves to an Array of values.\n- *$promiseAdapter*: Any object that implements `Overblog\\PromiseAdapter\\PromiseAdapterInterface`. (see [Overblog/Promise-Adapter](./lib/promise-adapter/docs/usage.md))\n- *$options*: An optional object of options:\n\n  - *batch*: Default `true`. Set to `false` to disable batching, instead\n    immediately invoking `batchLoadFn` with a single load key.\n\n  - *maxBatchSize*: Default `Infinity`. Limits the number of items that get\n    passed in to the `batchLoadFn`.\n\n  - *cache*: Default `true`. Set to `false` to disable caching, instead\n    creating a new Promise and new key in the `batchLoadFn` for every load.\n\n  - *cacheKeyFn*: A function to produce a cache key for a given load key.\n    Defaults to `key`. Useful to provide when an objects are keys\n    and two similarly shaped objects should be considered equivalent.\n\n  - *cacheMap*: An instance of `CacheMap` to be\n    used as the underlying cache for this loader. Default `new CacheMap()`.\n\n##### `load($key)`\n\nLoads a key, returning a `Promise` for the value represented by that key.\n\n- *$key*: An key value to load.\n\n##### `loadMany($keys)`\n\nLoads multiple keys, promising an array of values:\n\n```php\nlist($a, $b) = DataLoader::await($myLoader-\u003eloadMany(['a', 'b']));\n```\n\nThis is equivalent to the more verbose:\n\n```php\nlist($a, $b) = DataLoader::await(\\React\\Promise\\all([\n  $myLoader-\u003eload('a'),\n  $myLoader-\u003eload('b')\n]));\n```\n\n- *$keys*: An array of key values to load.\n\n##### `clear($key)`\n\nClears the value at `$key` from the cache, if it exists. Returns itself for\nmethod chaining.\n\n- *$key*: An key value to clear.\n\n##### `clearAll()`\n\nClears the entire cache. To be used when some event results in unknown\ninvalidations across this particular `DataLoaderPHP`. Returns itself for\nmethod chaining.\n\n##### `prime($key, $value)`\n\nPrimes the cache with the provided key and value. If the key already exists, no\nchange is made. (To forcefully prime the cache, clear the key first with\n`$loader-\u003eclear($key)-\u003eprime($key, $value)`. Returns itself for method chaining.\n\n##### `static await([$promise][, $unwrap])`\n\nYou can synchronously force promises to complete using DataLoaderPHP's await method.\nWhen an await function is invoked it is expected to deliver a value to the promise or reject the promise.\nAwait method process all waiting promise in all dataLoaderPHP instances.\n\n- *$promise*: Optional promise to complete.\n\n- *$unwrap*: controls whether or not the value of the promise is returned for a fulfilled promise\n  or if an exception is thrown if the promise is rejected. Default `true`.\n\n## Using with Webonyx/GraphQL\n\nDataLoader pairs nicely well with [Webonyx/GraphQL](https://github.com/webonyx/graphql-php). GraphQL fields are\ndesigned to be stand-alone functions. Without a caching or batching mechanism,\nit's easy for a naive GraphQL server to issue new database requests each time a\nfield is resolved.\n\nConsider the following GraphQL request:\n\n```graphql\n{\n  me {\n    name\n    bestFriend {\n      name\n    }\n    friends(first: 5) {\n      name\n      bestFriend {\n        name\n      }\n    }\n  }\n}\n```\n\nNaively, if `me`, `bestFriend` and `friends` each need to request the backend,\nthere could be at most 13 database requests!\n\nWhen using DataLoader, we could define the `User` type\nat most 4 database requests,\nand possibly fewer if there are cache hits.\n\n```php\n\u003c?php\nuse GraphQL\\GraphQL;\nuse GraphQL\\Type\\Definition\\ObjectType;\nuse GraphQL\\Type\\Definition\\Type;\nuse Overblog\\DataLoader\\DataLoader;\nuse Overblog\\DataLoader\\Promise\\Adapter\\Webonyx\\GraphQL\\SyncPromiseAdapter;\nuse Overblog\\PromiseAdapter\\Adapter\\WebonyxGraphQLSyncPromiseAdapter;\n\n/**\n* @var \\PDO $dbh\n*/\n// ...\n\n$graphQLPromiseAdapter = new SyncPromiseAdapter();\n$dataLoaderPromiseAdapter = new WebonyxGraphQLSyncPromiseAdapter($graphQLPromiseAdapter);\n$userLoader = new DataLoader(function ($keys) { /*...*/ }, $dataLoaderPromiseAdapter);\n\nGraphQL::setPromiseAdapter($graphQLPromiseAdapter);\n\n$userType = new ObjectType([\n  'name' =\u003e 'User',\n  'fields' =\u003e function () use (\u0026$userType, $userLoader, $dbh) {\n     return [\n            'name' =\u003e ['type' =\u003e Type::string()],\n            'bestFriend' =\u003e [\n                'type' =\u003e $userType,\n                'resolve' =\u003e function ($user) use ($userLoader) {\n                    $userLoader-\u003eload($user['bestFriendID']);\n                }\n            ],\n            'friends' =\u003e [\n                'args' =\u003e [\n                    'first' =\u003e ['type' =\u003e Type::int() ],\n                ],\n                'type' =\u003e Type::listOf($userType),\n                'resolve' =\u003e function ($user, $args) use ($userLoader, $dbh) {\n                    $sth = $dbh-\u003eprepare('SELECT toID FROM friends WHERE fromID=:userID LIMIT :first');\n                    $sth-\u003ebindParam(':userID', $user['id'], PDO::PARAM_INT);\n                    $sth-\u003ebindParam(':first', $args['first'], PDO::PARAM_INT);\n                    $friendIDs = $sth-\u003eexecute();\n\n                    return $userLoader-\u003eloadMany($friendIDs);\n                }\n            ]\n        ];\n    }\n]);\n```\nYou can also see [an example](https://github.com/mcg-web/sandbox-dataloader-graphql-php).\n\n## Using with Symfony\n\nSee the [bundle](https://github.com/overblog/dataloader-bundle).\n\n## Credits\n\nOverblog/DataLoaderPHP is a port of [dataLoader NodeJS version](https://github.com/facebook/dataloader)\nby [Facebook](https://github.com/facebook).\n\nAlso, large parts of the documentation have been ported from the dataLoader NodeJS version\n[Docs](https://github.com/facebook/dataloader/blob/master/README.md).\n\n## License\n\nOverblog/DataLoaderPHP is released under the [MIT](https://github.com/overblog/dataloader-php/blob/master/LICENSE) license.\n\n[Coverage image]: https://codecov.io/gh/overblog/dataloader-php/branch/master/graph/badge.svg\n[CodeCov Master]: https://codecov.io/gh/overblog/dataloader-php/branch/master\n[GA master]: https://github.com/overblog/dataloader-php/actions?query=workflow%3A%22CI%22+branch%3Amaster\n[GA master image]: https://github.com/overblog/dataloader-php/workflows/CI/badge.svg\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foverblog%2Fdataloader-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foverblog%2Fdataloader-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foverblog%2Fdataloader-php/lists"}