https://github.com/phpnomad/datastore
Storage-agnostic data access pattern — separate business interfaces from concrete storage implementations
https://github.com/phpnomad/datastore
data-access datastore framework php phpnomad platform-agnostic repository-pattern
Last synced: 16 days ago
JSON representation
Storage-agnostic data access pattern — separate business interfaces from concrete storage implementations
- Host: GitHub
- URL: https://github.com/phpnomad/datastore
- Owner: phpnomad
- License: mit
- Created: 2023-10-23T10:48:22.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2026-04-10T02:10:03.000Z (about 2 months ago)
- Last Synced: 2026-04-10T02:36:01.663Z (about 2 months ago)
- Topics: data-access, datastore, framework, php, phpnomad, platform-agnostic, repository-pattern
- Language: PHP
- Homepage: https://phpnomad.com
- Size: 80.1 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# phpnomad/datastore
[](https://packagist.org/packages/phpnomad/datastore) [](https://packagist.org/packages/phpnomad/datastore) [](https://packagist.org/packages/phpnomad/datastore) [](https://packagist.org/packages/phpnomad/datastore)
`phpnomad/datastore` is the storage-agnostic data access pattern at the heart of [PHPNomad](https://phpnomad.com). It ships a small set of interfaces, traits, models, and events that let your business logic describe what data operations it needs without committing to where the data lives. It contains no concrete storage code of its own.
The pattern splits into two layers. Your Core layer holds the `Datastore` interface your application code depends on, the `DatastoreHandler` interface that storage implementations fulfill, and the domain models that flow between them. Your Service layer holds concrete handlers that talk to real storage, whether that's a SQL database, a REST API, a GraphQL endpoint, or an in-memory array for tests. `phpnomad/db` is one Service-layer implementation against SQL, and PHPNomad has been running this pattern in production for years, powering [Siren](https://sirenaffiliates.com), several MCP servers, and other client systems.
## Installation
```bash
composer require phpnomad/datastore
```
## Quick Start
The pattern centers on three files: a `Datastore` interface (your public API), a `DatastoreHandler` interface (the storage contract), and a Core implementation that wires them together with decorator traits.
Declare your public API by extending the base interfaces you need and adding any custom business methods:
```php
datastoreHandler = $datastoreHandler;
}
public function getPublishedPosts(): array
{
return $this->datastoreHandler->where([
[
'type' => 'AND',
'clauses' => [
['column' => 'status', 'operator' => '=', 'value' => 'published'],
],
],
]);
}
}
```
A Service-layer class like `PostDatabaseDatastoreHandler` implements `PostDatastoreHandler` against an actual backend. You bind the handler interface to that concrete class in your DI container at bootstrap time. Swapping storage later is a one-line change to the binding. Nothing in `PostDatastore` or its callers has to move.
## Key Concepts
- `Datastore` is your public API. `DatastoreHandler` is the storage contract. Both extend the same base interfaces, but only the `Datastore` adds custom business methods.
- Base interfaces are composable. Mix `Datastore`, `DatastoreHasPrimaryKey`, `DatastoreHasWhere`, and `DatastoreHasCounts` to describe exactly the operations your entity supports, no more.
- Decorator traits (`WithDatastoreDecorator`, `WithDatastorePrimaryKeyDecorator`, `WithDatastoreWhereDecorator`, `WithDatastoreCountDecorator`) delegate the standard methods to your handler so implementations stay lean.
- `DataModel` and `ModelAdapter` keep domain entities independent of storage format. Adapters translate between raw arrays and model objects on read and write.
- `RecordCreated`, `RecordUpdated`, and `RecordDeleted` events let handler implementations broadcast state changes through `phpnomad/event` without coupling consumers to any specific storage backend.
## Documentation
Full documentation lives at [phpnomad.com](https://phpnomad.com), including the datastore conceptual overview, the Core datastore layer reference, model and adapter guidance, and the `phpnomad/db` Service-layer implementation for SQL-backed storage.
## License
MIT, see [LICENSE.txt](LICENSE.txt) for the full text.