Getting Started

Minimal Setup

Installation:
```
composer require opcodesio/log-viewer
php artisan log-viewer:publish
```
This installs the package and publishes assets (Vue.js frontend).
First Access: Visit {APP_URL}/log-viewer (e.g., http://localhost:8000/log-viewer). No additional configuration is required for basic Laravel log viewing.
First Use Case:
- Debugging Errors: Immediately inspect Laravel’s storage/logs/laravel.log for recent errors.
- Search: Use the search bar to filter logs by keywords (e.g., SQLSTATE[HY000]).
- Filter by Level: Toggle log levels (e.g., error, warning) via the sidebar.

Implementation Patterns

Core Workflows

Log Exploration:
- Folder Navigation: Browse log files (Laravel, Horizon, Nginx, etc.) in a tree view.
- Log Entry Context: Click a log line to expand it, revealing:
  - Timestamp, log level, and message.
  - Stack Trace Tab (Laravel 10+): Visualize exception traces with file/line links.
  - Mail Previews: If the log entry includes sent emails, view them inline.
Advanced Filtering:
- Log Level: Filter by debug, info, warning, error, etc.
- Time Range: Use the date picker to narrow logs to a specific period.
- Custom Search: Combine keywords with operators (e.g., error AND "timeout").
API Integration:
- Programmatic Access: Fetch logs via the API endpoint (/log-viewer/api/folders, /log-viewer/api/logs). Example (JavaScript):
```
fetch('/log-viewer/api/logs?file=laravel.log')
  .then(response => response.json())
  .then(logs => console.log(logs));
```
- Authentication: Secure the API with Laravel’s built-in auth (e.g., auth:sanctum middleware).
Log Management:
- Delete/Download: Right-click a log file to delete it or download its contents.
- Sharable Links: Generate URLs like /log-viewer?file=laravel.log&line=42 to share specific log entries.

Integration Tips

Custom Log Formats:
- Extend log support by defining a custom parser in config/log-viewer.php:
```
'parsers' => [
    'custom' => \Opcodes\LogViewer\Parsers\CustomParser::class,
],
```
- Implement Opcodes\LogViewer\Contracts\LogParser to handle non-standard log formats.
Multi-Host Environments:
- Configure log-viewer to scan logs from remote hosts by adding entries to log-viewer.includes:
```
includes:
    - path: /var/log/myapp
      remote: true
      host: ssh://user@remote-server
```

Octane Compatibility:

Use scoped bindings for Octane (Laravel’s high-performance server):

$app->bind(Opcodes\LogViewer\Services\LogService::class, function ($app) {
    return new Opcodes\LogViewer\Services\LogService(
        $app->make(Opcodes\LogViewer\Repositories\LogRepository::class)
    );
});

Frontend Customization:

Override default UI settings in config/log-viewer.php:

'frontend' => [
    'defaults' => [
        'itemsPerPage' => 50,
        'darkMode' => true,
    ],
],

Extend Vue components by publishing assets and modifying the frontend:
```
php artisan vendor:publish --tag=log-viewer-assets
```

Gotchas and Tips

Pitfalls

Permission Issues:
- Symptom: Logs fail to load with "Permission denied" errors.
- Fix: Ensure the web server user (e.g., www-data, nginx) has read access to log directories:
```
chmod -R 755 storage/logs
chown -R www-data:www-data storage/logs
```
Missing Logs:
- Symptom: Custom log files (e.g., app.log) are not detected.
- Fix: Explicitly include them in log-viewer.includes:
```
includes:
    - path: storage/logs/app.log
```
Horizon Logs Not Showing:
- Symptom: Horizon logs are missing despite being enabled.
- Fix: Ensure Horizon’s log path is included and the log format matches Horizon’s structure. Update log-viewer.includes:
```
includes:
    - path: storage/logs/horizon.log
      parser: horizon
```

API Authentication Failures:

Symptom: API endpoints return 401 Unauthorized.

Fix: Configure middleware in routes/web.php:

Route::middleware(['auth:sanctum'])->group(function () {
    Route::prefix('log-viewer/api')->group(base_path('vendor/opcodes/log-viewer/src/Routes/api.php'));
});

Multiline Logs (Nginx/Apache):
- Symptom: Nginx/Apache logs appear truncated.
- Fix: Ensure the log parser is configured to handle multiline entries. For Nginx, use:
```
includes:
    - path: /var/log/nginx/access.log
      parser: nginx
      multiline: true
```

Debugging Tips

Log Parser Debugging:
- Enable debug mode in config/log-viewer.php:
```
'debug' => true,
```
- Check Laravel logs (storage/logs/laravel.log) for parser errors.
Indexing Issues:
- Symptom: Logs load slowly or appear out of sync.
- Fix: Rebuild the log index:
```
php artisan log-viewer:rebuild-index
```
- For persistent issues, adjust the index_path in config/log-viewer.php to a writable directory.
Frontend Assets:
- Symptom: Styling or JavaScript fails to load.
- Fix: Clear cached assets:
```
php artisan view:clear
php artisan cache:clear
```
- If using a custom asset path, ensure assets_path in config/log-viewer.php is correct.

Extension Points

Custom Log Parsers:

Create a parser for proprietary log formats by implementing Opcodes\LogViewer\Contracts\LogParser:

namespace App\Parsers;

use Opcodes\LogViewer\Contracts\LogParser;
use Opcodes\LogViewer\Models\LogEntry;

class CustomParser implements LogParser {
    public function parse(string $line): ?LogEntry {
        // Parse custom log format and return a LogEntry instance
    }
}

'parsers' => [
    'custom' => \App\Parsers\CustomParser::class,
],

API Extensions:

Extend the API by adding routes in routes/web.php:

Route::prefix('log-viewer/api')->group(function () {
    Route::get('/custom-endpoint', [\App\Http\Controllers\LogViewerController::class, 'customMethod']);
});

Use the existing API service (Opcodes\LogViewer\Services\LogService) for consistency.

Event Listeners:

Listen for log events (e.g., log entry creation) by registering a listener:

namespace App\Listeners;

use Opcodes\LogViewer\Events\LogEntryCreated;

class LogEntryListener {
    public function handle(LogEntryCreated $event) {
        // Custom logic (e.g., notify Slack)
    }
}

protected $listen = [
    LogEntryCreated::class => [
        LogEntryListener::class,
    ],
];

Dark Mode Toggle:

Override the default dark mode behavior by extending the Vue component:

// resources/js/log-viewer/components/App.vue
export default {
    data() {
        return {
            darkMode: false, // Override default
        };
    },
};

Configuration Quirks

includes Path Handling:
- Paths in log-viewer.includes are resolved relative to the Laravel root unless prefixed with / (absolute path).
- Example:
```
includes:
    - path: logs/app.log          # Relative to Laravel root
    - path: /var/log/nginx/error.log
```

Log Viewer Laravel Package