Open-source event management and ticket selling platform β perfect for concerts, conferences, and everything in between ποΈ If you find this project helpful, please consider giving us a star βοΈ
Repository Pattern in Hi.Events
Overview
Hi.Events uses a clean implementation of the Repository Pattern that provides abstraction between the domain layer and data persistence. All repositories follow interface-based design and return domain objects instead of Eloquent models.
Architecture
graph TB
A[Handler] --> B[Repository Interface]
B --> C[Eloquent Repository Implementation]
C --> D[Eloquent Model]
D --> E[Database]
C --> F[Domain Object]
F --> A
Core Components
1. Base Repository Interface
Location: backend/app/Repository/Interfaces/RepositoryInterface.php
Provides 40+ methods for common CRUD operations:
Core CRUD Methods
// Create
public function create(array $attributes): DomainObjectInterface;
public function insert(array $inserts): bool; // Bulk insert
// Read
public function all(array $columns = ['*']): Collection;
public function findById(int $id, array $columns = ['*']): DomainObjectInterface;
public function findFirst(int $id, array $columns = ['*']): ?DomainObjectInterface;
public function findWhere(array $where, array $columns = ['*']): Collection;
public function findFirstWhere(array $where, array $columns = ['*']): ?DomainObjectInterface;
public function findWhereIn(string $field, array $values): Collection;
// Update
public function updateFromDomainObject(int $id, DomainObjectInterface $do): DomainObjectInterface;
public function updateFromArray(int $id, array $attributes): DomainObjectInterface;
public function updateWhere(array $attributes, array $where): int;
// Delete
public function deleteById(int $id): bool;
public function deleteWhere(array $conditions): int;
Pagination & Counting
public function paginate(int $limit = 20, array $columns = ['*']): LengthAwarePaginator;
public function paginateWhere(array $where, int $limit = 20): LengthAwarePaginator;
public function countWhere(array $conditions): int;
Increment/Decrement
public function increment(int $id, string $column, int|float $amount = 1): int;
public function decrement(int $id, string $column, int|float $amount = 1): int;
public function incrementWhere(array $where, string $column, int|float $amount = 1): int;
Special Operations
// Eager loading
public function loadRelation(string|Relationship $relationship): static;
// Include soft deleted
public function includeDeleted(): static;
// Required domain object mapping
public function getDomainObject(): string; // Returns FQCN of domain object
2. Base Repository Implementation
Location: backend/app/Repository/Eloquent/BaseRepository.php
Abstract class that implements all interface methods with:
- Automatic model hydration to domain objects
- Flexible where conditions
- Model reset pattern
- Eager loading support
Key Implementation Features
Flexible Where Conditions:
// Simple key-value
$where = ['event_id' => 1];
// Array with operator
$where = [['status', '!=', 'RESERVED']];
// Callable for complex queries
$where[] = static function (Builder $builder) {
$builder->where('name', 'like', '%search%')
->orWhere('email', 'like', '%search%');
};
Automatic Hydration:
private function hydrateDomainObjectFromModel(Model $model): DomainObjectInterface
{
$domainObject = new ($this->getDomainObject())();
foreach ($model->attributesToArray() as $attribute => $value) {
$method = 'set' . ucfirst(Str::camel($attribute));
if (is_callable([$domainObject, $method])) {
$domainObject->$method($value);
}
}
// Handle eager-loaded relationships
$this->handleEagerLoads($model, $domainObject);
return $domainObject;
}
Creating a Repository
Step 1: Define Interface
File: backend/app/Repository/Interfaces/AffiliateRepositoryInterface.php
<?php
namespace HiEvents\Repository\Interfaces;
use HiEvents\DomainObjects\AffiliateDomainObject;
use HiEvents\DataTransferObjects\QueryParamsDTO;
use Illuminate\Pagination\LengthAwarePaginator;
interface AffiliateRepositoryInterface extends RepositoryInterface
{
public function findByEventId(int $eventId, QueryParamsDTO $params): LengthAwarePaginator;
public function incrementSales(int $affiliateId, float $amount): void;
}
Step 2: Create Implementation
File: backend/app/Repository/Eloquent/AffiliateRepository.php
<?php
namespace HiEvents\Repository\Eloquent;
use HiEvents\DomainObjects\AffiliateDomainObject;
use HiEvents\DomainObjects\Generated\AffiliateDomainObjectAbstract;
use HiEvents\Models\Affiliate;
use HiEvents\Repository\Interfaces\AffiliateRepositoryInterface;
use Illuminate\Database\Query\Builder;
class AffiliateRepository extends BaseRepository implements AffiliateRepositoryInterface
{
protected function getModel(): string
{
return Affiliate::class; // Eloquent model
}
public function getDomainObject(): string
{
return AffiliateDomainObject::class; // Domain object returned
}
public function findByEventId(int $eventId, QueryParamsDTO $params): LengthAwarePaginator
{
$where = [
[AffiliateDomainObjectAbstract::EVENT_ID, '=', $eventId]
];
// Add search if query provided
if ($params->query) {
$where[] = static function (Builder $builder) use ($params) {
$builder
->orWhere(AffiliateDomainObjectAbstract::NAME, 'ilike', '%' . $params->query . '%')
->orWhere(AffiliateDomainObjectAbstract::CODE, 'ilike', '%' . $params->query . '%')
->orWhere(AffiliateDomainObjectAbstract::EMAIL, 'ilike', '%' . $params->query . '%');
};
}
$this->model = $this->model->orderBy(
column: $params->sort_by ?? AffiliateDomainObject::getDefaultSort(),
direction: $params->sort_direction ?? 'desc',
);
return $this->paginateWhere(
where: $where,
limit: $params->per_page,
page: $params->page,
);
}
public function incrementSales(int $affiliateId, float $amount): void
{
$this->model->where('id', $affiliateId)
->increment('total_sales', 1, [
'total_sales_gross' => $this->db->raw('total_sales_gross + ' . $amount)
]);
}
}
Step 3: Register in Service Provider
File: backend/app/Providers/RepositoryServiceProvider.php
class RepositoryServiceProvider extends ServiceProvider
{
private static array $interfaceToConcreteMap = [
AffiliateRepositoryInterface::class => AffiliateRepository::class,
OrderRepositoryInterface::class => OrderRepository::class,
EventRepositoryInterface::class => EventRepository::class,
// ... more mappings
];
public function register(): void
{
foreach (self::$interfaceToConcreteMap as $interface => $concrete) {
$this->app->bind($interface, $concrete);
}
}
}
Usage in Handlers
Basic Usage
class CreateAffiliateHandler
{
public function __construct(
private readonly AffiliateRepositoryInterface $affiliateRepository,
) {}
public function handle(int $eventId, int $accountId, UpsertAffiliateDTO $dto): AffiliateDomainObject
{
// Check for existing
$existing = $this->affiliateRepository->findFirstWhere([
'event_id' => $eventId,
'code' => $code,
]);
if ($existing) {
throw new ResourceConflictException('Affiliate with this code already exists');
}
// Create new affiliate
return $this->affiliateRepository->create([
'event_id' => $eventId,
'account_id' => $accountId,
'name' => $dto->name,
'code' => $code,
'email' => $dto->email,
'status' => $dto->status->value,
]);
}
}
Using Domain Object Constants
Always use constants for field names:
// β
GOOD - Using constants
$affiliate = $this->affiliateRepository->findFirstWhere([
AffiliateDomainObjectAbstract::EVENT_ID => $eventId,
AffiliateDomainObjectAbstract::CODE => $code,
AffiliateDomainObjectAbstract::STATUS => AffiliateStatus::ACTIVE->value,
]);
// β BAD - Using strings
$affiliate = $this->affiliateRepository->findFirstWhere([
'event_id' => $eventId,
'code' => $code,
]);
Eager Loading
$event = $this->eventRepository
->loadRelation(EventSettingDomainObject::class)
->loadRelation(EventStatisticDomainObject::class)
->findById($eventId);
// Event now has eager-loaded settings and statistics
$settings = $event->getEventSettings();
$statistics = $event->getEventStatistics();
Complex Queries
public function findByEventId(int $eventId, QueryParamsDTO $params): LengthAwarePaginator
{
$where = [
[OrderDomainObjectAbstract::EVENT_ID, '=', $eventId],
[OrderDomainObjectAbstract::STATUS, '!=', OrderStatus::RESERVED->name],
];
// Complex search with OR conditions
if ($params->query) {
$where[] = static function (Builder $builder) use ($params) {
$builder
->where(
DB::raw("(first_name||' '||last_name)"),
'ilike',
'%' . $params->query . '%'
)
->orWhere(OrderDomainObjectAbstract::EMAIL, 'ilike', '%' . $params->query . '%')
->orWhere(OrderDomainObjectAbstract::PUBLIC_ID, 'ilike', '%' . $params->query . '%');
};
}
// Dynamic filters
if (!empty($params->filter_fields)) {
$this->applyFilterFields($params, OrderDomainObject::getAllowedFilterFields());
}
// Sorting
$this->model = $this->model->orderBy(
column: $params->sort_by ?? OrderDomainObject::getDefaultSort(),
direction: $params->sort_direction ?? 'desc',
);
return $this->paginateWhere($where, $params->per_page, page: $params->page);
}
Relationship Constraints
public function findOrdersAssociatedWithProducts(
int $eventId,
array $productIds,
array $orderStatuses
): Collection {
return $this->handleResults(
$this->model
->whereHas('order_items', static function (Builder $query) use ($productIds) {
$query->whereIn('product_id', $productIds);
})
->whereIn('status', $orderStatuses)
->where('event_id', $eventId)
->get()
);
}
Best Practices
1. Favor Base Methods Over Custom Methods
Prefer existing base methods:
// β
GOOD - Use base method
$affiliate = $repository->findFirstWhere(['event_id' => $eventId]);
// β BAD - Custom method for common pattern
$affiliate = $repository->findByEventId($eventId);
Only create custom methods for complex, reusable queries:
// β
GOOD - Complex query worth a custom method
public function findOrdersAssociatedWithProducts(
int $eventId,
array $productIds,
array $orderStatuses
): Collection;
// β
GOOD - Domain-specific business logic
public function incrementSales(int $affiliateId, float $amount): void;
2. Use Type Hints
public function handle(int $eventId, UpsertDTO $dto): AffiliateDomainObject
{
// Handler knows it receives a domain object
$affiliate = $this->repository->create([...]);
// Type-safe method calls
$affiliateId = $affiliate->getId();
$status = $affiliate->getStatus();
return $affiliate;
}
3. Handle Null Safely
// findById throws if not found
$affiliate = $this->repository->findById($id);
// findFirstWhere returns null if not found
$affiliate = $this->repository->findFirstWhere(['code' => $code]);
if (!$affiliate) {
throw new NotFoundHttpException('Affiliate not found');
}
4. Use Transactions at Handler Level
public function handle(CreateOrderDTO $dto): OrderDomainObject
{
return $this->databaseManager->transaction(function () use ($dto) {
// Multiple repository calls in transaction
$event = $this->eventRepository->findById($dto->eventId);
$order = $this->orderRepository->create([...]);
$items = $this->orderItemRepository->insert([...]);
return $order;
});
}
5. Avoid N+1 Queries
// β
GOOD - Eager load relationships
$orders = $this->orderRepository
->loadRelation(OrderItemDomainObject::class)
->loadRelation(AttendeeDomainObject::class)
->findWhere(['event_id' => $eventId]);
// β BAD - N+1 query
$orders = $this->orderRepository->findWhere(['event_id' => $eventId]);
foreach ($orders as $order) {
$items = $order->getOrderItems(); // Lazy load for each order
}
Common Repository Patterns
Pagination with Filters
public function findByEventId(int $eventId, QueryParamsDTO $params): LengthAwarePaginator
{
$where = [['event_id', '=', $eventId]];
if ($params->query) {
$where[] = static fn($builder) => $builder->where('name', 'ilike', '%' . $params->query . '%');
}
if ($params->filter_fields) {
$this->applyFilterFields($params, DomainObject::getAllowedFilterFields());
}
$this->model = $this->model->orderBy(
$params->sort_by ?? 'created_at',
$params->sort_direction ?? 'desc'
);
return $this->paginateWhere($where, $params->per_page, page: $params->page);
}
Bulk Operations
// Bulk insert
$this->repository->insert([
['name' => 'Item 1', 'event_id' => 1],
['name' => 'Item 2', 'event_id' => 1],
]);
// Bulk update
$this->repository->updateWhere(
['status' => 'CANCELLED'],
['event_id' => 1, 'payment_status' => 'PENDING']
);
// Bulk delete
$this->repository->deleteWhere(['status' => 'EXPIRED']);
Increment/Decrement
// Increment single field
$this->repository->increment($id, 'view_count', 1);
// Increment with additional updates
$this->model->where('id', $affiliateId)
->increment('total_sales', 1, [
'total_sales_gross' => DB::raw('total_sales_gross + ' . $amount)
]);
Finding by Short ID
public function findByShortId(string $orderShortId): ?OrderDomainObject
{
return $this->findFirstByField('short_id', $orderShortId);
}
Testing Repositories
Unit Testing with Mocks
use Mockery;
use Tests\TestCase;
class CreateAffiliateHandlerTest extends TestCase
{
use DatabaseTransactions;
public function test_creates_affiliate_successfully(): void
{
$repository = Mockery::mock(AffiliateRepositoryInterface::class);
$repository->shouldReceive('findFirstWhere')
->once()
->with(['event_id' => 1, 'code' => 'TEST'])
->andReturn(null);
$repository->shouldReceive('create')
->once()
->with([
'event_id' => 1,
'name' => 'Test Affiliate',
'code' => 'TEST',
])
->andReturn(new AffiliateDomainObject());
$handler = new CreateAffiliateHandler($repository);
$result = $handler->handle(1, 1, new UpsertAffiliateDTO(...));
$this->assertInstanceOf(AffiliateDomainObject::class, $result);
}
}
Repository Method Reference
Query Methods
| Method | Returns | Description |
|---|---|---|
all() |
Collection | Get all records |
findById() |
DomainObject | Find by ID (throws if not found) |
findFirst() |
?DomainObject | Find by ID (returns null if not found) |
findWhere() |
Collection | Find multiple by conditions |
findFirstWhere() |
?DomainObject | Find first by conditions |
findWhereIn() |
Collection | Find where column in array |
paginate() |
LengthAwarePaginator | Paginate all |
paginateWhere() |
LengthAwarePaginator | Paginate with conditions |
countWhere() |
int | Count matching records |
Mutation Methods
| Method | Returns | Description |
|---|---|---|
create() |
DomainObject | Create single record |
insert() |
bool | Bulk insert (no domain objects returned) |
updateFromArray() |
DomainObject | Update by ID with array |
updateFromDomainObject() |
DomainObject | Update by ID with domain object |
updateWhere() |
int | Bulk update matching records |
deleteById() |
bool | Delete by ID |
deleteWhere() |
int | Bulk delete matching records |
Utility Methods
| Method | Returns | Description |
|---|---|---|
increment() |
int | Increment column |
decrement() |
int | Decrement column |
loadRelation() |
self | Add eager load (chainable) |
includeDeleted() |
self | Include soft deleted (chainable) |