Log Viewer

Once installed, Log Viewer is accessible via your browser at the following default URL:

{APP_URL}/log-viewer

(e.g., https://my-app.test/log-viewer)

Install the Log Viewer package via Composer and then publish the front-end assets to complete the setup.

Requirements

• PHP 8.0+
• Laravel 8+

composer require opcodesio/log-viewer

php artisan log-viewer:publish

You can publish the Log Viewer configuration file and its Blade views to your application's config and resources directories to customize their behavior and appearance. Use the following Artisan commands:

To publish the configuration: php artisan vendor:publish --tag="log-viewer-config"

To publish the views: php artisan vendor:publish --tag="log-viewer-views"

If your logs are not appearing in the Log Viewer UI, check the following:

1. Log Format: Ensure your log follows a supported format. If you use a custom format, you must define a custom log parser.
2. File Permissions: The web process running Log Viewer must have permission to read the log files. For example, if reading Apache logs in /var/log/httpd, the apache or httpd user must have read access via file ACLs.

To ensure frontend requests are treated as stateful (allowing sessions, cookies, and CSRF protection), you must define which domains are considered first-party.

Log Viewer resolves stateful domains using the following priority:

1. The log-viewer.api_stateful_domains configuration key.
2. The sanctum.stateful configuration key (if using Laravel Sanctum).
3. Default local domains (e.g., localhost, 127.0.0.1) and the current APP_URL.

If APP_URL is not configured, the middleware falls back to allowing same-domain requests based on the referer or origin headers.

The LogFolder identifier (used for routing and downloads) can be influenced by the log-viewer.exclude_ip_from_identifiers configuration setting.

• If false (default): The identifier is a short MD5 hash of the local IP address concatenated with the path.
• If true: The identifier is a short MD5 hash of the path only.

The Log Viewer routes are controlled via the log-viewer configuration file. You can customize the following settings:

• route_path: The URL prefix for the web interface.
• route_domain: A specific domain to host the Log Viewer on.
• middleware: Middleware applied to the web routes.
• api_middleware: Middleware applied to the API routes (which are prefixed with {route_path}/api).

Note: The package automatically prepends EnsureFrontendRequestsAreStateful to the middleware priority to ensure compatibility with stateful frontend requests.

To support custom log formats in the Log Viewer UI, you can extend the Opcodes\LogViewer\Logs\Log class. You must define static properties to tell the parser how to interpret the log text and how to display the data in the frontend.

Key properties to override:

• $name: The human-readable name for the log type.
• $levelClass: A class implementing Opcodes\LogViewer\LogLevels\LevelInterface to handle severity levels.
• $regex: A regular expression with named capture groups to extract data.
• $regexDatetimeKey, $regexLevelKey, $regexMessageKey: The names of the capture groups in your regex.
• $columns: An array defining the frontend table columns, mapping label to the data_path extracted by your regex.

Once a Log instance is created, you can access the parsed data using the following methods:

• getTimestamp(): Returns the integer timestamp of the log entry (defaults to 0 if no datetime is found).
• getLevel(): Returns an instance of the severity level (via the configured $levelClass).
• getOriginalText(): Returns the raw, unparsed log line.
• url(): Returns the URL to view this specific log entry in the Log Viewer UI.

The MultipleLogReader class allows you to perform unified operations across a collection of LogFile objects. You can filter by log levels, search for specific queries, set the reading direction, and paginate through results across all files in the collection.

Key features include:

• Directional reading: Use forward() or reverse() to control the order of logs.
• Filtering: Use exceptLevels() to exclude specific log levels or search() to filter by a query string.
• Pagination: Use paginate() to return a LengthAwarePaginator for large datasets.
• Scanning: Use scan() to ensure log files are indexed/scanned for new content.