Auth Bundle Laravel Package

Getting Started

This is an internal Proviante package, not a public Packagist release. That single fact shapes every step below: you cannot composer require it from a fresh checkout, and you should not expect community docs, issue trackers, or Stack Overflow answers. Budget the first hour for reconnaissance, not integration.

Access & install

1. Get GitLab access to proviante.gitlab.yandexcloud.net/ebedak2003/auth.git before touching composer.json. Without it Composer will fail on a private-host clone, usually with a misleading 404.

2. Register the repo as a VCS source (or use your org's private Composer registry if one exists):

   {
     "repositories": [
       { "type": "vcs", "url": "[email protected]:ebedak2003/auth.git" }
     ]
   }
   

3. Require it by the package name declared in its composer.json, not by the repo slug — these frequently diverge. Confirm the real name and current tag first.

4. Pin to a tag or commit, never dev-main. With zero external consumers, semver discipline is unverified.

Where to look first (in order)

• composer.json — actual package name, require constraints (which Laravel versions are actually supported), autoload PSR-4 root.
• README.md — likely the only source of truth for config keys and setup steps. Read it fully before writing any code.
• The service provider — find it via "extra": {"laravel": {"providers": [...]}}. This tells you what is registered, what is bindable, and whether config/routes/migrations are published.
• config/*.php — every option with its default; this is effectively the package's public API.
• Any src/Http/Middleware and src/Guards — this is where Laravel-auth behavior actually lives.

First use case

The fastest win is almost always: pull the package in, publish its config, run migrations in a scratch DB, then protect one existing route with whatever middleware/guard it exposes. Do this on a throwaway branch with a seeded user. Do not attempt to retrofit an existing auth system on day one — you need to see the package's shapes (user model assumption, guard driver, token vs session) before deciding whether it replaces or sits alongside Laravel's Breeze/Jetstream/Sanctum setup.

Implementation Patterns

Discovery-before-integration. Because there are no dependents, treat this package as an unknown quantity: write a throwaway test that boots the provider, resolves the bindings, and asserts your existing User model satisfies whatever interface it expects. Ten minutes there beats a day of debugging a silent guard mismatch.

Service provider registration. If the package uses auto-discovery you get this for free. If not, add it to config/app.php providers. Either way, verify order — auth-related providers that boot before AuthServiceProvider or before your user provider registration will fail at resolve time, often with a confusing Target [..] is not instantiable.

Config-first configuration. Prefer publishing (php artisan vendor:publish --provider=...) and committing the published config over reading env vars directly in the package. This gives you a diffable record of what you changed and makes the package's assumptions visible in code review. Never edit the vendor copy.

Guard / middleware integration. Typical auth-bundle shapes are a custom guard driver, middleware aliases, and sometimes an alternative user provider. Integrate by:

• Registering the guard in config/auth.php under a named guard rather than replacing web.
• Aliasing middleware in Kernel.php (Laravel <11) or bootstrap/app.php (Laravel 11+), then applying it to specific route groups before rolling it out app-wide.
• Running both old and new guards in parallel on a staging environment for a sprint before cutting over.

Testing. Add a contract test suite that exercises the package's happy path through your application, not its internals. Since upstream has no test signal (0 dependents, 0 stars), your app becomes the only regression net. Pin the commit and re-run these tests on every bump.

CI integration. Add GitLab credentials to your CI runner (a deploy token with read_repository scope is enough) and store them as CI variables referenced in composer.json’s auth config or a global composer config http-basic step. Without this, local builds pass and pipeline builds fail on a bare 404. Cache the Composer files directory keyed on composer.lock to avoid re-fetching the private repo on every job.

Wrapping the package. Because you cannot patch upstream quickly, put a thin application-level wrapper (a service class or adapter) around the package's primary entry points. When behavior changes on the next internal release, you adjust one file instead of grep-replacing across the codebase.

Gotchas and Tips

The naming misleads. -bundle is Symfony terminology; Laravel calls these packages, and bundles use a different discovery mechanism. Confirm whether composer.json actually targets laravel/framework or symfony/*. If the latter, this is not a Laravel package and needs a bridge — check the require block before assuming anything.

Private-repo failure modes. A 404 from Composer almost always means auth, not existence — GitLab returns 404 rather than 403 for private repos a token cannot see. Test with ssh -T [email protected] or a curl against the repo API with your token before debugging Composer.

No upstream safety net. Zero stars and zero dependents means: no external bug reports, no community patches, no proof the package is maintained. Treat it as vendor code you may have to fork. Keep a local path-repo fork or a repositories override ready so you can ship a hotfix on the same day a bug blocks a release. This is the single biggest operational risk of adopting it.

Version pinning is mandatory. With no downstream users, untested tags are likely. Pin exact versions ("1.2.3", not "^1.2"), commit composer.lock, and require a PR to bump. If you use dev- constraints you will eventually be broken by an unrelated composer update.

Migrations. Publish and inspect migrations before running them. Watch for: hardcoded table names that collide with your users table, missing foreign-key indexes, and assumptions about primary keys (UUID vs auto-increment). If the package ships its own user model, decide early whether to extend it or swap in your own via config — mixing the two is a common source of "column not found" errors.

Debugging. When auth silently fails (user resolves to null, guard returns false), the issue is almost always ordering: config published after the provider cached it, config:cache not cleared after a config change, or the guard registered under a name that routes do not reference. php artisan config:clear && php artisan route:list -v to confirm middleware actually attached, then Auth::guard('name')->user() in tinker to isolate guard vs. middleware.

Extension points. Real auth packages expose at minimum: a user provider (to swap models), a guard driver, and events (login, logout, failure). Before writing any workaround, check the config for a provider/model/table override — most integration pain is caused by missing an existing hook. If the package exposes no extension points, that is a signal to wrap it heavily or fork it.

Terminology in code review. Since no one else uses this package, every integration decision is institutional knowledge. Document the guard name, the config keys you changed, the pinned version, and why — otherwise the next developer to touch auth will re-derive all of it from scratch.