Skip to content

RELEASE_NOTES.md

Latest commit

 

History

History
331 lines (241 loc) · 12 KB

RELEASE_NOTES.md

File metadata and controls

331 lines (241 loc) · 12 KB

Laravel Authentication Log Release Notes

v6.1.0 Release Notes

🚀 Laravel 13 Support & Immutable Date Compatibility

Released 2026-06-10.

  • Laravel 13.x support (#140) — the package and CI matrix now cover PHP 8.2–8.4 on Laravel 11.x, 12.x, and 13.x
  • Immutable date casting compatibility (#137) — lastLoginAt(), lastSuccessfulLoginAt(), and previousLoginAt() now return \Carbon\CarbonInterface instead of \Illuminate\Support\Carbon, fixing a TypeError in applications that cast model dates to CarbonImmutable (the default in current Laravel starter kits)
  • PHP 8.2+ now required — PHP 8.1 is EOL and was never installable alongside Laravel 11+, so this does not affect any working installation

No database changes or migrations are required when upgrading from v6.0.x.

v6.0.0 Release Notes

🎉 Major Release - Enhanced Features & Modernization

This is a major release that modernizes the package for Laravel 11.x and 12.x, adds numerous new features, and fixes several long-standing issues.

⚠️ Breaking Changes

  • Laravel 10.x support dropped: This package now only supports Laravel 11.x and 12.x (Laravel 12 support was added in v5.0.0)
  • PHP 8.1+ required: Minimum PHP version is now 8.1
  • Database migration required: Existing installations must run the upgrade migration to add new columns

🚀 New Features

1. Suspicious Activity Detection

Automatically detect and flag suspicious login patterns including:

  • Multiple failed login attempts
  • Rapid location changes
  • Unusual login times (configurable)

Configuration:

'suspicious' => [
    'failed_login_threshold' => 5,
    'check_unusual_times' => false,
    'usual_hours' => [9, 10, 11, 12, 13, 14, 15, 16, 17],
],

2. Session Management

Comprehensive session management capabilities:

  • View active sessions
  • Revoke specific sessions
  • Revoke all other sessions (keep current device)
  • Revoke all sessions
  • Track last activity timestamp

Usage:

$user->getActiveSessions();
$user->revokeSession($sessionId);
$user->revokeAllOtherSessions($currentDeviceId);
$user->revokeAllSessions();

3. Device Fingerprinting & Management

  • Unique device identification (normalized user agent to prevent false positives)
  • Device trust management
  • Device naming
  • Browser version normalization (prevents false "new device" notifications)

Usage:

$user->getDevices();
$user->trustDevice($deviceId);
$user->untrustDevice($deviceId);
$user->isDeviceTrusted($deviceId);

4. Query Scopes

Powerful query scopes for filtering authentication logs:

  • successful() - Only successful logins
  • failed() - Only failed attempts
  • fromIp($ip) - Filter by IP address
  • recent($hours) - Recent logs
  • suspicious() - Suspicious activities
  • trusted() - Trusted devices only
  • fromDevice($deviceId) - Specific device
  • forUser($user) - Specific user
  • active() - Active sessions

Usage:

AuthenticationLog::suspicious()->recent(24)->get();
$user->authentications()->failed()->recent(1)->count();

5. Statistics & Insights

Get authentication statistics for users:

  • Total logins count
  • Failed attempts count
  • Unique devices count
  • Suspicious activities count
  • Comprehensive login stats array

Usage:

$stats = $user->getLoginStats();
$totalLogins = $user->getTotalLogins();
$failedAttempts = $user->getFailedAttempts();
$uniqueDevices = $user->getUniqueDevicesCount();

6. Rate Limiting for Notifications

Prevent notification spam with configurable rate limiting:

  • Configurable max attempts per time period
  • Separate limits for new device and failed login notifications
  • Automatic rate limit decay

Configuration:

'new-device' => [
    'rate_limit' => 3,
    'rate_limit_decay' => 60, // minutes
],

7. Middleware for Device Trust

Restrict access to trusted devices only:

Usage:

Route::middleware(['auth', \Rappasoft\LaravelAuthenticationLog\Middleware\RequireTrustedDevice::class])
    ->group(function () {
        // Protected routes
    });

8. Export Functionality

Export authentication logs to CSV or JSON:

Usage:

php artisan authentication-log:export --format=csv --path=storage/app/logs.csv
php artisan authentication-log:export --format=json

9. Webhook Support

Send webhooks for authentication events:

  • Login events
  • Failed login events
  • New device events
  • Suspicious activity events

Configuration:

'webhooks' => [
    [
        'url' => 'https://example.com/webhook',
        'events' => ['login', 'failed', 'new_device', 'suspicious'],
        'headers' => [
            'Authorization' => 'Bearer your-token',
        ],
    ],
],

10. Enhanced Notifications

  • Support for Vonage (formerly Nexmo) SMS notifications
  • Custom notification templates
  • Improved email templates with better error handling

11. Configurable New User Threshold

Prevent false positives for new users connecting from multiple devices/locations:

Configuration:

'new-device' => [
    'new_user_threshold_minutes' => 1, // Default: 1 minute
],

12. Session Restoration Prevention

Fixes #13

Automatically prevents session restorations (page refreshes, remember me cookies) from creating duplicate log entries. Updates last_activity_at instead of creating new entries.

Configuration:

'prevent_session_restoration_logging' => true,
'session_restoration_window_minutes' => 5,

🐛 Bug Fixes

Fixed Issue #40 - Browser Version Updates Triggering False Notifications

Fixes #40

Browser version updates (e.g., Safari 14.1.2 → 15.1) no longer trigger false "new device" notifications. Device fingerprinting now normalizes user agent strings by removing version numbers.

Fixed Issue #13 - Session Restoration Logging

Fixes #13

Session restorations (page refreshes, remember me cookies) no longer create duplicate log entries. The package now detects and handles session restorations automatically.

Fixed Issue #48, #87, #111 - SQL Server Duplicate ORDER BY Error

Fixes #48, #87, #111

Fixed SQL Server error "A column has been specified more than once in the order by list" by removing duplicate orderByDesc('login_at') calls. The authentications() relationship already orders by login_at DESC, so additional ordering was unnecessary.

Fixed Issue #33, #58 - Model Exception for Models Without Trait

Fixes #33, #58

All listeners now check if the authenticatable model implements the AuthenticationLoggable trait before processing, preventing BadMethodCallException errors when using multiple authenticatable models where only some have the trait.

Fixed Issue #82 - Duplicate Log Entries

Fixes #82

Duplicate log entries issue resolved by session restoration prevention (same fix as Issue #13).

✅ Pull Requests Implemented

PR #15 - Notification After Failed Login on New Device

Closes #15

The package now sends new device notifications when a successful login occurs after a failed login attempt on an unknown device.

PR #52 - Optimize Other Devices Logout Listener

Closes #52

Already implemented. The listener filters to only active sessions using whereNull('logout_at').

PR #57 - Use Null Safe/Chaining Operator

Closes #57

Already implemented. The codebase uses null-safe operators (?->) instead of optional().

PR #80 - Added PHPDocs for IDE Autocompletion

Closes #80

Already implemented. The AuthenticationLog model includes PHPDoc comments for all properties including new fields.

PR #85 - Configurable New User Threshold

Closes #85

Added new_user_threshold_minutes configuration option to reduce false positives for users connecting from multiple devices/locations shortly after registration.

PR #92 - Configurable Listeners

Closes #92

Already implemented. The config file includes configurable listeners for all authentication events.

PR #94 - Check Trait Implementation

Closes #94

Already implemented. All listeners check if the user model implements the AuthenticationLoggable trait before processing.

PR #100 - Laravel 11 Support

Closes #100

Package now supports Laravel 11.x and 12.x.

PR #115 - Check if GeoIP is Installed

Closes #115

Config defaults now check if geoip function exists before enabling location tracking, preventing errors when the geoip package is not installed.

PR #120 - Laravel 12 Support & Arabic Translation

Closes #120

Laravel 12 support added and Arabic translation (ar.json) included.

PR #125 - Test Configuration Updates

Closes #125

Test configuration updated for Laravel 11+ support.

PR #127 - Spanish Translation & Blade Fixes

Closes #127

Spanish translation (es_ES.json) exists and blade templates use the null coalescing operator (??) for state/country fields.

📝 Pull Requests No Longer Applicable

PR #70 - Laravel 10 Support

Closes #70

No longer applicable. Package v4.0.0 dropped Laravel 10 support and now only supports Laravel 11.x and 12.x.

📚 Documentation

  • Comprehensive upgrade guide added
  • All new features documented
  • Configuration examples updated
  • Usage examples for all new features

🧪 Testing

  • 76 tests passing (146 assertions)
  • Comprehensive test coverage for all new features
  • Tests for session restoration prevention
  • Tests for device fingerprinting normalization
  • Tests for suspicious activity detection
  • Tests for all query scopes and statistics

📦 Installation & Upgrade

New Installation

composer require rappasoft/laravel-authentication-log
php artisan vendor:publish --provider="Rappasoft\LaravelAuthenticationLog\LaravelAuthenticationLogServiceProvider"
php artisan migrate

Upgrading from v5.x or Earlier

composer update rappasoft/laravel-authentication-log
php artisan vendor:publish --provider="Rappasoft\LaravelAuthenticationLog\LaravelAuthenticationLogServiceProvider" --tag="authentication-log-migrations"
php artisan migrate

The upgrade migration will safely add new columns to your existing authentication_log table without data loss.

🙏 Credits

Thank you to all contributors who submitted issues, pull requests, and feedback that made this release possible!

📖 Full Documentation

See the documentation for complete usage instructions and examples.

Note: This release includes breaking changes. Please review the upgrade guide before upgrading from v5.x or earlier.