beastbytes/yii-tracy

Integrate the Tracy debugger into the Yii Framework

Maintainers

Details

github.com/beastbytes/yii-tracy

Source

Issues

Installs: 45

Dependents: 5

Suggesters: 1

Security: 0

Stars: 0

Watchers: 1

Forks: 0

Open Issues: 0

dev-main 2025-07-06 19:25 UTC

Requires

Requires (Dev)

BSD-3-Clause 80404fb4e7b269014b59881e598f0381963832c3

debuggeryiitracy

This package is auto-updated.

Last update: 2025-07-06 21:23:40 UTC

README

The Yii Tracy package integrates the Tracy debugging tool into Yii3.

Requirements

  • PHP 8.1 or higher

Installation

Do not directly install this package.

Install the Yii Tracy Panels as required.

Configuration

Yii Tracy is configured using Yii’s configuration. It has the following configuration parameters defined in the beastbytes/yii-tracy section of params-web.php:

  • editor (string) Tracy IDE integration
  • email (null|string|string[]) Email address(es) to which send error notifications
  • logDirectory (?string) Absolute path or path alias to the log directory. Default: '@runtime/logs'
  • logSeverity (int) Log bluescreen in production mode for this error severity.
  • mode (null|bool|string|array) The mode that Tracy is to operate in; Development or Production.

    • Tracy\Debugger::Detect: Tracy detects the mode; it sets development mode is if it is running on localhost (i.e. IP address 127.0.0.1 or ::1) and there is no proxy, otherwise it sets production mode.

    • Tracy\Debugger::Development: put Tracy in development mode.

    • Tracy\Debugger::Production: put Tracy in production mode.

    • string: enable development mode for the given IP address.

    • string[]: enable development mode for IP addresses in the list.

      NOTE It is highly recommended to combine IP addresses with a cookie token by specifying allowed addresses as <token>@<ipAddress>; see token.

  • panelConfig (array) Panel configurations indexed by panel ID. Panel packages contain default configuration.
  • panels (string[]) IDs of panels to show. The panels are added to the debugger in the order listed.
  • showBar (bool) Whether to display debug bar in development mode.
  • token (string) The secret token for enabling development mode for IP addresses. See mode.

Note: A panel must be configured in panelConfig and listed in panels to be enabled.

Set the required configuration parameters in the application params-web configuration file.

Internationalisation

Yii Tracy supports internationalisation of tabs and panels. To ensure that this works as expected an implementation of Yiisoft\Translator\TranslatorInteface must be present in application views.

Disable Yii Debug

Yii Tracy uses components of Yii Debug; to ensure Yii Tracy operates correctly, it is necessary to disable Yii Debug.

In the application entry script, set the configModifiers parameter in the constructor of the application runner; the value is:

[
    RemoveFromVendor::groups([
        'yiisoft/yii-debug' => '*',
    ]),
]

The end of the application entry script will be something like:

(new HttpApplicationRunner(
    rootPath: <root path>,
    debug: <true|false>,
    checkEvents: <true|false>,
    environment: <development|test|production>,
    configModifiers: [
        RemoveFromVendor::groups([
            'yiisoft/yii-debug' => '*',
        ]),
    ],
))->run();

Panels

The following panels are available:

  • Assets Provides information about Asset Bundles on the page.
  • Database Provides information about the database connection and executed queries.
  • Route Provides information about the current route.
  • User Provides information about the current user.
  • View Provides information about the rendered view.

Add the required panels to the require-dev section of the application composer.json. This package is installed as a dependency.

Custom Panels

Custom panels can be added to Yii Tracy. The information below gives details of how to do this. Also see Tracy Bar Extensions for more information and examine the existing panels for example code.

Panel Class

The Panel class must extend either BeastBytes\Yii\Tracy\Panel\Panel or one of the collector panel classes if the panel uses a Yiisoft\Yii\Debug\Collector\CollectorInterface.

All panels have access to Yii's Dependency Injection container through the $container property.

The Panel class must implement the following methods:

getViewPath(): string

Visibility: public

Returns the view path.

BeastBytes\Yii\Tracy\ViewTrait provides this method for panels that follow the standard file structure.

panelParameters(): array

Visibility: protected

Returns view parameters for the panel view as array<string: mixed>;

panelTitle(): array

Visibility: protected

Returns array{id: string, category: int} where:

  • id: message id for translation
  • category: message translation category

Tip Define a public constant MESSAGE_CATEGORY = tracy-<panel-id>

tabIcon(array $parameters): string

Visibility: protected

Returns an SVG icon for the debugger tab view.

The method takes the tab parameters as an argument to allow the icon to reflect the state of the tab.

tabParameters(): array

Visibility: protected

Returns view parameters for the debugger tab view as array<string: mixed>;

tabTitle(): array

Visibility: protected

Returns array{id: string, category: int} where:

  • id: message id for translation
  • category: message translation category

Tip Define a public constant MESSAGE_CATEGORY = tracy-<panel-id>

Views

The panel must implement two views, tab and panel; they are php templates. The views need only render the tab/panel content; Yii Tracy provides layouts for both tab and panel to decorate the content.

To correctly support internationalisation and make the panel fully contained, it is recommended to:

  • Define a public constant in the Panel class that defines the message translation category
public const MESSAGE_CATEGORY = 'tracy-<panel-id>';

where <panel-id> is the panel id, and the prefix tracy- avoids name collisions

  • Place the following line at the start of the tab and panel views:
$translator = $translator->withDefaultCategory(Panel::MESSAGE_CATEGORY);
  • Use message ids of the form <panel-id>.type.name. Suggested types are 'heading', 'title', 'value'. type can be omitted for body text.

Configuration

Two configuration files are required:

  • di-web.php - defines the message translation category
  • params-web - defines the panel

and references to them in composer.json.

di-web.php
use Fully\Qualified\Namespace\For\Panel;
use Yiisoft\Translator\CategorySource;
use Yiisoft\Translator\IntlMessageFormatter;
use Yiisoft\Translator\Message\Php\MessageSource;

$category = Panel::MESSAGE_CATEGORY;
$messageSource = dirname(__DIR__) . '/resources/messages';

return [
    "translation.$category" => [
        'definition' => static function() use ($category, $messageSource)  {
            return new CategorySource(
                $category,
                new MessageSource($messageSource),
                new IntlMessageFormatter(),
            );
        },
        'tags' => ['translation.categorySource'],
    ],
];
params-web.php
return [
    'beastbytes/yii-tracy' => [
        'panelConfig' => [
            '<panel-id>' => [
                'class' => <FQCN>,
                // Additional panel definition
            ],
        ],
    ],
];
composer.json

Add references to di-web.php and params.php in the extra section of composer.json:

  "extra": {
    // Additional 'extra' sections
    "config-plugin": {
      "di-web": "di-web.php",
      "params-web": "params-web.php"
    }
  }

License

The BeastBytes Yii Tracy package is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.