Getting Started

Minimal Setup

Installation:
```
composer require opcodesio/log-viewer
php artisan log-viewer:publish
```
- Publishes assets and config files to resources/views/vendor/log-viewer and config/log-viewer.php.
Access:
- Visit /log-viewer in your Laravel app (e.g., https://your-app.test/log-viewer).
- No additional routes or middleware are required by default.
First Use Case:
- Debugging a production error: Navigate to /log-viewer, filter by error level, and search for keywords like 500 or DatabaseException to quickly locate relevant logs.

Implementation Patterns

Core Workflows

Log Exploration:
- Folder/File Navigation: Browse Laravel logs (storage/logs/) and other supported log types (Horizon, Nginx, Redis, etc.) via the UI.
- Filtering: Use the sidebar to filter by log level (debug, info, error), date range, or custom keywords.
- Search: Global search across all logs with regex support (e.g., /\d{3} Error/).
Advanced Features:
- Stack Trace Visualization:
  - Click a log entry with a stack trace to expand it into a collapsible, file-linked tree (Laravel 10+).
  - Example: Debug a QueryException by clicking the trace to see the SQL query and affected files.
- Mail Previews:
  - View sent emails logged via Log::channel('mail')->info($mailable) with rendered HTML previews.
- API Access:
  - Fetch logs programmatically via /api/log-viewer/folders, /api/log-viewer/files, or /api/log-viewer/entries.
  - Example: Automate log archiving with a cron job:
```
$logs = Http::get('http://your-app.test/api/log-viewer/entries?filter[level]=error');
```
Configuration:
- Custom Log Parsers: Extend support for unsupported log formats (e.g., custom JSON logs) by defining a parser in config/log-viewer.php:
```
'parsers' => [
    'custom-json' => \Opcodes\LogViewer\Parsers\JsonParser::class,
],
```
- Frontend Defaults: Override UI defaults (e.g., items per page, dark mode) in config/log-viewer.php:
```
'frontend' => [
    'defaults' => [
        'itemsPerPage' => 50,
        'darkMode' => true,
    ],
],
```

Multi-Host Environments:

Remote Logs: Configure log-viewer.php to include remote hosts:

'includes' => [
    'remote' => [
        'type' => 'remote',
        'url' => 'https://staging-app.test',
        'auth' => [
            'basic' => [
                'username' => 'user',
                'password' => 'pass',
            ],
        ],
    ],
],

Local IP Scoping: Disable local IP hashing in config/log-viewer.php to share logs across machines:
```
'useLocalIpInFileFolderHash' => false,
```

Asset Management:
- No Publish Needed: Since v3.18.0, assets are served directly from the vendor directory. Override via:
```
php artisan log-viewer:publish --tag=assets
```
- Custom Paths: Change the assets path in config/log-viewer.php:
```
'assets_path' => public_path('custom-log-viewer-assets'),
```

Gotchas and Tips

Pitfalls

Permission Issues:
- Symptom: Logs fail to load with a "403 Forbidden" error.
- Fix: Ensure the web server user (e.g., www-data, nginx) has read access to log files:
```
sudo chmod -R 755 storage/logs
sudo setfacl -R -m u:www-data:rX storage/logs
```
- Remote Logs: Verify the remote server’s APP_URL is accessible and credentials are correct.

Log Format Mismatches:

Symptom: Custom logs (e.g., JSON, CSV) appear as raw text.
Fix: Register a custom parser in config/log-viewer.php or extend \Opcodes\LogViewer\Parsers\ParserInterface:
```
'parsers' => [
    'json' => \App\Services\JsonLogParser::class,
],
```

Example Parser:

namespace App\Services;
use Opcodes\LogViewer\Parsers\ParserInterface;

class JsonLogParser implements ParserInterface {
    public function parse(string $line): array {
        return json_decode($line, true) ?: ['message' => $line];
    }
}

Octane Compatibility:
- Issue: Log Viewer may not work with Laravel Octane due to route binding conflicts.
- Fix: Use scoped bindings in routes/web.php:
```
Route::middleware(['web', 'log-viewer'])
     ->group(function () {
         \Opcodes\LogViewer\LogViewerServiceProvider::routes();
     });
```

Indexing Delays:

Symptom: New logs don’t appear immediately.

Fix: Log Viewer indexes logs on-demand. For real-time updates, use the API with polling:

// Poll logs every 5 seconds
setInterval(() => {
    axios.get('/api/log-viewer/entries?updated_after=' + new Date().toISOString())
         .then(response => updateUI(response.data));
}, 5000);

Horizon Logs:
- Issue: Horizon logs (v9.20+) may not display correctly.
- Fix: Ensure Horizon’s log path is included in config/log-viewer.php:
```
'includes' => [
    'horizon' => [
        'type' => 'horizon',
        'path' => storage_path('logs/horizon.log'),
    ],
],
```

Debugging Tips

API Debugging:
- Test the API endpoints directly:
```
curl -X GET http://your-app.test/api/log-viewer/folders
```
- Check for authentication issues if APP_URL is empty (fixed in v3.21.0).
Log Index Corruption:
- Symptom: Log entries appear duplicated or missing.
- Fix: Rebuild indexes via:
```
php artisan log-viewer:rebuild-indexes
```
- Note: This may take time for large log files.
Stack Trace Issues:
- Symptom: Stack traces don’t expand or show broken file links.
- Fix: Ensure debugbar is installed and configured in Laravel:
```
composer require barryvdh/laravel-debugbar
```
- Custom Paths: Map stack trace paths in config/log-viewer.php:
```
'stack_trace' => [
    'base_path' => app_path(),
],
```

Extension Points

Custom Log Types:

Extend \Opcodes\LogViewer\LogTypes\LogType to support new formats (e.g., Elasticsearch logs).

Example:

namespace App\LogTypes;
use Opcodes\LogViewer\LogTypes\LogType;

class ElasticsearchLogType extends LogType {
    protected $name = 'elasticsearch';
    protected $parser = \App\Services\ElasticsearchParser::class;
    protected $filePattern = '*.json';
}

'log_types' => [
    \App\LogTypes\ElasticsearchLogType::class,
],

UI Customization:

Override Blade templates in resources/views/vendor/log-viewer:
- Copy resources/views/vendor/log-viewer/layouts/app.blade.php to customize the layout.
- Extend Vue components by publishing assets and modifying resources/js/log-viewer.js.

Example: Add a custom button to download logs:

// resources/js/log-viewer.js
Vue.component('log-viewer-custom-button', {
    template: `<button @click="downloadLogs">Download Logs</button>`,
    methods: {
        downloadLogs() {
            axios.get('/api/log-viewer/entries', { responseType: 'blob' })
                 .then(response => {
                     const url = window.URL.createObjectURL(new Blob([response.data]));
                     const link = document.createElement('a');
                     link.href = url;
                     link.setAttribute('download', 'logs.zip');
                     document.body.appendChild(link);
                     link.click();
                 });
        }
    }

Log Viewer Laravel Package