README

EntityRepository - A modern, type-safe implementation of the Repository pattern for PHP domain entities. Provides a robust data access layer with automatic entity mapping and collection support.

✨ Features

Entity-centric design - Work with domain objects instead of raw arrays
Automatic mapping - Convert database results to entity objects via toEntity()
Typed collections - Customizable collection classes via constructor
Transaction management - Atomic operations with beginTransaction(), commit(), and rollback()
Query Builder - Flexible SQL construction with type safety
Generics support - PHPDoc template types for IDE autocompletion
Strict type validation - Ensures data integrity and type safety

📥 Installation

composer require solophp/entity-repository

🔗 Dependencies

solophp/database: Database abstraction layer
solophp/query-builder: SQL query construction

🚀 Quick Start

1. Define Your Entity

class User implements EntityInterface {
    public function __construct(
        public readonly int $id,
        public string $name,
        public string $email,
        public DateTimeImmutable $createdAt
    ) {}
}

2. Create Repository

/**
 * @extends EntityRepository<User>
 */
class UserRepository extends EntityRepository {
    public function __construct(Database $db) {
        parent::__construct(
            db: $db,
            table: 'users',
            collectionClass: UserCollection::class
        );
    }

    protected function toEntity(array $data): User {
        return new User(
            (int)$data['id'],
            $data['name'],
            $data['email'],
            new DateTimeImmutable($data['created_at'])
        );
    }
}

📚 Core Features

Repository Methods

Entity Operations

Persistence

Utilities

🧩 GenericCollection Methods

Core Functionality

Item Manipulation

Data Processing

Sorting

Utility Methods

💡 Usage Examples

Collection Operations

$users = $userRepo->findAll();

// Filtering and sorting
$activeUsers = $users
    ->filter(fn(User $u) => $u->isActive())
    ->sortByProperty('name');

// Data extraction
$userEmails = $users->pluck('email');
$groupedByRole = $users->groupBy(fn(User $u) => $u->role);

Custom Collections

// Instantiate with custom collection
$repo = new UserRepository(
    db: $database,
    table: 'users',
    collectionClass: UserCollection::class
);

// Direct collection manipulation
$collection = new GenericCollection();
$collection->add($user1);
$collection->remove($user2);

⚙️ Advanced Configuration

Custom Repository Setup

Configure repositories with granular control using constructor parameters:

/**
 * @extends EntityRepository<Product>
 */
class ProductRepository extends EntityRepository {
    public function __construct(
        Database $db,
        string $collectionClass = ProductCollection::class
    ) {
        parent::__construct(
            db: $db,
            table: 'products',
            alias: 'p',
            primaryKey: 'prod_id',
            collectionClass: $collectionClass
        );
    }
}

Key Parameters:

table (Required): Database table name
alias: Table alias for complex queries
primaryKey: Custom ID field for entity lookups
collectionClass: Custom collection implementation

Transaction Management Patterns

Implement robust data operations with ACID compliance:

Basic Transaction

$repo->beginTransaction();

try {
    // Atomic operations
    $repo->update(1, ['stock' => $newStock]);
    $repo->create($orderData);
    $repo->commit();
} catch (DatabaseException $e) {
    $repo->rollback();
    throw new OperationFailedException("Transaction aborted", 0, $e);
}

⚙️ Requirements

PHP 8.2+

🤝 Contributions

Feel free to open an issue or submit a pull request!

📝 License

This project is licensed under the MIT License.

solophp / entity-repository

Maintainers

Details