Auth Laravel Package

Getting Started

smorken/auth is not on Packagist. The first step is making Composer aware of the Bitbucket repository, then pinning a commit so builds are reproducible.

// composer.json
"repositories": [
    {
        "type": "vcs",
        "url": "https://bitbucket.org/scott_morken/auth.git"
    }
],
"require": {
    "smorken/auth": "dev-master#<commit-sha>"
}

Bitbucket HTTPS clones often require credentials. If composer require hangs or returns 403, add a Bitbucket app password to auth.json or switch to SSH:

"url": "[email protected]:scott_morken/auth.git"

Before writing application code, inspect the package in this order:

1. composer.json — check the require block for Laravel and PHP constraints. This is the compatibility gate; do not assume it supports your Laravel version.
2. README.md — the only reliable description of public API, config keys, middleware aliases, and published views.
3. src/ — locate the service provider, any facade, config file, controllers, middleware, model traits, and migrations.
4. tests/ — if absent, treat every flow as unverified and write your own feature tests.

Then publish whatever the package exposes:

php artisan vendor:publish --provider="Smorken\Auth\AuthServiceProvider"

If auto-discovery is not declared in the package’s composer.json, manually register the provider in config/app.php.

First use case: protect a single route with the package’s auth middleware and prove the login flow end-to-end in a throwaway branch. Do not start with registration or password reset — login is the smallest surface that exercises guard, provider, session, and redirect configuration together.

// routes/web.php
Route::middleware(['auth'])->group(function () {
    Route::get('/dashboard', DashboardController::class);
});

If the package supplies its own middleware alias, use that alias exactly as documented; otherwise fall back to Laravel’s auth middleware and verify the package’s guard is the default.

Implementation Patterns

Wrap the package behind an internal adapter. Day-to-day calls should go through your own service or facade, not directly to package classes. This gives you a one-file swap-out path when the package is abandoned or a Laravel upgrade breaks it.

namespace App\Auth;

use Smorken\Auth\SomePackageClass;

class AuthService
{
    public function login(array $credentials): bool
    {
        return SomePackageClass::attempt($credentials);
    }
}

Configure guards and providers explicitly. In config/auth.php, confirm the package’s guard driver and user provider are registered against your actual user model. Do not rely on the package overwriting framework defaults. If the package publishes its own config/auth.php, diff it against your existing config rather than replacing it.

Protect routes with middleware groups, not per-route middleware. Apply the package’s middleware alias to a group so login, logout, and redirect behavior stays consistent.

Route::middleware(['auth:web'])->group(function () {
    Route::get('/account', [AccountController::class, 'show']);
});

Override views and redirects through config, not by editing vendor files. Publish views, then set the package’s view namespace or redirect keys in config/auth.php or the package’s published config. Keep custom login/register views in resources/views/auth/ and point the package at them.

Treat registration and password reset as separate integrations. Each has its own controller, validation, broker, and redirect path. Enable them one at a time:

1. Login
2. Logout
3. Route protection
4. Registration
5. Password reset

Use Laravel’s native testing helpers. Write feature tests for each flow before relying on the package in a shared branch.

public function test_user_can_login(): void
{
    $user = User::factory()->create(['password' => bcrypt('secret')]);

    $this->post('/login', [
        'email' => $user->email,
        'password' => 'secret',
    ])->assertRedirect('/dashboard');

    $this->assertAuthenticatedAs($user);
}

Keep the user model framework-native. The package expects an Authenticatable model. Do not add package-specific traits unless the source clearly requires them; prefer Laravel’s Authenticatable, Notifiable, and standard password broker contracts.

Use it as a reference implementation where possible. If the package’s only value is scaffolding, copy the relevant patterns into your own auth layer and remove the dependency. That is often the lowest-risk way to “leverage” an unmaintained helper.

Gotchas and Tips

• No Packagist means no standard supply-chain signals. No GitHub advisories, no Dependabot, no Packagist metadata. You must track the Bitbucket repository manually and audit it quarterly.
• Pin to a commit, never dev-master. A branch rename or repository visibility change can break every clean build simultaneously. Use dev-master#<sha> and cache Composer dependencies in CI.
• Check Laravel version constraints before anything else. If composer.json targets Laravel 5.x or 8.x, do not attempt to install it on Laravel 10/11 without reading the source for guard contract changes.
• Service provider auto-discovery may be missing. If package classes are not found, manually add the provider to config/app.php and run composer dump-autoload.
• Publishing config can overwrite your auth setup. Back up config/auth.php before running vendor:publish, and diff rather than replace.
• Guard name assumptions break custom setups. The package may hard-code web or assume a default guard. If your app uses multiple guards or a custom session guard, test login, logout, remember-me, and password reset separately.
• Middleware alias collisions are common. Check app/Http/Kernel.php for existing aliases before registering the package’s middleware. Prefer a distinct alias if the package provides one.
• Password reset is the most fragile flow. Verify the password broker name, token table, throttling config, and reset URL. A helper that assumes framework defaults will fail silently when your broker is customized.
• Remember-me and session cookies need explicit testing. These often depend on guard configuration and cookie names that a helper may not expose.
• View namespace conflicts. If the package publishes to resources/views/auth, it can collide with Breeze/Jetstream or your own auth views. Publish to a package namespace and override selectively.
• Debug with framework tools first. Use php artisan route:list, php artisan config:show auth, and Auth::guard()->check() inside a test route to confirm which guard is active. If the package registers its own guard driver, inspect config/auth.php for the driver name.
• Assume you own the code. With zero dependents and no visible release process, there is no upstream maintenance guarantee. Assign an internal owner, vendor or fork the source, and include it in your security review path before any customer-facing use.
• Do not use it for compliance-sensitive auth. SOC 2, HIPAA, PCI, SSO/OIDC, and multi-tenant production launches should use Laravel’s first-party stack (Breeze, Fortify, Sanctum) or a supported IAM provider.