---
title: "Introduction"
description: "Entity repositories for PHP with file and enum sources, in-memory queries and custom repository factories"
type: "docs"
category: "doc"
tags: []
authors: [Anonymous]
date: "2026-10-20"
last_update: "2026-10-20"
time_minutes: 3
draft: false
unlisted: false
url: "https://www.derafu.dev/docs/data/repository/introduction"
---

# Lightweight Data Source Management for PHP

[![GitHub](https://img.shields.io/badge/github-derafu%2Frepository-blue?logo=github)](https://github.com/derafu/repository)
![GitHub last commit](https://img.shields.io/github/last-commit/derafu/repository/main)
![CI Workflow](https://github.com/derafu/repository/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/repository)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/repository)
![Total Downloads](https://poser.pugx.org/derafu/repository/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/repository/d/monthly)

Derafu Repository provides an entity query contract, an in-memory repository and a manager that creates repositories through factories. Use the built-in data provider for catalogues and lookup tables, or register factories for repositories with their own infrastructure dependencies.

## Installation

PHP 8.5 or later is required.

```bash
composer require derafu/repository
```

To read YAML files, also install the optional YAML component:

```bash
composer require symfony/yaml
```

## Components

| Component | Responsibility |
|-----------|----------------|
| `RepositoryInterface` | Entity queries, counting and the entity class name |
| `Repository` | In-memory implementation; also exposes container operations |
| `DataSourceInterface` | Read a complete dataset as a PHP array |
| `DataProvider` | Resolve sources, optionally cache raw data, normalize rows and retain loaded data |
| `DataProviderRepositoryFactory` | Construct in-memory repositories using data-provider sources and entity metadata |
| `RepositoryFactoryInterface` | Construct a repository using its own dependencies |
| `RepositoryManager` | Select a factory, create a repository on demand and reuse its instance |

## Choosing a Data Access Path

For a small or medium-sized catalogue, use a PHP, JSON or YAML file, a backed enum, or a custom data source. The provider reads the complete dataset; `Repository` filters and sorts it in memory.

For direct database or remote-service queries, register a repository factory. Its repository can execute each query against the backend and implement `RepositoryInterface` without inheriting the in-memory container. The package supplies the extension point; it does not supply a production SQL repository or an ORM.

Reusing a repository instance does not determine how fresh its results are. The built-in in-memory repository uses loaded data; a custom repository controls its own queries and caching.

## Guides

- [Basic usage](https://www.derafu.dev/docs/data/repository/basic-usage): create a repository or use the manager.
- [Data sources](https://www.derafu.dev/docs/data/repository/data-sources): files, enums, normalization, caching and extension points.
- [Entities and mapping](https://www.derafu.dev/docs/data/repository/entities): entity classes, identifiers and specialized repositories.
- [Querying](https://www.derafu.dev/docs/data/repository/querying): lookup, filtering, ordering and Doctrine Criteria.
- [Repository factories](https://www.derafu.dev/docs/data/repository/factories): repositories with independent dependencies.
- [Symfony integration](https://www.derafu.dev/docs/data/repository/symfony): configure sources, factories and translation resources.



---
Last updated on 20/10/2026