README

Laravel Forge Logs

A Laravel package that integrates with the Laravel Forge API to fetch and manage application logs (laravel and nginx) from your Forge-managed sites. Simplify log retrieval and monitoring with interactive CLI commands.

Why this package

With the use of AI, it is increasingly necessary to access logs remotely to speed up bug fixing.

Features

• Interactive setup wizard to configure your Forge organization, server, and site
• Fetch application logs directly from Laravel Forge
• Fetch nginx access logs from Laravel Forge
• Fetch nginx error logs from Laravel Forge
• Customizable log file paths and filenames
• Store logs locally for analysis
• Simple artisan commands for easy integration

Requirements

• PHP 8.4+
• Laravel 11.x or 12.x

Installation

You can install the package via Composer:

composer require frankflow/laravel-forge-logs --dev

Get Your Laravel Forge API Token

First, obtain your API token from Laravel Forge:

1. Log in to Laravel Forge
2. Go to your account settings
3. Navigate to the API section
4. Generate a new API token (make sure you set the right scopes for the token)

Add Your Forge Token to .env

Add the following line to your .env file:

FORGE_TOKEN=your-forge-api-token-here

Run the Interactive Setup

Run the initialization command to configure your organization, server, and site:

php artisan forge-init

This interactive command will:

1. Fetch and display your available Forge organizations

2. Fetch and display servers for the selected organization

3. Allow you to search and select your site

4. Automatically update your .env file with the configuration

USAGE: Fetching Logs

Once configured, you can fetch different types of logs:

Fetch All Logs (Recommended)

php artisan forge-fetch-logs
# or
php artisan forge-all-logs

This command will fetch Laravel application logs, Nginx access logs, and Nginx error logs in sequence.

Fetch Individual Logs

Application Logs

php artisan forge-laravel-logs

Saves to storage/logs/laravel.log (customizable in config).

Nginx Access Logs

php artisan forge-nginx-access-logs

Saves to storage/logs/nginx/access.log (customizable in config).

Nginx Error Logs

php artisan forge-nginx-error-logs

Saves to storage/logs/nginx/error.log (customizable in config).

Delete Site Logs

php artisan forge-delete-logs

Interactively deletes logs on the configured site via the Forge API. The command presents a menu to select which logs to delete:

Options:

Skip the confirmation prompt with --force:

php artisan forge-delete-logs --force

⚠️ Warning: Log deletion is permanent and cannot be undone.

[Optional] Publishing Configuration

Publish the configuration file:

php artisan vendor:publish --tag="forge-logs-config"

This will create a config/forge-logs.php file with the following structure:

return [
    'forge_token' => env('FORGE_TOKEN'),
    'forge_server_id' => env('FORGE_SERVER_ID'),
    'forge_site_id' => env('FORGE_SITE_ID'),
    'forge_organization' => env('FORGE_ORGANIZATION'),

    // Customize log file paths (relative to storage_path())
    'log_paths' => [
        'laravel' => 'logs/laravel.log',
        'nginx_access' => 'logs/nginx/access.log',
        'nginx_error' => 'logs/nginx/error.log',
    ],
];

Customizing Log File Paths

You can customize where the logs are saved by modifying the log_paths array in config/forge-logs.php:

'log_paths' => [
    'laravel' => 'logs/forge/laravel.log',           // Change path
    'nginx_access' => 'logs/forge/nginx-access.log', // Change path and filename
    'nginx_error' => 'logs/forge/nginx-error.log',   // Change path and filename
],

All paths are relative to the storage_path() directory.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• FrankFlow
• All Contributors

License

The MIT License (MIT). Please see License File for more information.