Skip to content

Refactor debugbar() Helper for Structural and Behavioral Consistency #458

Closed

Description

@armanist

Refactor debugbar() helper for structural consistency

Description

The debugbar() helper method currently violates two major architectural conventions in the quantum-php-core framework:

  1. Incorrect Location: The function is currently defined in src/View/Helpers/view.php. The Debugger is a separated component, and this tightly couples the View module to Debugger dependencies.
  2. Inconsistent Behavior: The helper method currently executes business logic ($debugger->render()) instead of acting as a typical service locator. Other helper functions in the framework (e.g., config(), session(), request()) intuitively return the underlying service instance, allowing the developer to interact with the service fluently.

Current Implementation

Location: src/View/Helpers/view.php

function debugbar(): ?string
{
    if (!Di::isRegistered(Debugger::class)) {
        Di::register(Debugger::class);
    }

    $debugger = Di::get(Debugger::class);

    if ($debugger->isEnabled()) {
        return $debugger->render();
    }

    return null;
}

Proposed Solution

  1. Relocate the Helper: Move the debugbar() function to a dedicated helper file inside the Debugger module: src/Debugger/Helpers/debugger.php.
  2. Update the Return Value: Alter the helper logic so it strictly returns a Debugger instance.
  3. Protect the Render Method: Currently Debugger::render() does not check if debugging is enabled. We must update it to return an empty string if isEnabled() is false. Without this, calling debugbar()->render() in a layout file would render the bar even in production!

Changes for src/Debugger/Helpers/debugger.php

// Exception catching / PhpDoc omitted for brevity
function debugbar(): Debugger
{
    if (!Di::isRegistered(Debugger::class)) {
        Di::register(Debugger::class);
    }

    return Di::get(Debugger::class);
}

Changes for src/Debugger/Debugger.php

public function render(): string
{
    if (!$this->isEnabled()) {
        return '';
    }

    // ... existing render logic ...
}

After these changes, rendering the debug bar should be explicitly called via method chaining inside templates: debugbar()->render(). This will be perfectly safe since render() will now respect the debug configuration.

Considerations

  • Update the composer.json or LoadHelpersStage class to ensure src/Debugger/Helpers/debugger.php is properly autoloaded.
  • Scan the codebase for any implicit HTML rendering calls relying on debugbar() and update them to use debugbar()->render() if necessary (for instance, in main layouts).

Activity

  1. self-assigned this
    on Apr 21, 2026
  2. added this to the 3.0.0 milestone on Apr 21, 2026
  3. added a commit that references this issue on Apr 21, 2026
  4. added a commit that references this issue on Apr 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

bugSomething isn't workinggood first issueGood for newcomershelp wantedExtra attention is needed

Type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions