Download the PHP package shieldci/analyzers-core without Composer

ShieldCI Analyzers Core

Shared foundation for building static analysis tools. Includes abstract analyzer classes, result formatters, file parsers, and utilities.

Features

• Framework Agnostic: Works with any PHP 8.1+ project
• Type Safe: Full type hints and strict typing
• Extensible: Easy to create custom analyzers
• Well Tested: Comprehensive test suite (100% coverage)
• Modern PHP: Uses PHP 8.1+ features
• Laravel Compatible: Works with Laravel 9.x, 10.x, 11.x, 12.x and 13.x

Requirements

• PHP 8.1 or higher
• Composer

Installation

Architecture

Core Components

1. Interfaces

   • AnalyzerInterface - Contract for all analyzers
   • ResultInterface - Contract for analysis results
   • ReporterInterface - Contract for result formatters
   • ParserInterface - Contract for code parsers

2. Abstract Base Classes

   • AbstractAnalyzer - Base class with timing, error handling, and helper methods
   • AbstractFileAnalyzer - Base class for file-based analyzers with file filtering

3. Value Objects

   • Location - Represents a code location (file, line, column)
   • Issue - Represents a specific issue found
   • CodeSnippet - Represents a code snippet with context lines
   • AnalyzerMetadata - Metadata about an analyzer

4. Results

   • AnalysisResult - Result of running a single analyzer
   • ResultCollection - Collection of analysis results

5. Utilities

   • AstParser - AST parsing using nikic/php-parser
   • FileParser - File content parsing utilities
   • CodeHelper - Code analysis helpers
   • ConfigFileHelper - Laravel configuration file utilities
   • MessageHelper - Error message sanitization (redacts credentials, tokens, IPs)
   • InlineSuppressionParser - Parses @shieldci-ignore inline suppression comments
6. Formatters
   • JsonFormatter - Format results as JSON
   • ConsoleFormatter - Format results for console output

Usage

Creating a Custom Analyzer

Running an Analyzer

Using Result Collection

Formatting Results

Using the AST Parser

Using Code Helpers

Using Code Snippets

The CodeSnippet value object provides rich code context for issues with several advanced features:

Advanced Features:

1. Smart Context Expansion

   • Automatically detects method/class signatures above the target line
   • Expands context to include signature if within 15 lines
   • Provides crucial context for understanding where issues occur
   • Detects: classes, interfaces, traits, enums, public/protected/private methods

2. Configurable Context

   • Default: 8 lines before and after target line
   • Customizable via contextLines parameter
   • Automatically handles file boundaries

3. Line Truncation

   • Truncates long lines to 250 characters to prevent terminal wrapping
   • Preserves readability in console output
4. Null Safety
   • Returns null if file doesn't exist or can't be read
   • Graceful error handling for runtime exceptions

Example with Issue:

Smart Context Expansion Example:

Using Config File Helper

The ConfigFileHelper utility provides powerful methods for working with Laravel configuration files, particularly useful for analyzers that need to report issues in config files with precise line numbers.

Advanced Features:

1. Comment-Aware Searching

   • Automatically strips single-line comments (//, #)
   • Avoids false positives from commented-out config

2. Precise Pattern Matching

   • Uses regex to match exact array key patterns: 'key' => or "key" =>
   • Handles various spacing: 'key'=> or 'key' =>
   • Avoids matching keys in string values or comments

3. Nested Array Navigation

   • Can search within parent arrays using parentKey parameter
   • Detects when entering/exiting parent array boundaries
   • Handles nested array structures like connections, stores, etc.

4. Smart Indentation Detection

   • Uses indentation level to determine array nesting
   • Stops searching when encountering top-level keys outside target scope
   • Prevents false matches in unrelated config sections
5. Fallback Support
   • Returns line 1 if key not found (safe default)
   • Supports optional Laravel config_path() fallback for non-Laravel environments

Use Cases:

• Database Analyzers: Find connection settings, driver configurations
• Cache Analyzers: Locate cache store configurations, driver settings
• Session Analyzers: Find session driver, lifetime, security settings
• Queue Analyzers: Locate queue connection, driver configurations
• Mail Analyzers: Find mail driver, encryption settings

Parsing Config Arrays

ConfigFileHelper::parseConfigArray() parses a PHP config file that returns an array and extracts the top-level key–value pairs via AST — no regex, no fragile text matching.

Example — checking session cookie security:

Supported value types:

Stripping PHP Comments

FileParser::stripAllComments() removes all PHP comment styles from source code using the tokenizer — correctly handling comments inside strings, URLs, docblocks, and multiline blocks.

Unlike FileParser::stripComments() (which works on single lines via regex and breaks on URLs), stripAllComments() uses token_get_all() and handles arbitrary PHP source correctly.

Sanitizing Error Messages

MessageHelper::sanitizeErrorMessage() redacts sensitive values from error messages before they appear in analyzer recommendations — preventing credentials and tokens from leaking into reports.

Redacted patterns:

Parsing Inline Suppressions

InlineSuppressionParser parses // @shieldci-ignore comments to determine whether a given line should suppress a specific analyzer rule.

Supported suppression styles:

Enums

ShieldCI Analyzers Core provides three powerful enums with rich helper methods for better developer experience.

Status

Represents the result status of an analyzer execution.

Cases:

• Status::Passed - Analysis completed successfully with no issues
• Status::Failed - Analysis found critical issues that need fixing
• Status::Warning - Analysis found warnings that should be reviewed
• Status::Skipped - Analysis was skipped (not applicable)
• Status::Error - Analysis encountered an error during execution

Category

Represents the category/type of an analyzer.

Cases:

• Category::Security - Security vulnerabilities and risks (🔒)
• Category::Performance - Performance issues and optimizations (⚡)
• Category::CodeQuality - Code quality and maintainability (📊)
• Category::BestPractices - Best practices and conventions (✨)
• Category::Reliability - Reliability and stability issues (🛡️)

Severity

Represents the severity level of an issue.

Cases:

• Severity::Critical - Critical security or stability issue requiring immediate attention
• Severity::High - High priority issue that should be addressed soon
• Severity::Medium - Medium priority issue that should be considered
• Severity::Low - Low priority issue or minor improvement
• Severity::Info - Informational message or suggestion

Testing

Directory Structure

Used By

• shieldci/laravel - Free Laravel analyzer package
• shieldci/laravel-pro - Pro Laravel analyzer package

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License. See LICENSE file for details.

Credits

Built by the ShieldCI team.