Repository pattern in PHP - Deep Dive

Overview - Repository pattern

What is it?

The Repository pattern is a way to organize code that talks to a database or other storage. It acts like a middleman between your app and the data source. Instead of writing database code everywhere, you put it in one place called a repository. This makes your app easier to understand and change.

Why it matters

Without the Repository pattern, database code spreads all over your app, making it hard to fix bugs or add features. If you want to change how data is stored, you would have to change many parts of your app. The Repository pattern solves this by keeping data access in one place, so changes are simple and safe. This saves time and reduces mistakes.

Where it fits

Before learning the Repository pattern, you should know basic PHP, how to write functions, and how to connect to a database. After this, you can learn about Dependency Injection and Service Layers to build more flexible apps.

Mental Model

Core Idea

A repository is like a store that holds data and gives it to your app, hiding how the data is saved or found.

Think of it like...

Imagine a library where you ask the librarian for a book instead of searching the shelves yourself. The librarian knows where every book is and handles getting it for you. You don’t need to know the library’s layout or system.

┌───────────────┐
│   Application │
└──────┬────────┘
       │ asks for data
       ▼
┌───────────────┐
│ Repository    │
│ (Data Store)  │
└──────┬────────┘
       │ talks to database
       ▼
┌───────────────┐
│ Database      │
└───────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding data access basics

Concept: Learn how apps normally get data from a database using direct queries.

In PHP, you often write SQL queries directly in your code to get or save data. For example, you might use PDO to run a SELECT query and get results. This works but mixes database code with your app logic.

Result

You can fetch data but your code is hard to read and change because database details are everywhere.

Knowing how direct data access works helps you see why separating it into a repository is useful.

2

Foundation

What is a repository class?

Concept: Introduce a class that holds all data access methods for one type of data.

A repository class groups methods like find, save, and delete for one data type. For example, a UserRepository has methods to get users or save user info. This keeps database code in one place.

Result

Your app calls repository methods instead of writing SQL everywhere.

Grouping data access in one class makes your app cleaner and easier to maintain.

3

Intermediate

Separating app logic from data details

🤔Before reading on: do you think the app should know SQL details or just ask the repository? Commit to your answer.

Concept: The app should only ask the repository for data, not know how it is stored or retrieved.

The repository hides SQL queries inside its methods. The app calls methods like getUserById() without knowing SQL. This separation means you can change the database or queries without touching app code.

Result

App code is simpler and less error-prone because it doesn’t handle SQL directly.

Understanding this separation is key to writing flexible and testable code.

4

Intermediate

Using interfaces for repositories

🤔Before reading on: do you think using an interface helps or complicates repository design? Commit to your answer.

Concept: Interfaces define what methods a repository must have, allowing different implementations.

An interface lists methods like findAll() or save(). Different repository classes can implement this interface, for example one for MySQL and another for a file system. The app only knows the interface, so you can swap implementations easily.

Result

Your app becomes more flexible and easier to test with fake repositories.

Using interfaces decouples your app from specific data sources, improving maintainability.

5

Intermediate

Handling complex queries inside repositories

Concept: Repositories can have methods for complex data needs, keeping queries organized.

Instead of writing complex SQL in the app, you add methods like findUsersByRole() inside the repository. This keeps all data logic in one place and makes the app code simpler.

Result

Complex data retrieval is easier to manage and reuse.

Centralizing complex queries prevents duplication and bugs.

6

Advanced

Testing with repository pattern

🤔Before reading on: do you think repositories make testing easier or harder? Commit to your answer.

Concept: Repositories allow replacing real data access with fake data for testing.

By coding against repository interfaces, you can create fake repositories that return test data. This lets you test app logic without needing a real database, making tests faster and more reliable.

Result

You can write automated tests that run anywhere without database setup.

Knowing how repositories enable testing improves code quality and confidence.

7

Expert

Repository pattern tradeoffs and pitfalls

🤔Before reading on: do you think the repository pattern always improves code? Commit to your answer.

Concept: Understand when the pattern adds value and when it adds unnecessary complexity.

For very simple apps, repositories can add extra layers that make code harder to follow. Also, if repositories become too large or do too much, they lose clarity. Experts balance abstraction with simplicity and avoid over-engineering.

Result

You learn to apply the pattern wisely, improving maintainability without extra complexity.

Knowing the limits of the repository pattern helps you write clean, practical code.

Under the Hood

The repository pattern works by defining a class that contains all methods to access and manipulate data. This class uses database connections internally but exposes simple methods to the app. When the app calls a repository method, it triggers SQL queries or other data operations hidden inside. This hides database details and allows changing the data source without changing app code.

Why designed this way?

It was designed to solve the problem of scattered database code that is hard to maintain. By centralizing data access, developers can change storage methods or optimize queries without touching business logic. This separation also supports testing and cleaner code organization. Alternatives like direct SQL in app code were simpler but less maintainable.

┌───────────────┐
│ Application   │
│ (Business     │
│ Logic)        │
└──────┬────────┘
       │ calls methods
       ▼
┌───────────────┐
│ Repository    │
│ (Data Access) │
└──────┬────────┘
       │ runs SQL or
       │ other data
       ▼
┌───────────────┐
│ Database or   │
│ Data Source   │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does the repository pattern mean you never write SQL again? Commit yes or no.

Common Belief: Using the repository pattern means you never write SQL queries directly.

Reality: Repositories still use SQL or other data commands internally; they just hide them from the app code.

Why it matters: Thinking you never write SQL can lead to poorly designed repositories that duplicate logic or hide inefficient queries.

Quick: Is the repository pattern only useful for big projects? Commit yes or no.

Common Belief: The repository pattern is only needed in large, complex applications.

Reality: Even small projects benefit from repositories by keeping code organized and easier to change.

Why it matters: Ignoring repositories in small projects can cause messy code that grows harder to maintain as the project grows.

Quick: Does using repositories guarantee your app is well tested? Commit yes or no.

Common Belief: If you use repositories, your app is automatically easy to test.

Reality: Repositories help testing but you still need to write tests and design interfaces properly.

Why it matters: Assuming repositories alone ensure good tests can lead to poor test coverage and hidden bugs.

Quick: Can a repository handle business logic? Commit yes or no.

Common Belief: Repositories should contain business rules and logic.

Reality: Repositories should only handle data access; business logic belongs elsewhere.

Why it matters: Mixing business logic into repositories makes code harder to maintain and test.

Expert Zone

1

Repositories often implement caching internally to improve performance without changing app code.

2

Using repositories with Dependency Injection frameworks allows swapping implementations at runtime for different environments.

3

Repositories can be combined with Specification patterns to build flexible, reusable query criteria.

When NOT to use

Avoid the repository pattern in very simple scripts or prototypes where adding layers slows development. Instead, use direct data access. Also, if your app uses complex ORM features tightly coupled to your domain, repositories may add unnecessary abstraction.

Production Patterns

In real apps, repositories are used with service layers that handle business logic. They often implement pagination, filtering, and sorting inside repository methods. Developers write unit tests with fake repositories and integration tests with real databases to ensure correctness.

Connections

Dependency Injection

Builds-on

Knowing Dependency Injection helps you provide different repository implementations without changing app code, increasing flexibility.

Single Responsibility Principle

Same pattern

The repository pattern follows this principle by separating data access from business logic, making code easier to maintain.

Supply Chain Management

Analogy in logistics

Just like a warehouse manages goods and supplies them to stores without the stores knowing the warehouse details, repositories manage data and supply it to the app without exposing storage details.

Common Pitfalls

#1 Putting business logic inside the repository.

Wrong approach:

class UserRepository {
public function isUserAdult($userId) {
$user = $this->findById($userId);
return $user->age >= 18;
}
}

Correct approach:

class UserRepository {
public function findById($userId) {
// data access only
}
}

class UserService {
public function isUserAdult($user) {
return $user->age >= 18;
}
}

Root cause:

Confusing data access responsibilities with business rules leads to mixed concerns and harder maintenance.

#2 Writing SQL queries directly in the app code instead of repositories.

Wrong approach:

$stmt = $pdo->prepare('SELECT * FROM users WHERE id = ?');
$stmt->execute([$id]);
$user = $stmt->fetch();

Correct approach:

class UserRepository {
private $pdo;

public function __construct($pdo) {
$this->pdo = $pdo;
}

public function findById($id) {
$stmt = $this->pdo->prepare('SELECT * FROM users WHERE id = ?');
$stmt->execute([$id]);
return $stmt->fetch();
}
}

$user = $userRepository->findById($id);

Root cause:

Not centralizing data access causes duplicated SQL and scattered database logic.

#3 Making repository classes too large and doing too many things.

Wrong approach:

class UserRepository {
public function findById($id) {}
public function save($user) {}
public function sendWelcomeEmail($user) {}
public function calculateUserScore($user) {}
}

Correct approach:

class UserRepository {
public function findById($id) {}
public function save($user) {}
}

class UserService {
public function sendWelcomeEmail($user) {}
public function calculateUserScore($user) {}
}

Root cause:

Mixing unrelated responsibilities in one class reduces clarity and testability.

Key Takeaways

The Repository pattern centralizes data access, making your app easier to maintain and change.

It hides database details from your app, so you can change storage without breaking code.

Using interfaces with repositories improves flexibility and testing.

Repositories should only handle data access, not business logic.

Applying the pattern wisely avoids unnecessary complexity and keeps code clean.