Skip to main content
Retina provides powerful filtering options to customize which issues appear in your analysis reports. Filters can be applied via CLI options or configuration files.

​
Overview

Filtering helps you focus on relevant issues by:
  • Excluding entire categories of issues (e.g., all unused code warnings)
  • Disabling specific analyzers (e.g., deprecated API checks)
  • Hiding issues by severity level (e.g., info and hints)
CLI filter options override configuration file settings. If you specify a filter via CLI, the corresponding config file setting is ignored.

​
Category filtering

​
--exclude-categories
string
Comma-separated list of issue categories to exclude from reports.
retina run --exclude-categories unused,undefined
retina run --exclude-categories unused_variable,unused_import

​
Available category presets

Excludes all unused code warnings:
  • unused_variable
  • unused_parameter
  • unused_import
  • Dead code warnings
retina run --exclude-categories unused
Excludes all undefined reference warnings:
  • undefined_variable
  • undefined_method
  • undefined_class
  • undefined_constant
  • undefined_function
retina run --exclude-categories undefined
Excludes PocketMine-MP specific issues:
  • Plugin.yml validation errors
  • Event handler issues
  • API version problems
  • Thread safety violations
  • And other PocketMine-specific checks
retina run --exclude-categories pocketmine

​
Individual categories

You can also exclude specific individual categories: 
retina run --exclude-categories unused_variable,unused_import

​
Configuration file

In retina.yml: 
excludeCategories:
  - unused_variable
  - unused_import
Or using presets: 
excludeCategories:
  - unused
  - undefined

​
Analyzer filtering

​
--exclude-analyzers
string
Comma-separated list of analyzers to disable during analysis.
retina run --exclude-analyzers DeprecatedApi,ThreadSafety

​
Available analyzers

  • PhpFile - General PHP file structure and syntax
  • PHPStan - Advanced static analysis engine
  • PluginYml - Validates plugin.yml structure and content
  • MainClass - Checks main plugin class implementation
  • EventHandler - Validates event handler methods
  • Listener - Checks listener class registration
  • Command - Validates command implementations
  • Permission - Checks permission definitions
  • AsyncTask - Detects async task misuse and thread safety issues
  • Scheduler - Validates scheduler usage patterns
  • Config - Checks configuration file handling
  • Resource - Validates resource file access
  • DeprecatedApi - Detects usage of deprecated PocketMine-MP APIs
  • ThreadSafety - Identifies thread safety violations

​
Examples

Disable deprecated API warnings: 
retina run --exclude-analyzers DeprecatedApi
Disable multiple analyzers: 
retina run --exclude-analyzers DeprecatedApi,ThreadSafety,PHPStan

​
Configuration file

In retina.yml: 
excludeAnalyzers:
  - DeprecatedApi
  - ThreadSafety
Disabling core analyzers like PluginYml or MainClass may cause Retina to miss critical plugin structure issues.

​
Severity filtering

​
--exclude-severities
string
Comma-separated list of severity levels to exclude from reports.Valid severity levels: error, warning, info, hint
retina run --exclude-severities info,hint

​
Severity levels

Critical issues that will likely cause runtime failures or crashes. These should always be fixed before deployment.Examples:
  • Undefined variables or methods
  • Type mismatches
  • Invalid plugin.yml structure
Issues that may cause unexpected behavior or are considered bad practices.Examples:
  • Unused variables
  • Missing return types
  • Deprecated API usage
Informational messages about potential improvements or style recommendations.Examples:
  • Code style suggestions
  • Performance optimization hints
Minor suggestions that may improve code quality but are not critical.Examples:
  • Documentation suggestions
  • Alternative implementation hints

​
Examples

Show only errors and warnings: 
retina run --exclude-severities info,hint
Show only errors: 
retina run --exclude-severities warning,info,hint

​
Configuration file

In retina.yml: 
excludeSeverities:
  - info
  - hint

​
Combining filters

You can combine multiple filter types for precise control: 
retina run \
  --exclude-categories unused \
  --exclude-analyzers DeprecatedApi,ThreadSafety \
  --exclude-severities info,hint
In retina.yml: 
excludeCategories:
  - unused
  - undefined

excludeAnalyzers:
  - DeprecatedApi
  - ThreadSafety

excludeSeverities:
  - info
  - hint

​
Filter precedence

CLI options take precedence over configuration file settings:
  1. CLI filter options (highest priority)
  2. retina.yml configuration file
  3. Default settings (no filters)
If you specify a filter via CLI, the entire corresponding config file setting is replaced: 
# Config file has excludeCategories: [unused, undefined]
# CLI option completely replaces it:
retina run --exclude-categories pocketmine
# Result: Only 'pocketmine' is excluded, not 'unused' or 'undefined'

​
Validation

Retina validates filter configurations before running analysis:
  • Invalid category names will cause an error
  • Invalid analyzer names will cause an error
  • Invalid severity levels will cause an error
  • Typos in preset names will not match and may cause unexpected results
If filter validation fails, Retina will display an error message and exit without running analysis.

​
Use cases

retina run --exclude-severities warning,info,hint

retina run --exclude-categories unused,undefined --exclude-analyzers DeprecatedApi

retina run \
  --exclude-severities info,hint \
  --console-only \
  --no-progress

retina run --level 9
# No filters, all analyzers and severities included

retina run --exclude-analyzers PHPStan --exclude-categories unused,undefined

Build docs developers (and LLMs) love

Get started for freeTalk to us