PHPackages                             xultech/auth-log-notification - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. xultech/auth-log-notification

AbandonedArchivedLibrary[Authentication & Authorization](/categories/authentication)

xultech/auth-log-notification
=============================

Log user authentication events and send login alerts via Mailable and Notification.

v1.0.9(1y ago)4271MITPHPPHP ^8.1

Since Mar 24Pushed 7mo ago2 watchersCompare

[ Source](https://github.com/Xultech-LTD/laravel-auth-log-notification)[ Packagist](https://packagist.org/packages/xultech/auth-log-notification)[ RSS](/packages/xultech-auth-log-notification/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (16)Versions (11)Used By (0)

AuthLogNotification for Laravel
===============================

[](#authlognotification-for-laravel)

A Laravel package for tracking authentication activity, detecting suspicious logins, and notifying users in real time via Mail, Slack, or SMS.

It logs login, logout, and failed attempts, adds device and location awareness, supports session fingerprinting, rate limiting, and integrates seamlessly with your existing authentication flow.

Features
--------

[](#features)

- ✅ Tracks login, logout, failed login, and re-authentication events
- 🌍 Detects IP address, device type, browser, and geolocation
- 🔔 Sends real-time login alerts via Mail, Slack, and SMS (Vonage)
- 🧠 Detects suspicious logins based on device, IP, and location history
- 🔒 Supports session fingerprinting to detect hijacked sessions
- 🚫 Applies rate limiting and temporary lockouts for failed login attempts
- 🧩 Allows custom hook execution on auth events
- 📊 Includes Blade components for login/session insights
- 🧼 Artisan commands for log cleanup and geo-location syncing
- 🔌 Easily integrates with existing User models via a trait
- 🔧 Fully configurable and extendable

---

Installation
------------

[](#installation)

You can install the package via Composer:

```
composer require xultech/auth-log-notification
```

The package uses Laravel's auto-discovery, so no additional configuration is needed for Laravel 5.5 and above.

If you're using Laravel below 5.5, you’ll need to manually register the service provider in config/app.php:

```
'providers' => [
    // ...
    Xultech\AuthLogNotification\AuthLogNotificationServiceProvider::class,
],
```

> Before you begin to use this package ensure you have published the GeoIP config package. You can find the details about how to do this at [Torann/laravel-geoip](https://github.com/Torann/laravel-geoip)

---

Configuration
-------------

[](#configuration)

To publish the configuration file, run:

```
php artisan vendor:publish --provider="Xultech\AuthLogNotification\AuthLogNotificationServiceProvider" --tag="authlog-config"
```

This will create a file at:

```
config/authlog.php
```

### Available Configuration Options

[](#available-configuration-options)

#### 🔘 enabled

[](#-enabled)

Enable or disable the entire package globally.

```
'enabled' => true,
```

#### 🗂️ log\_events

[](#️-log_events)

Control which authentication events should be logged.

```
'log_events' => [
    'login'             => true,
    'logout'            => true,
    'failed_login'      => true,
    'password_reset'    => false,
    're-authenticated'  => false,
],
```

#### 📣 notification

[](#-notification)

Configure how users should be notified about login events.

```
'notification' => [
    'channels' => ['mail'], // Supports: mail, slack, nexmo (SMS)
    'mode' => 'notification', // 'notification' or 'mailable'
    'only_on_suspicious_activity' => true,

    'channels_config' => [
        'mail' => [
            'enabled' => true,
            'template' => 'authlog::mail.login-alert',
        ],
        'slack' => [
            'enabled' => false,
            'channel' => '#alerts',
        ],
        'nexmo' => [
            'enabled' => false,
            'phone_field' => 'phone',
        ],
    ],
],
```

#### 📩 default\_notification

[](#-default_notification)

Override default values used for notification channels.

```
'default_notification' => [
    'subject' => 'New Login Detected',
    'slack_channel' => '#security-alerts',
    'mail_from' => env('MAIL_FROM_ADDRESS', 'no-reply@example.com'),
    'mail_view' => 'authlog::mail.login-alert',
],
```

#### 🧠 device\_detection

[](#-device_detection)

Enable device tracking, user-agent, and metadata storage.

```
'device_detection' => [
    'enabled' => true,
    'store_user_agent' => true,
    'store_device_metadata' => true,
],
```

#### 🌍 location\_detection

[](#-location_detection)

Control geo-location detection settings.

```
'location_detection' => [
    'enabled' => true,
    'driver' => 'torann/geoip',
    'store_metadata' => true,
    'strict' => false,
],
```

#### 🧬 session\_tracking

[](#-session_tracking)

Enable session tracking and fingerprint validation.

```
'session_tracking' => [
    'enabled' => true,
    'generate_session_id' => true,
    'enforce_single_session' => false,

    'fingerprint' => [
        'enabled' => true,
        'store_in_session' => true,
        'validate_on_request' => false,
    ],

    'session_fingerprint' => [
        'enabled' => true,
        'validate_on_request' => true,
        'abort_on_mismatch' => true,
        'redirect_to' => '/login',
        'notify_user' => true,

        'notify_admins' => [
            'emails' => ['admin@example.com'],
            'slack_webhooks' => [
                // Add your Slack webhook URLs here
            ],
        ],
    ],
],
```

#### ✅ whitelisted\_ips

[](#-whitelisted_ips)

List of IPs that will never trigger alerts or be flagged.

```
'whitelisted_ips' => [
    '127.0.0.1',
    '::1',
],
```

#### 🛡️ security\_thresholds

[](#️-security_thresholds)

Thresholds to detect brute-force and location change behavior.

```
'security_thresholds' => [
    'failed_attempts_before_alert' => 3,
    'alert_on_geo_change' => true,
    'cooldown_minutes' => 3,
],
```

#### 🧼 retention

[](#-retention)

Control log retention and cleanup behavior.

```
'retention' => [
    'enabled' => true,
    'days' => 90,
    'delete_method' => 'soft', // Options: 'soft', 'hard'
],

'auto_cleanup' => true,
```

#### 🔄 hooks

[](#-hooks)

Bind custom callbacks or listeners to authentication events.

```
'hooks' => [
    'on_login'  => null,
    'on_logout' => null,
    'on_failed' => null,
],
```

#### 🛠️ admin

[](#️-admin)

Optional admin view configuration (for future support or custom use).

```
'admin' => [
    'viewer_enabled' => false,
    'viewer_route' => '/admin/auth-logs',
    'middleware' => ['web', 'auth', 'can:view-auth-logs'],
],
```

#### 🧭 location\_service

[](#-location_service)

Customize the geolocation service class.

```
'location_service' => \Xultech\AuthLogNotification\Services\GeoLocation\GeoLocationService::class,
```

#### ⚠️ suspicion\_rules

[](#️-suspicion_rules)

Define logic for what counts as a suspicious login and whether to block it

```
'suspicion_rules' => [
    'new_device' => true,
    'new_location' => true,
    'block_suspicious_logins' => false,
],
'suspicious_login_handler' => \Xultech\AuthLogNotification\Handlers\SuspiciousLoginHandler::class,
```

#### 🔐 lockout

[](#-lockout)

Rate limiting and lockout configuration for brute-force protection.

```
'lockout' => [
    'enabled' => true,
    'key_prefix' => 'authlog:lockout:',
    'max_attempts' => 5,
    'lockout_minutes' => 10,
    'track_by' => 'ip', // Options: 'ip', 'email', 'both'
    'generic_response' => true,
    'redirect_to' => '/login',
],
```

#### 🛑 middleware\_blocking

[](#-middleware_blocking)

Configure the middleware that blocks suspicious login attempts before authentication (i.e., on the login route).

```
'middleware_blocking' => [

    // Enable or disable the middleware
    'enabled' => true,

    // The Eloquent model class used to identify the user (e.g., App\Models\User::class)
    // Use a string, not ::class, for compatibility with package-based environments
    'user_model' => 'App\\Models\\User',

    // The database column used to match the user (e.g., 'email', 'username')
    'email_column' => 'email',

    // The request input key used in your login form (e.g., 'email', 'login', 'identifier')
    // This should match the input name your users fill out when logging in
    'request_input_key' => 'email',
],
```

> This powers the `authlog.block-suspicious` middleware. When enabled, the system checks if the login attempt is from a new device or IP, and blocks the request before authentication if suspicious.

To use it:

```
Route::post('/login', [LoginController::class, 'store'])
    ->middleware('authlog.block-suspicious');
```

This gives you full control over how authentication is monitored, logged, and secured within your Laravel app. Adjust the values to fit your security strategy.

---

Publishing Assets
-----------------

[](#publishing-assets)

This package provides some required and optional assets that can be published into your application for customization.

### 🗃️ Migrations (Required)

[](#️-migrations-required)

To publish the database migration:

```
php artisan vendor:publish --provider="Xultech\AuthLogNotification\AuthLogNotificationServiceProvider" --tag="authlog-migrations"
```

This will copy the migration file to:

```
database/migrations/xxxx_xx_xx_xxxxxx_create_auth_logs_table.php
```

Make sure to run:

```
php artisan migrate
```

### 🖼️ Views

[](#️-views)

To customize the email or notification templates, publish the view files:

```
php artisan vendor:publish --provider="Xultech\AuthLogNotification\AuthLogNotificationServiceProvider" --tag="authlog-views"
```

View files will be published to:

```
resources/views/vendor/authlog/
```

You can edit templates like login-alert.blade.php to match your brand or layout.

### 🧩 Blade Components

[](#-blade-components)

The package provides reusable Blade components. To customize them, publish the components:

```
php artisan vendor:publish --provider="Xultech\AuthLogNotification\AuthLogNotificationServiceProvider" --tag="authlog-components"
```

This will publish components like:

- ``
- ``
- ``
- ``

These components can be embedded in your dashboard or user profile pages to display session-related information at a glance.

### 🎧 Listeners (Optional)

[](#-listeners-optional)

If you'd like to customize what happens on login/logout/failed/password reset:

```
php artisan vendor:publish --provider="Xultech\AuthLogNotification\AuthLogNotificationServiceProvider" --tag="authlog-listeners"
```

This will copy listeners like `LoginEventListener`, `LogoutEventListener`, etc., into:

```
app/Listeners/AuthLog/
```

You can then customize what each event does, such as triggering custom notifications, logging to other tables, or extending tracking logic.

### 📡 Events (Optional)

[](#-events-optional)

To customize or extend the package’s custom events:

```
php artisan vendor:publish --provider="Xultech\AuthLogNotification\AuthLogNotificationServiceProvider" --tag="authlog-events"
```

This publishes events like ReAuthenticated to:

```
app/Events/AuthLog/
```

### 🔔 Notifications (Optional)

[](#-notifications-optional)

To modify how users are notified when login or suspicious activity occurs:

```
php artisan vendor:publish --provider="Xultech\AuthLogNotification\AuthLogNotificationServiceProvider" --tag="authlog-notifications"
```

This copies notification classes (like LoginAlertNotification) into:

```
app/Notifications/AuthLog/
```

### 🛡️ Middleware (Optional)

[](#️-middleware-optional)

If you want to customize any of the built-in middlewares (rate limiting, session fingerprinting, or blocking suspicious logins), you can publish them like so:

```
php artisan vendor:publish --provider="Xultech\AuthLogNotification\AuthLogNotificationServiceProvider" --tag="authlog-middleware"
```

Middleware classes will be published to:

```
app/Http/Middleware/AuthLog/
```

> The middleware documentation below lists all the available middlewares and how you can use them

---

Usage Guide
-----------

[](#usage-guide)

This package integrates deeply into your Laravel app with traits, scopes, components, and helpers. Here’s how to get started and make the most of it.

### 🧬 Add the Trait to Your User Model

[](#-add-the-trait-to-your-user-model)

To enable logging, session tracking, and notifications, you must add the `HasAuthLogs` trait to your `User` model (or any model implementing `Authenticatable` and `Notifiable`):

```
use Xultech\AuthLogNotification\Traits\HasAuthLogs;

class User extends Authenticatable
{
    use HasAuthLogs;

    // ...
}
```

This trait wires in all the core features of the package, including:

- Access to login and session history
- Device and location details for each login
- Notification routing (e.g. phone for SMS)
- Query scopes for fetching login activity
- Helpers for previous and current sessions

### 🧠 Helper Methods from the Trait

[](#-helper-methods-from-the-trait)

After adding the trait, your model now has several powerful methods:

#### ⏱️ Login Timestamps

[](#️-login-timestamps)

```
$user->lastLoginAt();         // Timestamp of latest login
$user->previousLoginAt();     // Timestamp of login before last
```

#### 🌐 IP Address History

[](#-ip-address-history)

```
$user->lastLoginIp();         // IP of last login
$user->previousLoginIp();     // IP before last
```

#### 📖 Login History & Collections

[](#-login-history--collections)

```
$user->authentications();     // All login logs (latest first)
$user->logins();              // Last 5 successful logins
$user->logins(10);            // Last 10 logins
$user->loginsToday();         // Logins from today only
```

#### ❌ Failed & Suspicious Logins

[](#-failed--suspicious-logins)

```
$user->failedLogins();        // All failed attempts
$user->failedLoginsCount();   // Count of failed attempts
$user->suspiciousLogins();    // New device or location
$user->lastLoginWasSuspicious(); // Was last login suspicious?
$user->lastLoginWasFromIp('1.2.3.4'); // Did user login from a specific IP?

```

#### 📍 Location & Device Awareness

[](#-location--device-awareness)

```
$user->lastKnownLocation();   // e.g., "Lagos, Nigeria"
$user->lastKnownDevice();     // e.g., "Windows / Chrome (Desktop)"
```

#### 👥 Sessions & Activity

[](#-sessions--activity)

```
$user->activeSessions();      // Logins not yet logged out
$user->hasMultipleSessions(); // More than one active session?

```

### 📌 Query Scopes (AuthLogUserScopes)

[](#-query-scopes-authloguserscopes)

This package also registers custom query scopes dynamically via AuthLogUserScopes::register(): Example Queries:

```
User::loggedInToday()->get();       // Users active today
User::withFailedLogins()->get();    // Users with failed attempts
User::suspiciousActivity()->get();  // Users with flagged logins
User::multipleSessions()->get();    // Users with concurrent sessions
User::inactiveSince(60)->get();     // Users inactive for 60+ days
```

> Ensure AuthLogUserScopes::register() is called in a service provider (usually the package does this automatically).

### 📊 The AuthLog Model

[](#-the-authlog-model)

All authentication events are stored in the auth\_logs table via the AuthLog model.

##### Relationships:

[](#relationships)

```
$log->authenticatable; // Returns the related User/Admin/etc.
```

##### Scopes

[](#scopes)

```
AuthLog::completed();          // Sessions with logout_at
AuthLog::active();             // Currently active sessions
AuthLog::failed();             // Failed login attempts
AuthLog::fromIp('1.2.3.4');    // Filter by IP
AuthLog::withSession($id);     // Filter by session_id
```

##### State Checkers:

[](#state-checkers)

```
$log->isActive();              // Session still active?
$log->isFailed();              // Was this a failed login?
$log->isSuspicious();          // Marked suspicious?
$log->isLogin();               // Is this a login event?
$log->isLogout();              // Is this a logout event?

```

##### Accessors

[](#accessors)

```
$log->formatted_location;      // "Lagos, Nigeria"
$log->device_summary;          // "MacOS / Safari (Mobile)"
$log->event_type;              // "Login", "Failed Login"
$log->login_at_formatted;      // "2025-03-23 18:00:00"
$log->referrer_domain;         // Extracts domain from referrer
$log->user_agent_fragment;     // First 80 chars of user-agent
$log->is_suspicious;           // Boolean (true if login is suspicious)
```

> `is_suspicious` is a computed property that uses the `SuspicionDetector` service and respects the config settings for new device or new location detection.

🔔 Notifications
---------------

[](#-notifications)

This package allows you to notify users of login activity using Laravel’s built-in notification channels.

Notifications are sent when a user logs in, and can be routed through:

- **Email (Mail)**
- **Slack (via webhook)**
- **SMS (via Nexmo/Vonage)**

You have full control over:

- Which channels to use
- What content is sent
- When the notification is triggered (e.g., always or only on suspicious activity)
- Whether to use Laravel's `Notification` system or a custom `Mailable`

### Manually Logging Authentication Events

[](#manually-logging-authentication-events)

In addition to automatic detection through Laravel's auth events, you can also manually trigger logs and alerts from within your controllers, services, or custom login flows. This gives you full control over when and how logging occurs — especially useful for custom guards or stateless APIs.

##### 🔐 Login

[](#-login)

```
use Illuminate\Auth\Events\Login;
use Illuminate\Support\Facades\Event;
use Illuminate\Http\Request;

// Inside your login controller or service
$user = User::where('email', $request->email)->first();

// Perform login logic...

// Manually dispatch login event
Event::dispatch(new Login('web', $user, false));
```

##### ❌ Failed Login

[](#-failed-login)

```
use Illuminate\Auth\Events\Failed;

Event::dispatch(new Failed('web', null, [
    'email' => $request->email,
    'password' => $request->password,
]));
```

##### 🔓 Logout

[](#-logout)

```
use Illuminate\Auth\Events\Logout;

Event::dispatch(new Logout('web', auth()->user()));
```

##### 🔁 Password Reset

[](#-password-reset)

```
use Illuminate\Auth\Events\PasswordReset;

Event::dispatch(new PasswordReset($user));
```

##### 🔁 Re-Authentication (e.g. Password Confirm Screens)

[](#-re-authentication-eg-password-confirm-screens)

If you implement a flow like password confirmation, you can dispatch:

```
use Xultech\AuthLogNotification\Events\ReAuthenticated;

Event::dispatch(new ReAuthenticated($user));
```

> You only need to do this in custom logic. Laravel will automatically fire these events when using its built-in authentication system.

### 🔧 Notification Configuration

[](#-notification-configuration)

In your `config/authlog.php`, you’ll find the full notification settings:

```
'notification' => [
    'channels' => ['mail'], // Options: 'mail', 'slack', 'nexmo'
    'mode' => 'notification', // or 'mailable'
    'only_on_suspicious_activity' => true, // Only notify when flagged
],
'default_notification' => [
        'subject' => 'New Login Detected',
        'slack_channel' => '#security-alerts',
        'mail_from' => env('MAIL_FROM_ADDRESS', 'no-reply@example.com'),
        'mail_view' => 'authlog::mail.login-alert', // or 'authlog::mail.login-alert-html'
        'view_type' => 'markdown', // or 'html'
    ],
```

### 🔘 Notification Modes

[](#-notification-modes)

##### 1. notification (default)

[](#1-notification-default)

This uses Laravel's standard Notification class, meaning it's queued, well-integrated, and flexible.

```
'view_type' => 'markdown',
```

##### 2. mailable

[](#2-mailable)

If you prefer a full Mailable class (like a styled HTML email with branding), set this mode.

```
'view_type' => 'html',
```

Both modes are supported, and you can publish and override the default templates.

> If you are using markdown, you must also publish the Laravel’s Default Mail Views

Run this command to publish the views:

```
php artisan vendor:publish --provider="Xultech\AuthLogNotification\AuthLogNotificationServiceProvider" --tag="authlog-views"
php artisan vendor:publish --tag=laravel-mail
```

> if you encounter any errors while using `html`, run this:

```
php artisan vendor:publish --provider="Xultech\AuthLogNotification\AuthLogNotificationServiceProvider" --tag="authlog-views"
```

This publishes the custom HTML mail view for the email. Also ensure you set

```
'mail_view' => 'authlog::mail.login-alert', // or 'authlog::mail.login-alert-html'
```

to the corresponding view. You can define your default view which will be used, only that you need to set it in the `mail_view` configuration option.

### 📡 Notification Channels

[](#-notification-channels)

Define the channels you want to use:

```
'channels' => ['mail', 'slack', 'nexmo']
```

Each channel is configurable individually under channels\_config:

```
'channels_config' => [
    'mail' => [
        'enabled' => true,
        'template' => 'authlog::mail.login-alert',
    ],
    'slack' => [
        'enabled' => true,
        'channel' => '#security-alerts',
    ],
    'nexmo' => [
        'enabled' => true,
        'phone_field' => 'phone',
    ],
],
```

You can enable or disable each channel independently.

### 🖼️ Customizing Mail Templates

[](#️-customizing-mail-templates)

To customize the content or layout of your login alert emails:

```
php artisan vendor:publish --provider="Xultech\AuthLogNotification\AuthLogNotificationServiceProvider" --tag="authlog-views"
```

This will publish views like:

```
resources/views/vendor/authlog/mail/login-alert.blade.php
```

Update the layout, wording, or include branding as needed.

### 🧭 Notification Routing (Slack & SMS)

[](#-notification-routing-slack--sms)

Laravel needs to know where to send Slack messages or SMS alerts. You can define this in your User model.

##### Slack Routing

[](#slack-routing)

```
public function routeNotificationForSlack()
{
    return 'https://hooks.slack.com/services/XXX/YYY/ZZZ';
}
```

Or dynamically from the user:

```
public function routeNotificationForSlack()
{
    return $this->slack_webhook_url;
}
```

##### Nexmo/Vonage SMS Routing

[](#nexmovonage-sms-routing)

By default, the system will look for the field defined in phone\_field:

```
'nexmo' => [
    'phone_field' => 'phone',
]
```

If your model uses a different field name or you want more control:

```
public function routeNotificationForNexmo()
{
    return $this->phone_number;
}
```

#### ✉️ Default Notification Settings

[](#️-default-notification-settings)

You can also globally define subject lines, fallback Slack channels, and sender emails:

```
'default_notification' => [
    'subject' => 'New Login Detected',
    'slack_channel' => '#security-alerts',
    'mail_from' => env('MAIL_FROM_ADDRESS', 'no-reply@example.com'),
    'mail_view' => 'authlog::mail.login-alert',
    'view_type' => 'markdown', // or 'html'
],
```

These settings are used when no user-specific overrides exist.

#### 🔐 Suspicious Login Notifications Only

[](#-suspicious-login-notifications-only)

If you want to notify users only when a login is suspicious, enable this:

```
'only_on_suspicious_activity' => true,
```

Suspicious logins are flagged when:

- The user logs in from a new device
- The user logs in from a new location

This helps reduce noise and only notifies users when their account might be at risk.

---

This notification system is fully extensible, so you can create your own custom notifications, modify the channels, or build your own logic based on the AuthLog model or Laravel events.

🧩 Custom Hooks
--------------

[](#-custom-hooks)

This package allows you to hook into authentication events like login, logout, and failed login — giving you the power to run custom logic when those events fire.

You can define callbacks, dispatch jobs, send alerts, trigger audits, or anything else you want when a user authenticates.

---

### 🔧 Configuration

[](#-configuration)

In your `config/authlog.php`, you'll find the `hooks` section:

```
'hooks' => [
    'on_login'  => null,
    'on_logout' => null,
    'on_failed' => null,
],
```

Each hook accepts one of the following:

- A class name that implements \_\_invoke($user, $log)
- A closure
- A job class name
- A listener class

---

#### 🛠 Example: Logging Admin Login

[](#-example-logging-admin-login)

Let’s say you want to log a message whenever an admin logs in:

```
use Illuminate\Support\Facades\Log;

'hooks' => [
    'on_login' => function ($user, $log, $request) {
        if ($user->is_admin) {
            Log::info("Admin {$user->name} logged in from {$log->ip_address}");
        }
    },
],
```

---

#### 🚀 Example: Dispatch a Job

[](#-example-dispatch-a-job)

```
'hooks' => [
    'on_failed' => \App\Jobs\HandleFailedLogin::class,
],
```

> Your job should implement the \_\_invoke() method or a handle() method that receives the $user, $log, and optionally $request.

```
class HandleFailedLogin implements ShouldQueue
{
    public function handle($user, $log, $request)
    {
        // Block IP, alert security, log audit, etc.
    }
}
```

---

### 🔁 Hook Parameters

[](#-hook-parameters)

Each hook receives an array of three values, passed in the following order:

ParameterTypeDescription`$user``Illuminate\Contracts\Auth\Authenticatable`The user who triggered the event`$log``Xultech\AuthLogNotification\Models\AuthLog`The AuthLog instance that was just saved`$request``Illuminate\Http\Request`The Laravel Request object (IP, agent, etc.)If you’re using a closure or a class, make sure it accepts these arguments in the correct order:

```
function ($user, $log, $request) {
    // your logic here
}
```

---

#### 📦 How Laravel Resolves Your Hook

[](#-how-laravel-resolves-your-hook)

When you pass a class name to a hook (like a job or listener), the package will resolve it using Laravel’s service container:

```
App::make(YourHookClass::class)->__invoke($user, $log, $request);
```

This means:

- ✅ Laravel will automatically **instantiate the class**
- ✅ Any constructor dependencies (e.g., services, config, logger) will be **injected**
- ✅ You don’t have to call `new ClassName(...)` manually

For example, this works perfectly:

```
class NotifySecurityTeam
{
    public function __construct(LoggerInterface $logger)
    {
        $this->logger = $logger;
    }

    public function __invoke($user, $log, $request)
    {
        $this->logger->info("User {$user->email} logged in from suspicious IP.");
    }
}
```

### ✅ Supported Hook Events

[](#-supported-hook-events)

Hook KeyTriggered When`on_login`After a successful login`on_logout`When a user logs out`on_failed`After a failed login attempt---

🚨 Suspicious Login Detection
----------------------------

[](#-suspicious-login-detection)

This package includes built-in support for detecting suspicious login activity. It helps identify unusual behavior and protects user accounts by flagging logins from unfamiliar devices or locations.

---

### 🧠 What Counts as Suspicious?

[](#-what-counts-as-suspicious)

By default, a login is considered suspicious if it matches **either** of the following:

- The login comes from a **new device** (based on user agent/device metadata)
- The login comes from a **new location** (based on IP address or geolocation)

These rules are configurable in `config/authlog.php`:

```
'suspicion_rules' => [
    'new_device' => true,
    'new_location' => true,
    'block_suspicious_logins' => false,
],
```

### ⚙️ How It Works

[](#️-how-it-works)

When a user logs in:

1. The system compares the current device and location against previously seen records for the user.
2. If either is different **and enabled** in the config, the login is marked as suspicious.
3. The `AuthLog` record is saved with:

```
'is_new_device'   => true,
'is_new_location' => true,
```

4. You can act on this using:

- Notifications
- Custom hooks
- Blocking logic
- Admin alerts

### 📩 Notify on Suspicious Activity Only

[](#-notify-on-suspicious-activity-only)

To notify users only when a login is suspicious, update this in authlog.php:

```
'notification' => [
    'only_on_suspicious_activity' => true,
]
```

If set to `false`, users will be notified on every login, not just suspicious ones.

### 🔐 Block Suspicious Logins (Optional)

[](#-block-suspicious-logins-optional)

You can take it a step further and prevent suspicious logins entirely by enabling:

```
'block_suspicious_logins' => true,
```

When this is enabled and a suspicious login is detected, the login process can be aborted based on your custom handler.

### 🧩 Custom Handler

[](#-custom-handler)

If you're using custom logic to handle suspicious logins (e.g., verification steps or two-factor prompts), you can specify your own handler class:

```
'suspicious_login_handler' => \App\Handlers\MySuspiciousLoginHandler::class,
```

Your handler class should implement a `handle(Request $request): Response` method. You can use this to:

> Your custom handler should return a `Symfony\Component\HttpFoundation\Response`.

- Return a custom response (JSON, HTML, redirect)
- Trigger extra verification steps
- Log or report the attempt
- Notify administrators
- Abort the login process with a custom message

### ⚙️ Default Behavior

[](#️-default-behavior)

If you don’t provide a custom handler, the package uses a default handler:

```
\Xultech\AuthLogNotification\Handlers\SuspiciousLoginHandler::class
```

It returns a 403 JSON response:

```
{
  "message": "Login blocked due to suspicious activity."
}
```

> Suspicious login detection and blocking is a powerful, zero-config enhancement to your authentication system. Combined with notifications, hooks, and session tracking, it gives your app a strong layer of security intelligence.

---

🔄 Event Listeners
-----------------

[](#-event-listeners)

This package automatically listens to key authentication-related events and logs them as `AuthLog` entries.

Each event captures device metadata, location, IP, user agent, timestamp, and more. You can also hook into each event to run your own custom logic.

### 🗂️ Supported Events & Their Listeners

[](#️-supported-events--their-listeners)

EventListener ClassDescription`Login``LoginEventListener`Logs successful login, detects suspicious login, sends notification, and triggers hook`Logout``LogoutEventListener`Updates the logout timestamp on the last login session`Failed``FailedLoginEventListener`Logs failed login attempt and triggers rate limiter`PasswordReset``PasswordResetEventListener`Logs password reset activity and triggers hook`ReAuthenticated` *(custom)*`ReAuthenticatedEventListener`Logs re-authentication (e.g., password confirm)### ✅ What Gets Logged

[](#-what-gets-logged)

Each event logs the following data into the `auth_logs` table:

- IP address
- City, country, and location (via GeoIP)
- Device, browser, platform
- Whether it's a mobile device
- Referrer URL
- User agent
- Event type (login, logout, failed, etc.)
- Timestamp (`login_at` or `logout_at`)
- Session ID (if enabled)

### 🧩 Hook Support for Each Event

[](#-hook-support-for-each-event)

You can define custom logic for each of these in your config:

```
'hooks' => [
    'on_login' => ...,
    'on_logout' => ...,
    'on_failed' => ...,
    'on_password_reset' => ...,
    'on_re_authenticated' => ...,
],
```

---

🚫 Rate Limiting & Lockouts
------------------------------

[](#-rate-limiting--lockouts)

This package provides a built-in mechanism to track failed login attempts and lock out users after too many failures.

It helps protect your application against brute-force attacks and abusive login behavior, using a customizable and developer-friendly configuration.

### 🔧 Configuration

[](#-configuration-1)

In your `config/authlog.php`, the lockout settings are found under the `lockout` key:

```
'lockout' => [
    'enabled' => true,
    'key_prefix' => 'authlog:lockout:',
    'max_attempts' => 5,
    'lockout_minutes' => 10,
    'track_by' => 'ip', // Options: 'ip', 'email', 'both'
    'generic_response' => true,
    'redirect_to' => '/login',
],
```

### 🛠️ How It Works

[](#️-how-it-works-1)

When a failed login event occurs, the system:

1. Tracks the failure using a unique key (based on IP, email, or both).
2. Increments a counter for that identifier.
3. If the number of failed attempts `exceeds max_attempts`, the user is locked out for the duration of `lockout_minutes`.
4. On subsequent login attempts, the login is blocked before authentication occurs.

### 🔌 Using the Middleware

[](#-using-the-middleware)

To enforce rate limiting before authentication, use the built-in middleware:

```
Route::post('/login', [LoginController::class, 'store'])
    ->middleware('authlog.enforce-lockout');
```

This checks the current identifier’s failure count before the login attempt is processed and blocks it if the lockout limit has been exceeded.

#### 💬 Customizing the Response

[](#-customizing-the-response)

If `generic_response` is true, the user will receive a plain message:

```
Too many login attempts. Please try again later.
```

If false, the system will redirect to the `redirect_to` URL (usually /login) to show your UI or error message.

---

🧱 Middleware Overview
---------------------

[](#-middleware-overview)

AuthLogNotification ships with several powerful middleware that can be used to secure your authentication flow, detect suspicious behavior, and block malicious requests before they reach your controllers.

These middleware are fully optional, but when enabled, they offer pre-authentication defense layers that can block bad actors early.

### ✅ Available Middleware

[](#-available-middleware)

MiddlewareAliasPurpose`EnforceLoginRateLimit``authlog.enforce-lockout`Blocks users with too many failed login attempts`BlockSuspiciousLoginAttempt``authlog.block-suspicious`Prevents login from new devices or locations (before authentication)`VerifySessionFingerprint``authlog.verify-session`Detects session hijacking and mismatched device fingerprintsThese middleware are registered and ready to use once you publish them and attach them to your routes.

### 📦 Publishing Middleware

[](#-publishing-middleware)

To copy the middleware classes into your Laravel app `(e.g., app/Http/Middleware/AuthLog/)`:

```
php artisan vendor:publish --provider="Xultech\AuthLogNotification\AuthLogNotificationServiceProvider" --tag="authlog-middleware"
```

After publishing, you can customize them as needed.

### 📌 Registering the Middleware Alias

[](#-registering-the-middleware-alias)

#### 🔹 For Laravel 10 and Below (Using Kernel.php)

[](#-for-laravel-10-and-below-using-kernelphp)

If you want to add aliases manually in your `App\Http\Kernel`:

```
protected $routeMiddleware = [
    // ...
    'authlog.enforce-lockout'   => \App\Http\Middleware\AuthLog\EnforceLoginRateLimit::class,
    'authlog.block-suspicious'  => \App\Http\Middleware\AuthLog\BlockSuspiciousLoginAttempt::class,
    'authlog.verify-session'    => \App\Http\Middleware\AuthLog\VerifySessionFingerprint::class,
];
```

> The package automatically registers the aliases if your app supports it (Laravel 7+), but manual registration is also fine.

#### 🔹 For Laravel 11+ and 12

[](#-for-laravel-11-and-12)

In Laravel 11 and 12, middlewares are no longer registered in `Kernel.php`. Instead, you can use them directly in your routes or register them globally in `bootstrap/app.php`.

##### 🏷️ Option 1: Apply Middleware Directly in Routes

[](#️-option-1-apply-middleware-directly-in-routes)

Since Laravel 11+ supports middleware discovery, you can use fully qualified class names directly in your routes:

```
use Xultech\AuthLogNotification\Http\Middleware\EnforceLoginRateLimit;
use Xultech\AuthLogNotification\Http\Middleware\BlockSuspiciousLoginAttempt;

Route::post('/login', LoginController::class)
    ->middleware([
        EnforceLoginRateLimit::class,
        BlockSuspiciousLoginAttempt::class,
    ]);
```

##### 🏷️ Option 2: Register Middleware in bootstrap/app.php

[](#️-option-2-register-middleware-in-bootstrapappphp)

If you want to use named aliases (like `authlog.block-suspicious`), manually register middleware in `bootstrap/app.php`:

```
->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'authlog.enforce-lockout' => \Xultech\AuthLogNotification\Http\Middleware\EnforceLoginRateLimit::class,
        'authlog.block-suspicious' => \Xultech\AuthLogNotification\Http\Middleware\BlockSuspiciousLoginAttempt::class,
        'authlog.verify-session' => \Xultech\AuthLogNotification\Http\Middleware\VerifySessionFingerprint::class,
    ]);
})
```

Now you can use the alias in routes:

```
Route::post('/login', [LoginController::class, 'store'])
    ->middleware(['authlog.block-suspicious']);
```

### 🏗️ Publishing Middleware (Optional)

[](#️-publishing-middleware-optional)

If you want to customize the middleware, you can publish them into your Laravel application:

```
php artisan vendor:publish --provider="Xultech\AuthLogNotification\AuthLogNotificationServiceProvider" --tag="authlog-middleware"
```

---

🧪 Blade Components
------------------

[](#-blade-components-1)

This package includes a set of pre-built Blade components to display useful login and session-related data on your frontend — like dashboards, profile pages, or admin panels.

These components help you quickly show login insights without writing extra code.

### 🔹 Available Components

[](#-available-components)

> You must add the `HasAuthLogs` trait to your model for these components to work.

ComponentUsageDescription```@component('authlog::last-login')`Shows the user's last login time and location```@component('authlog::recent-logins')`Shows the last 5 login entries (with flags)```@component('authlog::suspicious-alert')`Warning if last login was suspicious```@component('authlog::session-count')`Number of active sessions for the current user### 🛠 How to Publish Blade Components

[](#-how-to-publish-blade-components)

If you want to customize how these components look or behave, publish them to your app:

```
php artisan vendor:publish --provider="Xultech\AuthLogNotification\AuthLogNotificationServiceProvider" --tag="authlog-components"
```

This will copy them to:

```
resources/views/vendor/authlog/components/
```

> You can now edit the components like regular Blade templates.

🧼 Cleanup & Maintenance
---------------------------

[](#-cleanup--maintenance)

Over time, your `auth_logs` table can grow significantly. To help you manage storage and improve performance, this package includes Artisan commands for log cleanup and geo-location updates.

### 🧹 Clean Old Auth Logs

[](#-clean-old-auth-logs)

Remove logs older than the retention period (defined in `config/authlog.php`):

```
php artisan authlog:clean
```

> This command uses either soft or hard delete based on the `retention.delete_method` config.

#### ✅ Scheduling (Laravel 10 and below)

[](#-scheduling-laravel-10-and-below)

If you're using Laravel 10 or earlier, schedule this in `app/Console/Kernel.php`:

```
$schedule->command('authlog:clean')->daily();
```

#### ✅ Scheduling (Laravel 11+)

[](#-scheduling-laravel-11)

Use the new `routes/console.php` format:

```
use Illuminate\Support\Facades\Schedule;

Schedule::command('authlog:clean')->daily();
```

### 🧽 Prune Suspicious Logs

[](#-prune-suspicious-logs)

If you're storing a lot of logs marked as suspicious (e.g., `is_new_device or is_new_location`), and you no longer need them, run:

Laravel 10 and below:

```
$schedule->command('authlog:prune-suspicious')->weekly();
```

Laravel 11 and 12:

```
use Illuminate\Support\Facades\Schedule;

Schedule::command('authlog:prune-suspicious')->weekly();
```

### 🌍 Sync Geo-Location

[](#-sync-geo-location)

If your IP geolocation source has changed or some entries have missing location data, you can reprocess them using:

```
php artisan authlog:sync-location
```

> This will update all logs missing country, city, or location fields using your configured location service.

🧪 Testing
---------

[](#-testing)

This package includes built-in Pest tests to ensure its core components are working as expected. You can also write your own tests to validate behavior in your application.

### ✅ Requirements

[](#-requirements)

To run tests locally, make sure you have:

- PHP 8.0+
- Composer
- [Pest PHP](https://pestphp.com) installed globally or locally (installed via `dev` dependencies)

### 📦 Running Tests

[](#-running-tests)

To run the full test suite:

```
./vendor/bin/pest
```

Or, if Pest is installed globally:

```
pest
```

🤝 Contributing
--------------

[](#-contributing)

Thank you for considering contributing to `AuthLogNotification`! Your help is deeply appreciated.

Whether you're reporting a bug, suggesting a feature, or submitting a pull request — you’re making the package better for everyone.

### 🛠️ How to Contribute

[](#️-how-to-contribute)

1. **Fork** the repository.
2. **Clone** your fork: ```
    git clone https://github.com/Xultech-LTD/laravel-auth-log-notification.git
    cd auth-log-notification
    ```
3. Install dependencies and set up the test environment.
4. Create a new branch: ```
    git checkout -b feature/my-improvement
    ```
5. Write your changes and cover them with tests.
6. Run the test suite
7. Commit with a clear message ```
    git commit -m "feat: added XYZ support to login hook"
    ```
8. Push and open a Pull Request.

### ✅ Coding Guidelines

[](#-coding-guidelines)

- Follow **PSR-12** standards.
- Use meaningful variable and method names.
- Write **tests** for any new feature or fix.
- Keep pull requests **focused** and **descriptive**.
- Avoid breaking **backward compatibility** unless discussed.

### 📦 Testing Notes

[](#-testing-notes)

This package uses **Pest PHP** and includes a fully bootstrapped container to simulate a Laravel-like environment.
You can write **unit and feature tests** without needing a full Laravel app.

---

If you're unsure how to begin or where to contribute, feel free to [open an issue](https://github.com/Xultech-LTD/laravel-auth-log-notification/issues) and start the conversation.

> Let's build safer Laravel apps together.

🔐 Security
----------

[](#-security)

If you discover a vulnerability within this package, please **do not** report it publicly.

Instead, please send an email to  or open a private issue on the repository.

We take security seriously and will respond promptly.

### Responsible Disclosure

[](#responsible-disclosure)

We appreciate responsible security disclosures and will:

- Acknowledge your report.
- Investigate and fix valid issues quickly.
- Credit you (if desired) once resolved.

🛣️ Roadmap
----------

[](#️-roadmap)

Here are some planned and proposed features for future versions of this package:

- Core login/logout/failed event tracking
- Device & IP intelligence (suspicious login detection)
- Multi-channel notifications (Mail, Slack, SMS)
- Custom hooks for login lifecycle
- Session fingerprinting & hijack detection
- Rate limiting and lockout middleware
- Artisan commands for cleanup and geo sync
- Blade components for recent activity
- Middleware for pre-auth blocking
- Configuration-driven and extendable

### Planned:

[](#planned)

- Web UI for browsing logs
- Graphs & dashboard widgets (Jetstream/Livewire support)
- Admin review panel for suspicious events
- Custom log channel support
- First-party support for Fortify and Breeze
- Official Nova & Filament integrations
- Better localization support (i18n)
- Optional hashed user agents for privacy-sensitive apps
- Fine-grained control over notification triggers
- Export logs to CSV / external tools

> Want to see something else? Open an issue or submit a feature request!

📄 License
---------

[](#-license)

This package is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).

You are free to use, modify, and distribute it within the terms of the license. Contributions are welcome and encouraged.

📝 Changelog
-----------

[](#-changelog)

All notable changes to this project will be documented in this section.

This project follows [Semantic Versioning](https://semver.org/).

### \[v1.0.0\] - Initial Release

[](#v100---initial-release)

- ✅ Login, logout, and failed login tracking
- 🔐 Suspicious login detection (new device or location)
- 📣 Real-time notifications (Mail, Slack, SMS)
- 🧬 Session fingerprinting & hijack detection
- 🚫 Rate limiting with lockout support
- 🧩 Blade components for login/session insights
- 🛠️ Hooks & custom handlers
- 🗃️ Artisan commands for cleanup and geolocation sync
- 🧱 Fully documented and testable outside Laravel app

👥 Credits & Authors
-----------------------

[](#-credits--authors)

AuthLogNotification was crafted with care by [Michael Erastus](https://github.com/michaelerastus) under [XulTech](https://github.com/Xultech-LTD) as part of our mission to build secure and developer-friendly Laravel tools.

### Core Maintainer

[](#core-maintainer)

- **Michael Erastus** – [GitHub](https://github.com/michaelerastus)

### Contributors

[](#contributors)

Special thanks to everyone who provided feedback, reported issues, or helped shape the direction of this package. Your support makes open source better.

---

If you find this package helpful, consider giving it a ⭐️ on GitHub or sharing it with others in the Laravel community.

For contributions, ideas, or collaborations, feel free to reach out!

### ⚠️ Disclaimer

[](#️-disclaimer)

This package is provided as-is and is intended to **enhance security awareness** around authentication activity. While it offers advanced features such as suspicious login detection, session tracking, and brute-force protection, it **does not guarantee absolute security**.

You are responsible for ensuring that your Laravel application adheres to best practices, including:

- Keeping dependencies up to date
- Using secure authentication flows
- Regularly auditing and reviewing security configurations
- Complying with data protection regulations (e.g., GDPR)

By using this package, you acknowledge that:

- The authors and contributors are **not liable** for any security breaches, data loss, or misuse of the package.
- You should **review and test all features** before deploying them to production environments.

Use this package at your own discretion and always in conjunction with your existing security policies.

###  Health Score

34

—

LowBetter than 75% of packages

Maintenance54

Moderate activity, may be stable

Popularity11

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 96.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

10

Last Release

466d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/f82ce04d410838ee2e2c88b4443d5c00c5af84c829dafd01c1cbbb0e90700bdd?d=identicon)[xultech](/maintainers/xultech)

---

Top Contributors

[![michaelerastus](https://avatars.githubusercontent.com/u/33043109?v=4)](https://github.com/michaelerastus "michaelerastus (49 commits)")[![officialmeritinfos](https://avatars.githubusercontent.com/u/87044411?v=4)](https://github.com/officialmeritinfos "officialmeritinfos (2 commits)")

---

Tags

auth-logsauthenticationauthentication-logbrute-force-protectiondetect-loginslaravellaravel-packagelogin-logslogin-tracking

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/xultech-auth-log-notification/health.svg)

```
[![Health](https://phpackages.com/badges/xultech-auth-log-notification/health.svg)](https://phpackages.com/packages/xultech-auth-log-notification)
```

###  Alternatives

[directorytree/ldaprecord-laravel

LDAP Authentication & Management for Laravel.

5752.3M18](/packages/directorytree-ldaprecord-laravel)[illuminate/auth

The Illuminate Auth package.

10528.2M1.2k](/packages/illuminate-auth)[flarum/core

Delightfully simple forum software.

201.4M2.3k](/packages/flarum-core)[masterix21/laravel-licensing

Laravel licensing package with polymorphic assignment to any model, activation keys, expirations/renewals, and seat control via LicenseUsage. Supports offline verification with public-key–signed tokens, a CLI to generate/rotate/revoke keys, and an extensible architecture via config and contracts.

1563.0k4](/packages/masterix21-laravel-licensing)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)