Easy Api Token Laravel Package

Getting Started

The package is a read-only mirror with essentially zero public adoption, so treat the repository source as the authoritative docs. First steps:

1. Read the source before installing. Composer-require it into a scratch Laravel app (composer require eonx-com/easy-api-token), then follow the service provider's boot()/register() methods and any published config. EonX packages conventionally ship a config/easy-api-token.php with a token_lifetime, token_length, and hashing driver — confirm what actually exists rather than assuming.
2. Check the Laravel/Eloquent vs Doctrine split. EonX historically built some packages on Doctrine ORM (eonx-com/easy-doctrine-*). If this one requires Doctrine entities or a custom repository interface, your install needs that stack; if it ships an Eloquent model/migration, php artisan migrate after publishing. Look under src/ for Entity/, Model/, or Bridge/ directories to tell which.
3. Publish config and migrations (the typical EonX pattern):

   php artisan vendor:publish --tag=easy-api-token-config
   php artisan vendor:publish --tag=easy-api-token-migrations
   php artisan migrate
   

4. First use case: issue a token on user creation, store only the hash, and return the plaintext once to the caller. That flow (generate → return once → verify on request) is what these packages exist to standardize.

Minimal happy path to verify the package works in your app:

$token = $user->createApiToken('mobile-app'); // or ApiToken::generateFor($user)
return response()->json(['token' => $token->plainTextToken]);

Then hit a route protected by the package's middleware and confirm authentication resolves the correct user.

Implementation Patterns

Issue-and-forget tokens from a login or register controller. Generate inside AuthController@login, return the plaintext in the JSON response, never persist it. Persist only the hash and metadata (name, last_used_at, expires_at). This is the canonical use case and keeps you aligned with the package's storage assumptions.

Middleware-first authentication. Register the package's guard/middleware (likely auth:easy-api-token or a TokenAuthenticator binding) as a route group guard rather than calling verification manually in controllers. Centralizing auth means $request->user() resolves consistently and last_used_at updates happen in one place.

Scoped / ability tokens. If the package supports abilities (EonX often models these as a JSON column or separate table), issue granular tokens — ['orders:read', 'orders:write'] — and gate with $request->user()->tokenCan('orders:read'). Use Laravel's can: middleware on routes so abilities stay declarative. Where the package lacks abilities, wrap verification in a small EnsureTokenAbility middleware of your own.

Hash-not-store plaintext. The whole point of a token package is that a DB dump shouldn't leak credentials. Confirm the hash algorithm in config (sha256 is standard; bcrypt is slow and usually wrong for high-volume API tokens). If the package stores plaintext by default, override it — that's a red flag worth checking early.

Rotate on privilege change. On password change or email change, revoke all tokens ($user->apiTokens()->delete()) and issue a fresh one. Pattern the revocation as a UserObserver or an event listener on PasswordChanged so it can't be forgotten.

Testing. Use actingAs($user, 'api') or withHeader('Authorization', "Bearer {$token->plainText}") in feature tests. If you can, seed a token in a factory so tests don't hit the real login endpoint.

Gotchas and Tips

• Zero public dependents and one star means no Stack Overflow trail. When something breaks, git log and the tests in the repo are your only reference. Budget an afternoon to read tests/ — EonX tests are usually more instructive than the README.
• EonX naming changes over time. Some of their packages moved from Doctrine entities to Eloquent models between minor versions. Check the composer.json require block for doctrine/orm before assuming Eloquent.
• Token prefix mismatches. If the package generates tokens with a prefix (e.g. pat_...), make sure your extraction logic in any custom middleware strips the prefix correctly before hashing. Hashing a prefixed token against a stored unprefixed hash is the most common verification-failure cause.
• Expiration is usually config-driven, not per-token. If token_lifetime is set in config, all tokens share the same TTL. If you need per-token expiry (e.g. short-lived mobile vs long-lived CLI), you may have to pass it through the generation method or override the model.
• last_used_at write amplification. If the package writes to the DB on every request, cache the write (e.g. only update if older than 60 seconds) or you'll add a write to every API call. Check the middleware source for how it handles this.
• Timing-safe comparison matters. Verify the package uses hash_equals() rather than == when comparing hashes. If not, wrap it yourself — a public token endpoint is a timing-oracle target.
• Revocation cache. If you cache token lookups (Redis, etc.), remember to bust the cache on revoke(). Otherwise a revoked token stays valid until TTL, which is a security issue that's easy to miss in tests.
• Extension points to look for: the token repository interface (for custom storage), the token generator contract (for alternate formats like UUIDs), and the config driver option (for swapping hashers). EonX packages typically expose these in src/Contracts/ or src/Interfaces/ — use them rather than forking.
• Abandoned-package risk. With no adoption and a READ-ONLY mirror, assume maintenance is minimal. If you're building a public product, consider laravel/sanctum instead, which covers the same ground with guarantees this package can't offer. Use this only if you're already in the EonX ecosystem or need its specific conventions.