PHPackages                             monkeyscloud/monkeyslegion-entity - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. monkeyscloud/monkeyslegion-entity

ActiveLibrary[Database & ORM](/categories/database)

monkeyscloud/monkeyslegion-entity
=================================

Attribute-based data-mapper, entity scanner, and repository layer.

1.1.0(1mo ago)01.2k↑250%15MITPHPPHP ^8.4

Since Jul 23Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/MonkeysCloud/MonkeysLegion-Entity)[ Packagist](https://packagist.org/packages/monkeyscloud/monkeyslegion-entity)[ RSS](/packages/monkeyscloud-monkeyslegion-entity/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (4)Versions (6)Used By (5)

MonkeysLegion Entity
====================

[](#monkeyslegion-entity)

[![Latest Stable Version](https://camo.githubusercontent.com/3bec2abff964fe5b1b8eb4ff346d45818038669c240886297a8c97e093f37071/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d6f6e6b657973636c6f75642f6d6f6e6b6579736c6567696f6e2d656e746974792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/monkeyscloud/monkeyslegion-entity)[![License](https://camo.githubusercontent.com/f8c6d8311a578c002f2c7dd1ecaacae1c44e5e43ad673412726e5057c7863135/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6d6f6e6b657973636c6f75642f6d6f6e6b6579736c6567696f6e2d656e746974792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/monkeyscloud/monkeyslegion-entity)

**MonkeysLegion Entity** is a lightweight, attribute-based data-mapper and entity scanner for PHP 8.4+. It provides a clean way to map database rows to PHP objects using attributes, scan directories for entities, and implement class-specific observers for lifecycle events.

Features
--------

[](#features)

- **Attribute-based Mapping**: Define entities and their fields using PHP 8.4+ attributes.
- **Flexible Hydration**: Map database rows to entities and extract data back for persistence with ease.
- **Entity Scanner**: Automatically discover entity classes in your project.
- **UUID Support**: Integrated UUID v4 generator and attribute for primary keys.
- **Class-Specific Observers**: Hook into entity lifecycle events (creating, updating, saving, deleting, hydrated) with dedicated observer classes.
- **Easy Integration**: Designed to be used with any repository or data-manager implementation.

Installation
------------

[](#installation)

```
composer require monkeyscloud/monkeyslegion-entity
```

Basic Usage
-----------

[](#basic-usage)

### Defining an Entity

[](#defining-an-entity)

Mark your class with the `#[Entity]` attribute and use `#[Column]` or `#[Field]` for its properties.

```
use MonkeysLegion\Entity\Attributes\Entity;
use MonkeysLegion\Entity\Attributes\Column;
use MonkeysLegion\Entity\Attributes\Id;

#[Entity(table: 'users')]
class User
{
    #[Id]
    #[Column]
    private int $id;

    #[Column]
    private string $username;

    #[Column]
    private string $email;

    // Getters and setters...
}
```

### UUID Support

[](#uuid-support)

You can mark properties as UUIDs using the `#[Uuid]` attribute. This is particularly useful for primary keys that should be generated as UUIDs.

```
use MonkeysLegion\Entity\Attributes\Entity;
use MonkeysLegion\Entity\Attributes\Id;
use MonkeysLegion\Entity\Attributes\Uuid;
use MonkeysLegion\Entity\Utils\Uuid as UuidUtil;

#[Entity(table: 'profiles')]
class Profile
{
    #[Id]
    #[Uuid]
    private string $id;

    public function __construct()
    {
        // You can use the built-in utility to generate a UUID v4
        $this->id = UuidUtil::v4();
    }
}
```

### Using Observers

[](#using-observers)

You can attach an observer to an entity class using the `#[ObservedBy]` attribute.

#### 1. Create an Observer

[](#1-create-an-observer)

Extend the `EntityObserver` base class and override the methods you need.

```
use MonkeysLegion\Entity\Observers\EntityObserver;

class UserObserver extends EntityObserver
{
    public function creating(object $entity): void
    {
        // Set default values or hash passwords
        echo "Creating user: " . $entity->getUsername();
    }

    public function hydrated(object $entity): void
    {
        // Perform actions after the entity is loaded from the database
        echo "User hydrated!";
    }
}
```

#### 2. Register the Observer on the Entity

[](#2-register-the-observer-on-the-entity)

You can register a single observer or an array of observers:

```
use MonkeysLegion\Entity\Attributes\Entity;
use MonkeysLegion\Entity\Attributes\ObservedBy;

#[Entity(table: 'users')]
#[ObservedBy(UserObserver::class)] // Single observer
class User
{
    // ...
}

#[Entity(table: 'posts')]
#[ObservedBy([PostObserver::class, ActivityLogObserver::class])] // Multiple observers
class Post
{
    // ...
}
```

#### Supported Lifecycle Events:

[](#supported-lifecycle-events)

- `creating` / `created`: Before and after an insert operation.
- `updating` / `updated`: Before and after an update operation.
- `saving` / `saved`: Before and after both insert and update operations.
- `deleting` / `deleted`: Before and after a delete operation.
- `hydrated`: After an entity is populated from a database row.

### Scanning for Entities

[](#scanning-for-entities)

Use `EntityScanner` to find all classes marked with the `#[Entity]` attribute in a directory.

```
use MonkeysLegion\Entity\Scanner\EntityScanner;

$scanner = new EntityScanner();
$entities = $scanner->scanDir(__DIR__ . '/src/Entities');

foreach ($entities as $reflectionClass) {
    echo "Found entity: " . $reflectionClass->getName() . "\n";
}
```

### Hydrating Entities

[](#hydrating-entities)

The `Hydrator` class handles the conversion between database rows (arrays/objects) and entities.

```
use MonkeysLegion\Entity\Hydrator;

// From DB to Entity
$user = Hydrator::hydrate(User::class, $dbRow);

// From Entity to DB data
$data = Hydrator::extract($user);
```

License
-------

[](#license)

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

###  Health Score

48

—

FairBetter than 95% of packages

Maintenance88

Actively maintained with recent releases

Popularity22

Limited adoption so far

Community18

Small or concentrated contributor base

Maturity57

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 78.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~60 days

Total

5

Last Release

59d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/51e4df19377776baa8eafb605d9e7d2374b855c686f552c20d6856e94e3597c3?d=identicon)[yorchperaza](/maintainers/yorchperaza)

---

Top Contributors

[![yorchperaza](https://avatars.githubusercontent.com/u/2913369?v=4)](https://github.com/yorchperaza "yorchperaza (15 commits)")[![Amanar-Marouane](https://avatars.githubusercontent.com/u/155680356?v=4)](https://github.com/Amanar-Marouane "Amanar-Marouane (4 commits)")

### Embed Badge

![Health badge](/badges/monkeyscloud-monkeyslegion-entity/health.svg)

```
[![Health](https://phpackages.com/badges/monkeyscloud-monkeyslegion-entity/health.svg)](https://phpackages.com/packages/monkeyscloud-monkeyslegion-entity)
```

###  Alternatives

[doctrine/orm

Object-Relational-Mapper for PHP

10.2k285.3M6.2k](/packages/doctrine-orm)[jdorn/sql-formatter

a PHP SQL highlighting library

3.9k115.1M102](/packages/jdorn-sql-formatter)[illuminate/database

The Illuminate Database package.

2.8k52.4M9.4k](/packages/illuminate-database)[ramsey/uuid-doctrine

Use ramsey/uuid as a Doctrine field type.

90440.3M211](/packages/ramsey-uuid-doctrine)[reliese/laravel

Reliese Components for Laravel Framework code generation.

1.7k3.4M16](/packages/reliese-laravel)[wildside/userstamps

Laravel Userstamps provides an Eloquent trait which automatically maintains `created\_by` and `updated\_by` columns on your model, populated by the currently authenticated user in your application.

7511.7M13](/packages/wildside-userstamps)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)