Legal Entity Laravel Package

Getting Started

amethyst/legal-entity is a small domain-model package from the Amethyst PHP family. It ships a set of legal-entity primitives — persons, organisations, addresses, identifiers and similar building blocks — expressed as Amethyst entities/value objects rather than as a framework integration. There is no service provider, no HTTP layer, no migration generator: it is a vocabulary you compose into your own application.

Install it alongside the core it depends on:

composer require amethyst/legal-entity
# almost certainly also needed for the annotation/metadata layer:
composer require amethyst/core amethyst/annotations

Look here first, in this order:

1. vendor/amethyst/legal-entity/src/ — the whole package is small; read every class once, top to bottom. The class list is the documentation.
2. vendor/amethyst/legal-entity/composer.json — the real require block and PHP constraint tell you which Amethyst/Doctrine versions you must align with.
3. vendor/amethyst/legal-entity/tests/ (if shipped) — with zero stars and zero dependents, the tests are the only executable specification you will get.
4. vendor/amethyst/core/src/ — the Entity, DataTrait/DataCollection and manager plumbing that gives these classes their behaviour.

First use case: representing a counterparty in an invoicing or onboarding flow. Sketch (adjust class names to what you actually find in src/):

use Amethyst\LegalEntity\...; // read src/ to confirm FQCNs

$company = new LegalEntity();
$company->setName('Acme Srl');
$company->setTaxId('IT01234567890');

$payload = $company->toArray();   // feed straight into a JSON response or DBAL mapper

If the classes expose a manager-based factory (ManagerFactory / Manager in amethyst/core), prefer that over new so annotation metadata and relations are initialised consistently.

Implementation Patterns

Use it as an anti-corruption layer, not as your persistence model. The most robust pattern is to keep the package's classes at the edge: hydrate them from your API payload, then copy into your own Eloquent/Doctrine models. That way a breaking change in an unmaintained package never reaches your schema.

final class CounterpartyMapper
{
    public function fromPayload(array $data): LegalEntity
    {
        $entity = new LegalEntity();
        $entity->setName($data['name']);
        // ... explicit field-by-field mapping, no magic hydration
        return $entity;
    }
}

Composition over inheritance. If you need an Invoice that has a customer, hold a LegalEntity property rather than extending the package class. Extending couples you to protected-property names and to Amethyst's metadata contract.

Annotation-driven metadata. Following Amethyst house style, these entities declare their shape with docblock annotations (@Column, @Entity, @OneToMany, …). That means:

• You can point amethyst/dbal or the relevant driver at them and get a mapper for free.
• You can also parse them yourself with amethyst/annotations to generate forms, JSON Schema, or validation rules — one source of truth for "what makes a valid legal entity".

Value-object discipline. Addresses, tax identifiers and similar leaf classes are usually effectively immutable. Treat them that way in your own code: build a new one rather than mutating, and clone when you need a variant. If the package exposes setters, wrap them behind your own factory so you can enforce validation once.

Serialisation boundary. Always serialise through your own transformer, not var_export/json_encode on the object directly. Package internals (metadata caches, back-references to managers) leak into json_encode output and will surprise you in an API response.

final class LegalEntityTransformer
{
    public function transform(LegalEntity $e): array
    {
        return array_filter([
            'name'   => $e->getName(),
            'tax_id' => $e->getTaxId(),
            'address'=> $e->getAddress()?->toArray(),
        ], fn ($v) => $v !== null);
    }
}

Test fixtures. Because you cannot rely on upstream tests, build a tiny fixture factory in your own test suite that produces valid entities. This doubles as living documentation of which fields your application actually depends on.

Gotchas and Tips

Zero stars, zero dependents is the headline risk. There is no community, no issue history to mine, and no guarantee of a security patch. Consequences:

• Pin an exact version ("amethyst/legal-entity": "1.0.3"), never a range.
• Consider vendoring or forking into your own namespace if this becomes load-bearing.
• Budget for reading the source rather than searching for docs; there are none.

Annotation compatibility is the most likely install-time failure. Amethyst's annotation stack was built around doctrine/annotations docblock parsing. On PHP 8.1+ with modern Doctrine releases the reader was deprecated and eventually removed. Expect to either pin an older doctrine/annotations or convert docblock annotations to native attributes. Check composer why-not first when resolution fails.

Class names are guesses until you look. Names like Person, LegalEntity, Organization, Address, TaxId are conventional but not contractual in a package this obscure. Do find vendor/amethyst/legal-entity/src -name '*.php' and treat that listing as the API surface. Never code against a guessed FQCN.

Config caching during development. Amethyst's metadata/managers are frequently cached in memory per process. If you change annotations and see stale behaviour, clear the manager cache (or simply restart the worker). Long-running queue workers will hold stale metadata indefinitely.

Mutability and shared state. Manager-created entities can carry a reference back to the manager and to relation collections. Two calls returning "the same" entity may or may not be the same instance. Compare by identifier, not ===.

Locale assumptions on tax identifiers. Any checksum or format logic inside the package for tax IDs is almost certainly single-jurisdiction (likely Italian/EU-style IT01234567890). Do not assume it validates your country's format — validate in your own layer and use the package only as a carrier.

Extension points, in order of preference:

1. Composition: wrap the entity in your own class.
2. Subclass and override the getters you disagree with, keeping the annotation metadata intact.
3. Fork the package when you need to change the annotations themselves — with zero upstream activity, a fork is a legitimate, low-drama option.

Debugging checklist when something is silently wrong: dump the parsed metadata (var_dump the class's metadata/mapping) before blaming your hydration code; confirm the autoloader actually resolves the class with class_exists(); verify the PHP version matches the package's constraint; and check whether your app's own entity base class shadows the Amethyst one.