Skip to main content
Retina can be customized using a retina.yml configuration file in your plugin’s root directory. This allows you to set default analysis options, define scan paths, exclude specific checks, and more.

​
Creating a configuration file

The quickest way to create a configuration file is to use the init command: 
retina init
This will create a retina.yml file in your current directory with all available options and helpful comments.
You can also run retina init /path/to/plugin to create a configuration file in a specific directory.

​
Configuration file structure

Here’s the complete default configuration file generated by Retina: 
# Retina Configuration
# PocketMine-MP Plugin Static Analyzer

# Analysis strictness level (1-9, higher = stricter)
level: 6

# Paths to scan (relative to plugin root)
paths:
  - src

# Paths to exclude from scanning
excludePaths:
  - vendor
  - tests

# Default report format (md, json, txt, html)
reportFormat: md

# Generate simplified reports (default: false)
# Simple reports show only file, line, category, severity, and message
# without code snippets or suggestions
simpleReport: false

# Exclude specific issue categories from reports
# Presets: unused, undefined, pocketmine
# Or specify individual categories like: unused_variable, unused_import
excludeCategories: []
#  - unused_variable
#  - unused_import

# Disable specific analyzers
# Available: PluginYml, MainClass, PhpFile, EventHandler, Listener,
#            Command, Permission, AsyncTask, Scheduler, Config,
#            Resource, DeprecatedApi, ThreadSafety, PHPStan
excludeAnalyzers: []
#  - DeprecatedApi
#  - ThreadSafety

# Exclude severity levels from reports
# Valid: error, warning, info, hint
excludeSeverities: []
#  - info
#  - hint

# Custom rules configuration
rules:
  # PHP Standard Rules
  undefinedVariable: true
  undefinedMethod: true
  undefinedClass: true
  undefinedConstant: true
  undefinedFunction: true
  typeMismatch: true
  unusedVariable: true
  unusedParameter: true
  unusedImport: true
  deadCode: true
  
  # PocketMine-MP Specific Rules
  invalidEventHandler: true
  unregisteredListener: true
  invalidPluginYml: true
  mainClassMismatch: true
  invalidApiVersion: true
  deprecatedApiUsage: true
  asyncTaskMisuse: true
  schedulerMisuse: true
  configMisuse: true
  permissionMismatch: true
  commandMismatch: true
  resourceMissing: true
  invalidEventPriority: true
  cancelledEventAccess: true
  threadSafetyViolation: true

# Ignore specific error codes
ignoreErrors: []

# PHPStan baseline file (for gradual adoption)
baseline: null

​
Configuration options

​
Analysis level

1

Set strictness level

The level option controls how strict the analysis is. Higher levels catch more issues but may also produce more false positives.
level: 6
  • 1-3: Basic checks (syntax errors, critical issues)
  • 4-6: Standard checks (recommended for most plugins)
  • 7-9: Strict checks (catches more potential issues)

​
Scan paths

1

Define paths to scan

Specify which directories should be analyzed:
paths:
  - src
  - lib
Paths are relative to your plugin’s root directory.
2

Exclude paths from scanning

Specify which directories should be ignored:
excludePaths:
  - vendor
  - tests
  - build
This is useful for excluding third-party code or test files.

​
Report settings

1

Set default format

Choose the default output format for reports:
reportFormat: md  # Options: md, json, txt, html
2

Enable simple reports

Simple reports show only essential information without code snippets or suggestions:
simpleReport: false
Set to true to generate minimal reports ideal for CI/CD environments.

​
Filtering options

​
Exclude categories

You can exclude specific issue categories from reports using presets or individual categories: 
excludeCategories:
  - unused      # Excludes: unused_variable, unused_parameter, unused_import
  - undefined   # Excludes: undefined_variable, undefined_method, etc.
  - pocketmine  # Excludes all PocketMine-MP specific categories

​
Exclude analyzers

Disable specific analyzers completely: 
excludeAnalyzers:
  - DeprecatedApi   # Don't check for deprecated API usage
  - ThreadSafety    # Don't check thread safety violations
  - PHPStan         # Don't run PHPStan analysis
Available analyzers:
  • PluginYml - Validates plugin.yml structure
  • MainClass - Checks main class exists and extends PluginBase
  • PhpFile - General PHP syntax validation
  • EventHandler - Validates event handler methods
  • Listener - Checks listener registration
  • Command - Validates command implementations
  • Permission - Checks permission definitions
  • AsyncTask - Detects AsyncTask misuse
  • Scheduler - Validates scheduler usage
  • Config - Checks config file handling
  • Resource - Validates resource file access
  • DeprecatedApi - Finds deprecated PocketMine-MP API usage
  • ThreadSafety - Detects thread safety violations
  • PHPStan - Runs PHPStan analysis

​
Exclude severities

Filter out issues by severity level: 
excludeSeverities:
  - info  # Don't show informational messages
  - hint  # Don't show hints and suggestions
Severity levels:
  • error - Critical issues that will cause crashes
  • warning - Problems that should be fixed
  • info - Suggestions for improvement
  • hint - Minor style or optimization suggestions

​
Rules configuration

Enable or disable specific rules individually: 
rules:
  undefinedVariable: true
  undefinedMethod: true
  undefinedClass: true
  typeMismatch: true
  unusedVariable: false  # Disable unused variable checks
  deadCode: true

​
Advanced options

​
Ignore specific errors

You can ignore specific error patterns: 
ignoreErrors:
  - "#Variable \$debug is never read#"
  - "#Call to deprecated method#"
Error patterns use regular expressions for matching.

​
PHPStan baseline

For gradual adoption, you can specify a PHPStan baseline file: 
baseline: phpstan-baseline.neon
This allows you to track existing issues while preventing new ones from being introduced.

​
Command line overrides

Command line options always take precedence over configuration file settings: 
# Override report format
retina run -f json

# Override strictness level
retina run -l 8

# Override exclude categories
retina run --exclude-categories=unused,undefined

# Enable simple report
retina run -s
When using command line options, they completely replace the corresponding configuration file settings rather than merging with them.

​
Example configurations

level: 4
reportFormat: md
simpleReport: false

paths:
  - src

excludePaths:
  - vendor
  - tests

excludeSeverities:
  - hint

rules:
  unusedVariable: false  # Allow unused vars during development
  deprecatedApiUsage: true

level: 8
reportFormat: json
simpleReport: true

paths:
  - src

excludePaths:
  - vendor

# No exclusions - catch everything
excludeCategories: []
excludeSeverities: []

rules:
  # All rules enabled
  deprecatedApiUsage: true
  threadSafetyViolation: true

level: 6
reportFormat: html

paths:
  - src

excludeCategories:
  - deprecated_api  # Gradually fix deprecated API usage

excludeSeverities:
  - hint
  - info

baseline: retina-baseline.neon

​
See also

Build docs developers (and LLMs) love

Get started for freeTalk to us