Skip to content

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 ⭐️

16.7 KB
Raw Blame

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)

Related Documentation