User Laravel Package

Getting Started

amethyst/user is a small, framework-agnostic user entity package from the Amethyst PHP ecosystem — not a Laravel package. Treat it as a domain model you wire in yourself rather than something that drops into config/auth.php.

1. Install and inspect:

   composer require amethyst/user
   ls vendor/amethyst/user/src
   cat vendor/amethyst/user/composer.json
   

2. Read in this order: composer.json (to see what it expects — Doctrine, PSR interfaces, Amethyst core), then src/ for the User class and any interfaces (UserInterface, repository/manager classes), then the tests/ directory. With 0 stars and no dependents, the tests are your real documentation.
3. First use case: construct a user, set credentials, and persist it through whatever repository abstraction the package exposes:

   $user = new \Amethyst\User\User();
   $user->setUsername('alice');
   $user->setPassword(password_hash('secret', PASSWORD_DEFAULT));
   $yourRepository->save($user);
   

The immediate goal is to confirm how the entity is meant to be persisted before you build anything on top of it — that is the hinge point for everything else.

Implementation Patterns

Wrap it, don't spread it. Because this is an entity package without Laravel opinions, put it behind a small adapter (an AuthUserRepository or a UserManager service) so the rest of your app talks to your interface, not Amethyst's. This keeps the blast radius small if you later swap it out or the package goes unmaintained.

Laravel integration pattern. Bind a service provider to register the repository/manager, and if you want to use it with Laravel's auth, implement Illuminate\Contracts\Auth\Authenticatable on a thin subclass/subclass-wrapper around the Amethyst entity. You will need to map its accessors (getUsername, getPassword, etc.) to Laravel's getAuthIdentifier, getAuthPassword, getRememberToken, and friends. Do this once, in one class.

Persistence. If the package ships Doctrine metadata or a repository interface, follow that shape and let Eloquent/Doctrine stay on the boundary. If you're using Eloquent, create a separate App\Models\User and hydrate from the Amethyst object rather than trying to make the package's entity an Eloquent model — mixing the two tends to create mapping headaches with password fields and timestamps.

Password lifecycle. Do hashing and verification yourself with password_hash/password_verify (or Laravel's Hash facade). If the package has a password helper, wrap it so you control the algorithm and cost factor in one place.

Testing. Assert against the package's public interface with an in-memory repository fake. Since upstream test coverage is your only spec, mirror its test cases in your own suite to catch regressions when you bump the dependency.

Feature work. Build registration, login, profile editing, and role checks as your own services on top; the package gives you the data shape, not the workflows.

Gotchas and Tips

• Not Laravel-native. No service provider auto-discovery contract you'd expect, no Eloquent model, no Authenticatable. Expect to write the glue.
• Maintenance risk. Zero stars and zero dependents means no community buffer. Pin the exact version in composer.json, commit the lock file, and keep a note of what you rely on so you can fork it if needed.
• Mapping friction. If the entity uses a custom or Doctrine-style mapping, double-check field names and nullability against your DB schema before debugging auth — mismatches surface as "password always wrong" or "user never found," not as clear errors.
• Hashing mismatch. The most common silent failure: storing a plaintext or double-hashed password because you hashed in one layer and the package/repository hashed again. Hash in exactly one place.
• Extension points. Prefer subclassing the entity or implementing the package's interfaces over editing vendor code; traits shipped with the package (timestamps, identifiers) are usually the intended customization hook.
• Debugging. When login fails, dump the hydrated user object right before verification and confirm identifier, password hash, and any enabled/status flags are what you expect — the package won't tell you which condition failed.
• Config quirks. Anything configurable (table names, hashing) is likely set at construction or via the manager, not via config/*.php. Read the constructor signatures in src/ — that's where the real knobs are.
• Consider the alternative. For a new Laravel app, native Eloquent auth will be less work than integrating this. Reach for amethyst/user when you're already inside the Amethyst ecosystem or need its specific entity shape.