README

A powerful Laravel package to scan, manage, and track TODO, FIXME, HACK, REVIEW, and NOTE comments across your entire project. Transform scattered code comments into a manageable technical debt backlog with a beautiful web interface.

Features

🔍 Smart Scanning - Detects TODO, FIXME, HACK, REVIEW, NOTE comments in single-line and multi-line formats
📊 Web Interface - Clean, responsive dashboard with filtering, search, and bulk actions
🎨 Dark/Light Theme - Automatic theme switching with user preference persistence
🌍 Multi-language - Support for 9 languages (English, Russian, Ukrainian, Polish, German, French, Spanish, Chinese, Japanese)
🔐 Authentication - Simple HTTP Basic Auth with configurable credentials
⚡ Bulk Operations - Update multiple task statuses at once
🗂️ File Links - Direct links to files in PhpStorm (configurable for other IDEs)
📈 Statistics - Visual statistics by type, priority, and status
🛠️ Artisan Command - php artisan todo:scan for manual or scheduled scanning

Requirements

PHP 8.1 or higher
Laravel 10.x, 11.x, 12.x, or 13.x
MySQL, PostgreSQL, or SQLite

Installation

1. Install via Composer

composer require php-prosvirin-dev/laravel-todo-inspector

2. Publish Package Assets

Publish everything at once:

php artisan vendor:publish --provider="Prosvirin\LaravelTodoInspector\TodoInspectorServiceProvider"

Or publish individually:

php artisan vendor:publish --tag=todo-inspector-config      # Configuration
php artisan vendor:publish --tag=todo-inspector-migrations  # Database migrations
php artisan vendor:publish --tag=todo-inspector-views       # Blade templates
php artisan vendor:publish --tag=todo-inspector-lang        # Language files
php artisan vendor:publish --tag=todo-inspector-assets      # CSS/JS assets

3. Run Migrations

php artisan migrate

4. Configure Authentication

Add credentials to your .env file to secure the web interface:

TODO_INSPECTOR_LOGIN=admin
TODO_INSPECTOR_PASSWORD=your-secure-password

Configuration

The configuration file is located at config/todo-inspector.php after publishing.

Basic Configuration

return [
    'table_name' => env('TODO_INSPECTOR_TABLE', 'todo_inspector_tasks'),
    'theme' => env('TODO_INSPECTOR_THEME', 'dark'),
    'auth' => [
        'login' => env('TODO_INSPECTOR_LOGIN', 'admin'),
        'password' => env('TODO_INSPECTOR_PASSWORD', 'password'),
    ],
    'locales' => [
        'en' => ['flag' => '🇬🇧', 'name' => 'English'],
        'ru' => ['flag' => '🇷🇺', 'name' => 'Русский'],
        'uk' => ['flag' => '🇺🇦', 'name' => 'Українська'],
        'pl' => ['flag' => '🇵🇱', 'name' => 'Polski'],
        'de' => ['flag' => '🇩🇪', 'name' => 'Deutsch'],
        'fr' => ['flag' => '🇫🇷', 'name' => 'Français'],
        'es' => ['flag' => '🇪🇸', 'name' => 'Español'],
        'zh' => ['flag' => '🇨🇳', 'name' => '中文'],
        'ja' => ['flag' => '🇯🇵', 'name' => '日本語'],
    ],
    'extensions' => ['php', 'js', 'vue', 'blade.php', 'css', 'scss'],
    'exclude_dirs' => ['vendor', 'node_modules', 'storage', 'bootstrap/cache', '.git', 'tests'],
    'exclude_files' => ['test-*.php', '*_test.php', '*.test.php'],
    'github_repo' => env('TODO_INSPECTOR_GITHUB_REPO', null),
];

Usage

Run the scan command to find all TODO comments:

php artisan todo:scan

Options:

--clear - Clear existing tasks before scanning
--type=TODO - Scan only specific type (TODO, FIXME, HACK, REVIEW, NOTE)
--path=app/Http - Scan only specific directory

Example:

php artisan todo:scan --clear --type=FIXME --path=app/Http

Schedule Automatic Scans

Add to app/Console/Kernel.php:

protected function schedule(Schedule $schedule): void
{
    $schedule->command('todo:scan')->dailyAt('03:00');
    // or hourly: $schedule->command('todo:scan')->hourly();
}

Access Web Interface

http://your-project.test/todo-inspector

Features in Web Interface

Dashboard

Statistics Cards - Total tasks and breakdown by type
Priority Statistics - Visual breakdown by priority level
Click Filters - Click on any statistic card to filter tasks

Task Management

Search - Search across content, file paths, and authors
Filters - Filter by type, priority, and status
Bulk Actions - Update multiple tasks at once
Status Updates - Change task status directly from the table
File Links - Click the code icon to open the file in PhpStorm

Theme & Language

Dark/Light Mode - Toggle with persistent preference
Multi-language - Select from 9 languages, saved to localStorage

Comment Format Examples

The package detects comments in the following formats:

Single-line Comments

// TODO: Fix this bug
// FIXME: @username Memory leak here
// HACK: [HIGH] Temporary workaround
// REVIEW: @lead Please check this logic
// NOTE: Important performance consideration

Multi-line Comments

/**
* TODO: Refactor this method
* FIXME: @developer Edge case not handled
* REVIEW: Architecture decision needed
  */

Priority Tags

Use brackets to specify priority:

[LOW] - Low priority
[MEDIUM] - Medium priority (default)
[HIGH] - High priority
[CRITICAL] - Critical priority

Author Tags

Use @username to assign tasks to specific developers.

Customization

Override Views

php artisan vendor:publish --tag=todo-inspector-views

Views will be copied to resources/views/vendor/todo-inspector/. Modify them as needed.

Override Translations

php artisan vendor:publish --tag=todo-inspector-lang

Translations will be copied to resources/lang/vendor/todo-inspector/. Add or modify translations.

Custom CSS/JS

php artisan vendor:publish --tag=todo-inspector-assets

Assets will be copied to public/vendor/todo-inspector/. Update CSS or JS files directly.

Troubleshooting

Tasks Not Found

Check file extensions in config
Verify exclude directories don't include your code
Ensure comments match the expected patterns

Authentication Issues

Verify credentials in .env file
Clear config cache: php artisan config:clear

Translation Not Working

Publish language files: php artisan vendor:publish --tag=todo-inspector-lang
Clear view cache: php artisan view:clear

Contributing

Contributions are welcome! Please submit a Pull Request or create an Issue.

License

The MIT License (MIT). Please see License File for more information.

Credits

Created by Yauheni Prasviryn
Built with Laravel and Tailwind CSS

php-prosvirin-dev / laravel-todo-inspector

Maintainers

Package info

Statistics

Security