Quick start

Your first scan

Let’s scan your first PocketMine-MP plugin with Retina. This guide assumes you’ve already installed Retina.

Navigate to your plugin directory

Open a terminal and change to your plugin’s root directory:

cd /path/to/your/plugin

Your plugin directory should contain a plugin.yml file. Retina will exit with an error if it doesn’t find one.

Run your first scan

Execute the scan command:

retina run

Retina will:

Validate your plugin.yml file
Analyze all PHP files in your plugin
Check for errors, deprecated API usage, and thread safety issues
Display a summary in your terminal
Generate a retina-report.md file

retina run

Review the results

After the scan completes, you’ll see a summary like this:

Retina - PocketMine-MP Plugin Scanner
Scanning: /path/to/your/plugin

Analyzing plugin...
✓ Found plugin.yml
✓ Analyzing 45 PHP files
✓ Running analyzers

⚠ Found 12 issue(s) in 5 file(s)

Summary
┌─────────────────────┬───────┐
│ Category            │ Count │
├─────────────────────┼───────┤
│ deprecated_api      │ 7     │
│ unused_variable     │ 3     │
│ undefined_method    │ 2     │
└─────────────────────┴───────┘

Total files scanned: 45
Total issues found: 12

✓ Report saved to: /path/to/your/plugin/retina-report.md

Open the detailed report

Open the generated report to see detailed findings:

# macOS
open retina-report.md

# Linux
xdg-open retina-report.md

# Windows
start retina-report.md

The report includes:

File paths and line numbers for each issue
Code snippets showing the problem
Severity levels (error, warning, info, hint)
Suggestions for fixing the issue

Configure your project

For ongoing use, create a configuration file to customize Retina’s behavior:

Initialize configuration

Create a retina.yml configuration file:

retina init

This creates a retina.yml file in your plugin directory with default settings.

Customize settings

Edit retina.yml to match your project’s needs:

retina.yml

# 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

# Exclude specific issue categories
excludeCategories:
  - unused_variable
  - unused_import

# Disable specific analyzers
excludeAnalyzers:
  - DeprecatedApi

# Exclude severity levels
excludeSeverities:
  - info
  - hint

Configuration file settings can be overridden by command-line options. CLI flags take precedence.

Run with configuration

Now when you run retina run, it will use your configuration:

retina run

The scan will respect all settings in retina.yml.

Common workflows

Quick console-only scan

For rapid feedback without generating a file:

retina run --console-only
# or
retina run -c

Create an interactive web-based report:

retina run --format html --output report.html
# or
retina run -f html -o report.html

Strict analysis for production

Run a rigorous scan before releasing:

retina run --level 9 --format json --output results.json
# or
retina run -l 9 -f json -o results.json

Focus on critical issues only

Exclude minor issues to focus on errors and warnings:

retina run --exclude-severities info,hint

Ignore unused code warnings

Exclude all unused variable/import/parameter warnings:

retina run --exclude-categories unused

Simple report for CI/CD

Generate a minimal report without code snippets:

retina run --simple --format json --output ci-results.json
# or
retina run -s -f json -o ci-results.json

Understanding command options

Retina’s run command supports numerous options for customization:

Output options

--format

string

default:"md"

Output format: md, json, txt, or html

retina run -f json

--output

string

default:"retina-report.<format>"

Custom output file path

retina run -o custom-report.md

--console-only

boolean

Print to console only, don’t create a file

retina run -c

--simple

boolean

Generate simplified report without code snippets

retina run -s

Analysis options

--level

integer

default:"6"

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

retina run -l 8

--no-progress

boolean

Disable progress output during scanning

retina run --no-progress

Filtering options

--exclude-categories

string

Comma-separated list of issue categories to exclude. Use presets: unused, undefined, pocketmine

retina run --exclude-categories unused_variable,unused_import
retina run --exclude-categories unused,undefined

--exclude-analyzers

string

Comma-separated list of analyzers to disable

retina run --exclude-analyzers DeprecatedApi,ThreadSafety

--exclude-severities

string

Comma-separated list of severity levels to exclude

retina run --exclude-severities info,hint

Report formats explained

Retina supports four report formats, each suited for different use cases:

Markdown (default)

Best for: Code review, documentationHuman-readable format with:

Code snippets with syntax highlighting
Severity badges
Actionable suggestions
Easy to read in GitHub, VS Code, or any Markdown viewer

retina run -f md

JSON

Best for: CI/CD integration, automationMachine-readable format with:

Structured issue data
Easy parsing in scripts
Integration with other tools
Perfect for build pipelines

retina run -f json

HTML

Best for: Sharing, presentationsInteractive web-based report with:

Filtering and search
Sortable tables
Click-to-expand details
Professional appearance

retina run -f html

Plain text

Best for: Console output, logsSimple text format with:

No formatting or colors
Easy to grep/search
Compatible with any text viewer
Lightweight output

retina run -f txt

Category presets

Retina provides convenient presets to exclude multiple related categories at once:

unused preset

Excludes all unused code warnings:

unused_variable
unused_parameter
unused_import

retina run --exclude-categories unused

undefined preset

Excludes all undefined reference warnings:

undefined_variable
undefined_method
undefined_class
undefined_constant
undefined_function
undefined_property

retina run --exclude-categories undefined

pocketmine preset

Excludes all PocketMine-MP specific categories:

invalid_event_handler
unregistered_listener
invalid_plugin_yml
deprecated_api
async_task_misuse
thread_safety
And more…

retina run --exclude-categories pocketmine

You can combine presets and individual categories: --exclude-categories unused,deprecated_api

Tips and best practices

Start with level 6

The default strictness level of 6 provides a good balance. Start here and adjust:

Lower levels (1-5): Faster scans, fewer false positives, misses some issues
Higher levels (7-9): More thorough, slower, may report minor issues

# Quick scan during development
retina run -l 4 -c

# Thorough scan before release
retina run -l 9

Use configuration files for teams

Commit retina.yml to your repository so all team members use the same settings:

retina.yml

level: 7
excludeCategories:
  - unused_variable
excludeSeverities:
  - hint

This ensures consistent code quality across your team.

Integrate with CI/CD

Add Retina to your continuous integration pipeline:

.github/workflows/analyze.yml

name: Static Analysis
on: [push, pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.1'
      - name: Install Retina
        run: |
          curl -sSL https://raw.githubusercontent.com/chinmay505/retina/main/install.sh | bash
      - name: Run analysis
        run: retina run -f json -o results.json
      - name: Upload results
        uses: actions/upload-artifact@v2
        with:
          name: analysis-results
          path: results.json

Focus on errors first

When starting with a legacy codebase, focus on critical issues:

# Only show errors and warnings
retina run --exclude-severities info,hint

Fix errors, then warnings, then gradually include info and hints.

Use simple reports for large codebases

For plugins with many files, simple reports are faster and easier to navigate:

retina run --simple

Simple reports show only:

File path and line number
Category and severity
Error message

No code snippets or suggestions (faster to generate and review).

Next steps

Command reference

Detailed documentation for all Retina commands

Configuration guide

Learn about all configuration options

Issue categories

Complete list of detectable issue categories

Analyzers

Deep dive into Retina’s 14 analyzers

Get Started

Core Concepts

Guides

Your first scan

Configure your project

Common workflows

Quick console-only scan

Strict analysis for production

Focus on critical issues only

Ignore unused code warnings

Simple report for CI/CD

Understanding command options

Output options

Analysis options

Filtering options

Report formats explained

Markdown (default)

JSON

HTML

Plain text

Category presets

Tips and best practices

Next steps

Command reference

Configuration guide

Issue categories

Analyzers

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Your first scan

​Configure your project

​Common workflows

​Quick console-only scan

​Generate HTML report for sharing

​Strict analysis for production

​Focus on critical issues only

​Ignore unused code warnings

​Simple report for CI/CD

​Understanding command options

​Output options

​Analysis options

​Filtering options

​Report formats explained

Markdown (default)

JSON

HTML

Plain text

​Category presets

​Tips and best practices

​Next steps

Command reference

Configuration guide

Issue categories

Analyzers

Build docs developers (and LLMs) love

Your first scan

Configure your project

Common workflows

Quick console-only scan

Generate HTML report for sharing

Strict analysis for production

Focus on critical issues only

Ignore unused code warnings

Simple report for CI/CD

Understanding command options

Output options

Analysis options

Filtering options

Report formats explained

Category presets

Tips and best practices

Next steps