README

The App Logging Web package provides a web interface for browsing and inspecting log entries created by the tobento-ch/app-logging package.

This package is especially useful when:

• you want quick visibility into application issues
• you don't have direct access to log files
• you want to inspect logs during development or debugging
• you use modular features where logs may or may not be enabled

Zero-Config Bootstrapping

The Logging Web system works out-of-the-box with sensible defaults.

Simply register the Logging Web Boot in your application, and the full log browsing UI becomes available immediately - no additional configuration required.

All built-in features are automatically discovered, registered, and ready to use.
You can inspect logs, browse log cards, and monitor application logs without writing any custom code.

You only need to customize configuration if you want to override defaults such as:

• enabling or disabling specific logging-web features
• customizing log cards or card collections
• adjusting ACL permissions and access control
• overriding log monitoring behavior
• using a shared log repository across multiple apps
• customizing storage or repository implementations

Table of Contents

• Getting Started
  • Requirements
• Documentation
  • App
  • Logging Web Boot
    • Logging Web Config
  • Features
    • Logs Feature
    • Logs Cards Feature
    • Monitor Logs Feature
  • Console
    • Purge Logs Command
  • Learn More
    • Monitor Logs From Another App
• Credits

Getting Started

Install the latest version of the App Logging Web package by running:

composer require tobento/app-logging-web

Requirements

• PHP 8.4 or above

Documentation

Check out the App Skeleton if you are using the skeleton.

You may also check out the App to learn more about the app in general.

Logging Web Boot

The LoggingWeb boot does the following:

• installs and loads logging-web config
• implements logging-web interfaces
• boots Features configured in Logging Web Config

use Tobento\App\AppFactory;
use Tobento\App\Logging\Web\LogRepositoryInterface;

// Create the app
$app = new AppFactory()->createApp();

// Add directories:
$app->dirs()
    ->dir(realpath(__DIR__.'/../'), 'root')
    ->dir(realpath(__DIR__.'/../app/'), 'app')
    ->dir($app->dir('app').'config', 'config', group: 'config')
    ->dir($app->dir('root').'public', 'public')
    ->dir($app->dir('root').'vendor', 'vendor');

// Adding boots
$app->boot(\Tobento\App\Logging\Web\Boot\LoggingWeb::class);
$app->booting();

// Implemented interfaces:
$logRepository = $app->get(LogRepositoryInterface::class);

// Run the app
$app->run();

You may also install the App Backend and boot the logging web within the backend application.

Logging Web Config

The configuration for the logging web is located in the app/config/logging-web.php file at the default App Skeleton config location.
There you can configure the available features and other options.

FeaturesLogs Feature

The Logs feature provides a page for viewing and inspecting log entries created by the tobento-ch/app-logging package.

Config

In the logging web config you can enable and configure this feature:

'features' => [
    new Feature\Logs(
        // A menu name to show the logs link, or null for no menu entry.
        menu: 'main',
        menuLabel: 'Logs',
        // A menu parent name (e.g. 'system') or null if none.
        menuParent: null,
        
        // You may disable ACL while testing.
        // Otherwise, only users with the required permissions can access the page.
        withAcl: false,
    ),
],

ACL Permissions

• logs User can access jobs

If you are using the App Backend, you can assign this permission to roles or users in the backend interface.

Logs Cards Feature

The Logs Cards feature provides cards that display log-related information using the app-card package.
These cards can be added to any card collection, such as the App Backend Dashboard Cards or any other custom card groups.

Config

In the logging web config you can enable and configure this feature:

use Tobento\App\Card\CardsInterface;

'features' => [
    new Feature\LogsCards(
        // Define the card collections where the logs cards should be added.
        applyToCards: [
            \Tobento\App\Backend\Card\DashboardCards::class, // CardsInterface
        ],
        
        // You may disable ACL while testing.
        // Otherwise, only users with the required permissions can see logs cards.
        withAcl: false,
    ),
],

The ACL check is performed before cards are added.
If ACL is enabled and the user does not have the logs permission, the cards are simply not added to the collection.

Customize Cards

You may customize the cards added by this feature by extending or replacing the LogsCards feature.
The feature uses the configureCards() method to define which cards are created.

To override or extend the cards, create your own feature:

use Tobento\App\Card\CardsInterface;
use Tobento\App\Logging\Web\Card\LatestLogsCard;
use Tobento\App\Logging\Web\Feature\LogsCards;

class CustomLogsCards extends LogsCards
{
    protected function configureCards(AppInterface $app): CardsInterface
    {
        $cards = parent::configureCards(app: $app);
        
        // Example: Add a custom card showing the latest debug logs.
        $cards->add('latest-debug-logs', new LatestLogsCard(
            logRepository: $app->container()->get(LogRepositoryInterface::class),
            view: $app->container()->get(ViewInterface::class),
            priority: 1000,
            title: 'Latest Debug Logs',
            levels: ['debug'],
            limit: 5,
        ));

        return $cards;
    }
}

Then register your custom feature instead of the default one:

'features' => [
    new CustomLogsCards(
        applyToCards: [
            \Tobento\App\Backend\Card\DashboardCards::class,
        ],
        withAcl: true,
    ),
],

This allows you to fully control which cards appear, their order, and how they behave.

For more details on creating and customizing cards, see the app-card documentation.

Monitor Logs Feature

The Monitor Logs feature wraps the application loggers and stores log entries in the LogRepositoryInterface for later inspection.
It depends on the Logging boot and is applied automatically when enabled.

Config

In the logging web config you can enable and configure this feature:

'features' => [
    new Feature\MonitorLogs(
        // Optionally override monitoring settings for specific loggers.
        // All other loggers are still monitored using their default settings.
        // To disable monitoring for a logger, you must explicitly configure it here.
        monitor: [
            'daily' => [
                'repository' => true, // write logs to LogRepositoryInterface (default)
                'logger' => true, // also log using the original logger (default)
            ],
        ],
    ),
],

This feature ensures that log entries are captured and made available for viewing in the Logs Feature web interface.

ConsolePurge Logs Command

Use the following command to purge monitored logs:

Purge logs older than 24 hours

php ap logs:purge

Available Options

Option	Description
--hours=24	The number of hours to retain log data.
--level=debug	Purges only logs with the specified level.
--appId[]	Purges only logs belonging to the specified app IDs.

If you would like to automate this process, consider installing the App Schedule bundle and using a command task:

use Tobento\Service\Schedule\Task;
use Butschster\CronExpression\Generator;

$schedule->task(
    new Task\CommandTask(
        command: 'logs:purge',
    )
    // Schedule task:
    ->cron(Generator::create()->daily())
);

Alternatively, you may install the App Task bundle and use the Command Task Registry to register this command.

Learn MoreMonitor Logs From Another App

When working with multiple Apps, you may monitor logs across all of them.
To do so, ensure that each app uses the same log repository connection in its config file.

For example, in an app using the App Backend, you might configure:

'features' => [
    Feature\Logs::class,
    Feature\MonitorLogs::class,
],

'interfaces' => [
    LogRepositoryInterface::class =>
    static function(DatabasesInterface $databases): LogRepositoryInterface {
        return new LogStorageRepository(
            storage: $databases->default('shared:storage')->storage()->new(),
            table: 'logs',
        );
    },
],

Next, in another app where you only want to monitor logs:

'features' => [
    // only monitor logs:
    Feature\MonitorLogs::class,
],

'interfaces' => [
    LogRepositoryInterface::class =>
    static function(DatabasesInterface $databases): LogRepositoryInterface {
        return new LogStorageRepository(
            storage: $databases->default('shared:storage')->storage()->new(),
            table: 'logs',
        );
    },
],

Finally, in the database config file of both apps, configure the shared:storage database:

'defaults' => [
    'pdo' => 'mysql',
    'storage' => 'file',
    'shared:storage' => 'shared:file',
],

'databases' => [
    'shared:file' => [
        'factory' => \Tobento\Service\Database\Storage\StorageDatabaseFactory::class,
        'config' => [
            'storage' => \Tobento\Service\Storage\JsonFileStorage::class,
            'dir' => directory('app:parent').'storage/database/file/',
        ],
    ],
],

By using a shared storage connection, all monitored logs from every app are stored in the same repository, allowing them to be viewed centrally in the Logs Feature web interface.

Credits

• Tobias Strub
• All Contributors