README

A lightweight Laravel package to record, monitor, and manage API user journeys with a beautiful admin dashboard. Automatically tracks HTTP requests, extracts user information from Bearer tokens, and provides comprehensive logging with a clean web interface.

✨ Features

🚀 Automatic Request Logging: Captures all HTTP requests with response times, status codes, headers, and payloads
👤 Smart User Tracking: Automatically extracts user IDs from Bearer tokens (Sanctum/Passport support)
🎯 Custom Event Tracking: Log custom application events with structured data
🔒 Security First: Automatically masks sensitive fields (passwords, tokens, credit cards, etc.)
📊 Beautiful Admin Dashboard: Clean, responsive web interface with Bootstrap styling
🧹 Intelligent Data Management: Built-in cleanup commands with flexible retention policies
⚡ Performance Optimized: Asynchronous logging in production, database indexing
🔍 Advanced Filtering: Filter logs by method, status, user, date range, endpoints, and more
📱 Mobile Friendly: Responsive dashboard design works on all devices
🎨 Highly Customizable: Extensive configuration options for different environments

📋 Requirements

PHP 8.1 or higher
Laravel 9.0, 10.0, 11.0, or 12.0
MySQL, PostgreSQL, or SQLite database

🚀 Installation

1. Install the Package

composer require rahban/laravel-logbook

2. Publish Configuration and Migrations

Publish the configuration file:

php artisan vendor:publish --tag=logbook-config

Publish and run the migrations:

php artisan vendor:publish --tag=logbook-migrations
php artisan migrate

3. Optional: Publish Views and Assets

Customize the admin dashboard views:

php artisan vendor:publish --tag=logbook-views

Publish frontend assets:

php artisan vendor:publish --tag=logbook-assets

All-in-one publishing:

php artisan vendor:publish --provider="Rahban\LaravelLogbook\Providers\LogbookServiceProvider"

⚙️ Configuration

Environment Variables

Add these variables to your .env file:

LOGBOOK_ENABLED=true
LOGBOOK_UI_ENABLED=true
LOGBOOK_UI_PREFIX=logbook
LOGBOOK_USER=admin
LOGBOOK_PASS=your_secure_password
LOGBOOK_RETENTION_DAYS=90
LOGBOOK_LOG_REQUEST_START=true
LOGBOOK_EXTRACT_USER_FROM_TOKEN=true

Add Middleware

Option A: Global Middleware (Recommended for APIs)

Add to app/Http/Kernel.php:

protected $middleware = [
    // ...existing middleware...
    \Rahban\LaravelLogbook\Http\Middleware\LogbookMiddleware::class,
];

Option B: Route-specific Middleware

Apply to specific routes:

// In routes/api.php or routes/web.php
Route::middleware(['logbook'])->group(function () {
    Route::get('/api/users', [UserController::class, 'index']);
    Route::post('/api/orders', [OrderController::class, 'store']);
    // ...other routes
});

🎯 Usage

Automatic Request Logging

Once the middleware is installed, all HTTP requests are automatically logged with:

Request method, URL, headers, and payload
Response status, headers, and body
Response time in milliseconds
User ID automatically extracted from Bearer tokens
IP address and user agent
Route information and middleware stack

Bearer Token & User Tracking

The package automatically extracts user IDs from Bearer tokens:

// Your API request with Authorization header:
// Authorization: Bearer abc123def456...

// Logbook automatically:
// 1. Extracts user ID from the token (if using Sanctum/Passport)
// 2. Logs the request with user association
// 3. Masks the token for security (shows: "abc123de***")

Custom Event Logging

Log custom business events throughout your application:

use Rahban\LaravelLogbook\Facades\Logbook;

// Log user actions
Logbook::event('user.login', [
    'email' => $user->email,
    'ip' => request()->ip(),
    'login_method' => 'email',
], $user->id);

// Log business events
Logbook::event('order.created', [
    'order_id' => $order->id,
    'amount' => $order->total,
    'currency' => 'USD',
    'payment_method' => 'credit_card',
], $order->user_id);

// Log system events
Logbook::event('email.sent', [
    'template' => 'welcome',
    'recipient' => $user->email,
    'status' => 'delivered',
]);

Using with User Models

Add the trait to your User model for convenient logging:

use Rahban\LaravelLogbook\Traits\HasLogbook;

class User extends Authenticatable
{
    use HasLogbook;

    // Now you can use:
    public function login()
    {
        $this->logLogin(['device' => 'mobile']);
        // Automatically logs user.login event
    }

    public function updateProfile()
    {
        $this->logAction('profile_updated', [
            'fields' => ['name', 'email']
        ]);
    }

    public function logout()
    {
        $this->logLogout();
        // Automatically logs user.logout event
    }
}

Service Injection

Use dependency injection in your controllers:

use Rahban\LaravelLogbook\Services\LogbookService;

class OrderController extends Controller
{
    public function store(Request $request, LogbookService $logbook)
    {
        $order = Order::create($request->all());

        // Log the business event
        $logbook->event('order.created', [
            'order_id' => $order->id,
            'amount' => $order->total,
            'items_count' => $order->items->count(),
        ], auth()->id());

        return response()->json($order);
    }
}

📊 Admin Dashboard

Access the Dashboard

Visit: http://your-app.com/logbook

Default credentials:

Username: admin
Password: your_secure_password (from .env)

Dashboard Features

📈 Overview Page

Total requests and custom events count
Error rate percentage and average response time
Status code distribution (2xx, 3xx, 4xx, 5xx)
Recent activity timeline
Top endpoints by request count

📋 Request Tracks

Paginated list of all logged requests
Advanced filtering:
- HTTP method (GET, POST, PUT, DELETE)
- Status code ranges
- User ID
- Date range picker
- Endpoint search
- Response time ranges

🔍 Entry Details

Complete request/response inspection
Formatted JSON viewer
Headers analysis
Performance metrics
User information (if authenticated)
Route and middleware details

🧹 Management Panel

Storage statistics: Total entries, storage size, old entries count
Cleanup operations:
- Clean by days (older than X days)
- Clean by date range
- Clean all data (with confirmation)
Real-time statistics: Error rates, performance metrics

🛠️ Artisan Commands

Cleanup Commands

# Clean logs older than default retention period (90 days)
php artisan logbook:cleanup

# Clean logs older than specific days
php artisan logbook:cleanup --days=30

# Clean logs by date range
php artisan logbook:cleanup --from=2024-01-01 --to=2024-12-31

# Delete all logs (use with caution!)
php artisan logbook:cleanup --all --force

# Preview what would be deleted (dry run)
php artisan logbook:cleanup --days=90 --dry-run

Scheduled Cleanup

Add automatic cleanup to your app/Console/Kernel.php:

protected function schedule(Schedule $schedule)
{
    // Clean old logs daily at 2 AM
    $schedule->command('logbook:cleanup --force')
             ->daily()
             ->at('02:00');

    // Weekly cleanup with custom retention
    $schedule->command('logbook:cleanup --days=30 --force')
             ->weekly()
             ->sundays()
             ->at('03:00');
}

⚙️ Advanced Configuration

The configuration file config/logbook.php provides extensive customization:

return [
    // Enable/disable logging
    'enabled' => env('LOGBOOK_ENABLED', true),

    // Admin UI settings
    'ui_enabled' => env('LOGBOOK_UI_ENABLED', true),
    'ui_route_prefix' => env('LOGBOOK_UI_PREFIX', 'logbook'),

    // Authentication
    'auth_user' => env('LOGBOOK_USER', 'admin'),
    'auth_pass' => env('LOGBOOK_PASS', 'password'),

    // Data retention
    'retention_days' => env('LOGBOOK_RETENTION_DAYS', 90),

    // Security - fields to automatically mask
    'mask_fields' => [
        'password', 'password_confirmation', 'token', 'api_key',
        'secret', 'access_token', 'refresh_token', 'credit_card',
        'ssn', 'cvv',
    ],

    // Body size limit (10KB default)
    'truncate_body_at' => env('LOGBOOK_TRUNCATE_AT', 10240),

    // Routes to exclude from logging
    'excluded_routes' => [
        'logbook/*', 'telescope/*', '_debugbar/*', 'health-check',
    ],

    // Token extraction settings
    'extract_user_from_token' => env('LOGBOOK_EXTRACT_USER_FROM_TOKEN', true),
    'log_request_start' => env('LOGBOOK_LOG_REQUEST_START', true),

    // Performance settings
    'async_logging' => env('LOGBOOK_ASYNC_LOGGING', app()->environment('production')),
    'queue_connection' => env('LOGBOOK_QUEUE_CONNECTION', 'default'),
];

🔒 Security Features

Automatic Data Masking

Sensitive fields are automatically masked in request/response bodies:

Passwords and password confirmations
API keys and access tokens
Credit card numbers and CVV codes
Social security numbers
Custom sensitive fields (configurable)

Header Sanitization

Authorization headers and cookies are automatically sanitized:

// Original: Authorization: Bearer abc123def456ghi789
// Logged:   Authorization: Bearer abc123de***

Admin Panel Protection

Basic HTTP authentication
CSRF protection on all management operations
Session-based authentication
Configurable credentials via environment variables

📈 Performance Considerations

Production Optimizations

Asynchronous logging in production environments
Database indexing for optimal query performance
Body truncation to prevent large data storage
Configurable retention policies for automated cleanup

Memory Management

Efficient data processing with minimal memory footprint
Stream-based body processing for large requests
Automatic garbage collection of old entries

Scalability

Supports horizontal scaling with shared database
Queue-based processing for high-traffic applications
Configurable database connections for separation

🧪 Testing

Run Package Tests

# Run all tests
composer test

# Run with coverage
composer test-coverage

# Run specific test
vendor/bin/phpunit --filter=test_middleware_logs_requests

Test Coverage

The package includes comprehensive tests covering:

Custom event logging
Request/response logging
User ID extraction from tokens
Data masking and security
Cleanup commands
Statistics calculation

🔧 Troubleshooting

Common Issues

SQLite Driver Missing (for testing):

sudo apt-get install php8.3-sqlite3

Permission Issues:

php artisan config:cache
php artisan route:cache

Large Log Files:

php artisan logbook:cleanup --days=7 --force

Debug Mode

Enable debug logging in your .env:

LOGBOOK_ENABLED=true
LOG_LEVEL=debug

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

Fork the repository
Clone your fork: git clone https://github.com/yourusername/laravel-logbook.git
Install dependencies: composer install
Run tests: composer test
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Run tests: composer test
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
Open a Pull Request

📜 License

This package is open-sourced software licensed under the MIT license.

🙏 Support

🐛 Bug Reports: Create an issue
💡 Feature Requests: Create an issue
📖 Documentation: Check our Wiki
⭐ Star the repository if you find it useful
🗣️ Share with fellow developers

📞 Contact

Author: Muhammad Rahban
Email: muhammadrahban@example.com
GitHub: @rahban
LinkedIn: Muhammad Rahban

Made with ❤️ by Muhammad Rahban

Laravel Logbook - Track Every Journey

rahban / laravel-logbook

Package info

Security

Statistics