Ist Auth Bundle Laravel Package

Getting Started

Because this package has no stars, no dependents, and effectively no public documentation trail, treat onboarding as source-reading rather than doc-reading. The first 30 minutes should be spent answering "what does this actually register?" before writing any application code.

Install

composer require micro-module/ist-auth-bundle

If it isn't resolvable from Packagist, add a VCS repository entry and pin a commit — do not float on dev-main for anything auth-related:

"repositories": [{ "type": "vcs", "url": "https://github.com/temafey/micro_modules_ist_auth_bundle" }],
"require": { "micro-module/ist-auth-bundle": "dev-main#<commit-sha>" }

Look here first, in this order

1. composer.json — namespace/PSR-4 root, illuminate/* version constraints (this tells you which Laravel versions are actually supported, and whether it was written for 8.x and abandoned or is current).
2. The service provider(s) — usually src/*ServiceProvider.php or src/Providers/*.php. Read register() and boot() line by line. Everything the package does to your app happens here: config merges, route loading, middleware aliases, container bindings, migrations, event listeners.
3. config/ — the package's config file is the real API surface. Any env() calls here define what you must set.
4. routes/ and src/Http/Middleware/ — what routes it exposes (login/logout/callback?) and what middleware it registers.
5. database/migrations/ — whether it expects to own the users table or add to it.

First use case to validate

Don't integrate with your whole app first. Stand up a throwaway Laravel app, install, and get one guarded route working end-to-end:

Route::middleware('auth')->get('/dashboard', fn () => 'ok');

or, if the bundle ships its own guard/middleware alias:

Route::middleware('ist.auth')->group(function () {
    Route::get('/dashboard', DashboardController::class);
});

That single request exercises provider boot, config resolution, guard registration, and the user provider — if it works, the rest of the package is likely usable. If it doesn't, you've found the blocker before it's buried in your app.

Implementation Patterns

Guard/provider replacement, not coexistence, where possible

This kind of bundle typically registers a custom guard or user provider. Pick one strategy and commit:

• Replace: point config/auth.php guards.web.driver (or a new guard) at whatever the bundle registers, and use it as your single source of truth.
• Coexist: leave web alone and register the bundle as a second guard, then apply it only to specific route groups. This is safer for brownfield apps but means Auth::user() and auth()->guard('ist') diverge — every call site must be explicit about which guard it means.

Coexistence is almost always the right call during initial adoption; replacing auth wholesale on an unvetted 0-star package is not.

Route-group middleware as the primary integration point

Keep the bundle's surface area at the routing layer. Apply its middleware to a group, leave the rest of the app's auth untouched:

Route::prefix('account')
    ->middleware(['web', 'ist.auth'])
    ->group(base_path('routes/account.php'));

This keeps blast radius small and makes rollback a one-line change if the package turns out to be unsuitable.

Publish config, don't rely on defaults

php artisan vendor:publish --provider="MicroModule\IstAuthBundle\IstAuthServiceProvider" --tag=config

Published config is your override point for everything the package hardcodes — guard names, table names, redirect routes, TTLs. If a --tag isn't documented, run vendor:publish without arguments and read the prompt; it lists available tags.

Extend, don't edit vendor

If the bundle ships a User model, a controller, or a middleware you need to change, bind your own implementation in a service provider rather than editing vendor/. Typical extension points:

$this->app->bind(
    \MicroModule\IstAuthBundle\Contracts\UserResolver::class,
    \App\Auth\CustomUserResolver::class
);

Check the provider's register() for bind/singleton calls — those reveal the intended extension seams. If there are none, that itself is an assessment finding: the package may require forking.

Compose with other micro-module/* packages deliberately

The micro-module naming implies a family of small bundles designed to be stacked. If you're using several, watch provider registration order — auth providers that touch the users table or register guards need to boot after the packages that define those models. If ordering matters, disable auto-discovery for the bundle and register it explicitly in config/app.php after its dependencies.

Test the guard boundary, not the package internals

Don't unit-test the bundle. Test your app's behavior at the guard boundary with feature tests:

public function test_account_requires_ist_guard(): void
{
    $this->get('/account')->assertRedirect();
}

public function test_user_can_reach_account(): void
{
    $user = User::factory()->create();
    $this->actingAs($user, 'ist')->get('/account')->assertOk();
}

actingAs($user, 'ist') also serves as a smoke test that the guard is actually registered — if the named guard doesn't exist, the test fails loudly, which is exactly what you want.

Gotchas and Tips

Zero stars and zero dependents is a security finding, not a footnote. Auth code is the highest-trust code in your app. Before production: read every line of the provider, middleware, and any crypto/token/HMAC code; confirm no outbound calls to unfamiliar endpoints; check git history and commit dates for abandonment signals. Pin to a commit SHA, and be prepared to fork. A small auth bundle is forkable in an afternoon — treat that as the fallback plan from day one.

"Bundle" is Symfony vocabulary. The name suggests Symfony heritage or a developer coming from Symfony. In Laravel land this is a service provider package; don't expect Symfony DI, compiler passes, or bundle config files. Conversely, don't assume the author's Laravel conventions match yours — check composer.json constraints against your app's version before assuming anything works.

Config merge silently losing to defaults. If the provider calls mergeConfigFrom, your published config should win, but a nested array merge can produce surprising results (package defaults surviving inside nested keys). When a setting appears ignored, dd(config('ist-auth')) immediately after boot and compare against the published file — you're looking for keys that didn't survive.

Guard name collisions. If the bundle registers a guard named web or api (rather than something namespaced like ist), it will clobber your existing config. Check config/auth.php after install and after any vendor:publish — a published file that overwrites your carefully configured guards is a classic first-day incident.

Migration ordering and table ownership. Auto-loaded migrations run with the package's timestamp prefix. If the bundle ships a users migration and you already have one, you get either a duplicate-table failure or, worse, a silent no-op depending on hasTable checks. Disable the package's migrations if you own the table, or rename yours — but decide before running migrate for the first time.

Middleware alias registration is easy to miss. If the bundle's provider calls $kernel->routeMiddleware([...]) or Router::aliasMiddleware, the alias only exists after boot. Referencing ist.auth in RouteServiceProvider (which loads very early) can fail in edge ordering cases. Test with php artisan route:list -v — it shows resolved middleware per route and surfaces missing aliases immediately.

Debugging checklist when "it just doesn't authenticate"

php artisan about                 # confirm provider is discovered and loaded
php artisan route:list -v         # confirm middleware alias resolved on the route
php artisan config:show auth      # confirm guard and provider entries

Then, in a tinker session: Auth::guard('ist') — if this throws, the guard isn't registered; if it returns a guard but Auth::guard('ist')->user() is always null, the provider is misconfigured or the session/redirect flow is broken.

Clear caches aggressively during setup. config:cache will bake in stale defaults and make config changes appear ineffective. When debugging unexpected package behavior, always php artisan optimize:clear before drawing conclusions.

Session/redirect quirks. Auth bundles frequently assume web middleware and session state. Applied to an API route group without web, you'll get confusing null-user behavior rather than a clear error. Match the package's middleware to the route group it was designed for; check the provider's route definitions for the assumed stack.

Extension points to look for, and what their absence means. Ideally the provider binds contracts (bind/singleton) for the user resolver, token generator, and redirect logic. If it hardcodes new instances instead, you cannot override behavior without forking. Note this in your adoption decision — it's the difference between "configurable" and "vendored code you happen to install via composer."

Version-lock everything. With no dependents, there's no community pressure to maintain backward compatibility. A minor-version bump could rename a config key or drop a method you rely on. Pin exact versions and upgrade deliberately with a test run of your guard-boundary feature tests.