Usage Guide

Learn how to use Sentinel AI to analyze your PHP code and generate comprehensive reports with categorized auto-fixing capabilities.

Basic Usage

Sentinel AI provides a simple command-line interface for running code analysis:

# Basic analysis
sentinel analyze src/

# Auto-fix issues interactively
sentinel autofix src/ --interactive

# Generate HTML report
sentinel analyze src/ --format=html --output=report.html

# Check specific file
sentinel analyze app/Models/User.php

# Show help
sentinel --help

Command Line Options

Analysis Types

Static Code Analysis

Comprehensive analysis using multiple tools:

sentinel analyze src/

This includes:

• PHP_CodeSniffer - PSR-12 coding standards and style checking
• PHPStan - Advanced static analysis for type safety
• PhpMetrics - Code quality metrics and complexity analysis
• Custom Duplicate Detection - Identifies copy-pasted code
• Framework-Aware Analysis - Automatic detection and configuration

Categorized Auto-Fix System

Risk-based auto-fixing with interactive mode:

# Interactive auto-fix (recommended)
sentinel autofix src/ --interactive

# Force auto-fix (skip confirmations)
sentinel autofix src/ --force

# Preview changes only
sentinel autofix src/ --dry-run

# Fix specific categories
sentinel autofix src/ --categories=low,medium

Risk Categories:

• LOW: Safe style fixes, formatting changes
• MEDIUM: Code structure improvements, unused variable removal
• HIGH: Logic changes, import reorganization

Cache Management

Intelligent caching for faster repeated analysis:

# Show cache status
sentinel cache --status

# Clear all cache
sentinel cache --clear

# Clear cache for specific tool
sentinel cache --clear-tool phpcs

# Show cache statistics
sentinel cache --stats

Framework Support

Sentinel AI automatically detects and configures analysis for popular PHP frameworks:

Manual Framework Override

# Override automatic detection
sentinel analyze /path/to/project --framework=laravel

# Available frameworks: laravel, symfony, codeigniter, cakephp, laminas, yii

Output Formats

HTML Reports

Generate beautiful, interactive HTML reports:

sentinel analyze src/ --format=html --output=analysis-report.html

HTML reports include:

• Interactive navigation and filtering
• Code highlighting and line numbers
• Issue categorization and severity levels
• Code quality metrics and trends
• Export capabilities

JSON Output

For integration with CI/CD and other tools:

sentinel analyze src/ --format=json --output=results.json

Text Output

Simple text format for terminal or logs:

sentinel analyze src/ --format=text

CI/CD Integration

Sentinel AI integrates seamlessly with CI/CD pipelines:

GitHub Actions

Add to your workflow:

- name: Run Sentinel AI Analysis
  run: |
    curl -sSL https://raw.githubusercontent.com/abdulbaquee/sentinel-ai-releases/main/releases/v1.0.6/install.sh | bash
    sentinel analyze src/ --format=json --output=analysis.json
    sentinel autofix src/ --force
    sentinel analyze src/ --no-cache

GitLab CI

Add to your pipeline:

sentinel_analysis:
  script:
    - curl -sSL https://raw.githubusercontent.com/abdulbaquee/sentinel-ai-releases/main/releases/v1.0.6/install.sh | bash
    - sentinel analyze src/ --format=html --output=report.html
    - sentinel autofix src/ --force
  artifacts:
    paths:
      - report.html

Configuration

Customize Sentinel AI behavior through configuration:

// .sentinel/config.php
return [
    'analysis' => [
        'tools' => ['phpcs', 'phpstan', 'phpmd', 'phpcpd'],
        'exclude' => ['vendor/*', 'node_modules/*', 'tests/*'],
        'max_file_size' => '1MB',
        'timeout' => 300,
    ],
    'output' => [
        'format' => 'html',
        'directory' => 'reports/',
        'include_metrics' => true,
    ],
    'fixes' => [
        'auto_fix' => true,
        'interactive' => false,
        'backup_files' => true,
        'risk_levels' => ['low', 'medium'],
    ],
    'cache' => [
        'enabled' => true,
        'directory' => '.sentinel/cache/',
        'ttl' => 3600,
    ],
    'frameworks' => [
        'auto_detect' => true,
        'manual_override' => null,
    ],
];

Real-World Examples

Example 1: Daily Code Review

# Every morning, review your changes
cd /path/to/your/project
sentinel analyze

# Fix any style issues automatically
sentinel autofix . --force

# Check if everything is clean
sentinel analyze --no-cache

Example 2: Before Committing

# Add this to your pre-commit hook
#!/bin/bash
sentinel analyze . --timeout=30
if [ $? -ne 0 ]; then
    echo "❌ Code review failed! Fix issues before committing."
    exit 1
fi
echo "✅ Code review passed!"

Example 3: CI/CD Pipeline

# In your GitHub Actions workflow
- name: Code Review
  run: |
    sentinel analyze . --timeout=60
    sentinel autofix . --force
    sentinel analyze . --no-cache

Interpreting Results

Issue Severity Levels

Reading the Output

Sentinel AI
===========

Analyzing: /path/to/your/project
----------------------------------------

PHP_CodeSniffer Results: Found 5 errors and 12 warnings.
PHPStan Results: Found 0 issues.
PhpMetrics Results: Average Complexity: 15.2
PHPCpd Results: Found 8 duplicated blocks.

[OK] HTML report generated: /path/to/report.html

Performance Optimization

Intelligent Caching

• File-Based Caching: Uses SHA256 hashes to detect file changes
• Incremental Analysis: Only re-analyzes modified files
• Tool-Specific Caches: Separate caches for each analysis tool
• Automatic Invalidation: Cache invalidates when files or rules change

Optimization Tips

• Use cache: Enable caching for faster repeated analysis
• Exclude directories: Ignore vendor, node_modules, and test directories
• Set timeouts: Configure appropriate timeouts for your project size
• Parallel processing: Multiple tools run concurrently by default

Best Practices

• Run analysis frequently: Use during development for immediate feedback
• Use interactive mode: Review fixes before applying them
• Leverage caching: Enable intelligent caching for faster analysis
• Review HTML reports: Detailed analysis with context and suggestions
• Integrate with CI/CD: Automated analysis in your deployment pipeline
• Configure exclusions: Exclude vendor and test directories for faster analysis
• Use framework detection: Let Sentinel AI automatically detect your framework
• Set up pre-commit hooks: Catch issues before they reach the repository

Next Steps

Now that you understand the basics:

• Learn about custom rules
• Configure your project settings
• Set up CI/CD integration
• Create team-specific analysis profiles
• Explore advanced features and customization