monolog-gdpr-filter/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

Development

# Install dependencies
composer install

# Run all linting tools
composer lint

# Auto-fix code issues (runs Rector, Psalm fix, and PHPCBF)
composer lint:fix

# Run tests with coverage
composer test
composer test:coverage  # Generates HTML coverage report

# Individual linting tools
composer lint:tool:phpcs     # PHP_CodeSniffer
composer lint:tool:phpcbf    # PHP Code Beautifier and Fixer
composer lint:tool:psalm     # Static analysis
composer lint:tool:psalm:fix # Auto-fix Psalm issues
composer lint:tool:rector    # Code refactoring

# Preview changes before applying (dry-run)
composer lint:tool:rector -- --dry-run
composer lint:tool:psalm -- --alter --dry-run

# Check for hardcoded constant values
php check_for_constants.php           # Basic scan
php check_for_constants.php --verbose # Show line context

Testing

# Run all tests
composer test

# Run specific test file
./vendor/bin/phpunit tests/GdprProcessorTest.php

# Run specific test method
./vendor/bin/phpunit --filter testMethodName

Architecture

This is a Monolog processor library for GDPR compliance that masks sensitive data in logs.

Core Components

1. GdprProcessor (src/GdprProcessor.php): The main processor implementing Monolog's ProcessorInterface

   • Processes log records to mask/remove/replace sensitive data
   • Supports regex patterns, field paths (dot notation), and custom callbacks
   • Provides static factory methods for common field configurations
   • Includes default GDPR patterns (SSN, credit cards, emails, etc.)

2. FieldMaskConfig (src/FieldMaskConfig.php): Configuration value object with three types:

   • MASK_REGEX: Apply regex patterns to field value
   • REMOVE: Remove field entirely from context
   • REPLACE: Replace with static value

Key Design Patterns

• Processor Pattern: Implements Monolog's ProcessorInterface for log record transformation
• Value Objects: FieldMaskConfig is immutable configuration
• Factory Methods: Static methods for creating common configurations
• Dot Notation: Uses adbario/php-dot-notation for nested array access (e.g., "user.email")

Laravel Integration

The library can be integrated with Laravel in two ways:

1. Service Provider registration
2. Using a Tap class to modify logging channels

Code Standards

• PHP 8.4+ with strict types
• PSR-12 coding standard (enforced by PHP_CodeSniffer)
• Psalm Level 5 static analysis with conservative configuration
• PHPStan Level 6 for additional code quality insights
• Rector for safe automated code improvements
• EditorConfig: 4 spaces, LF line endings, UTF-8, trim trailing whitespace
• PHPUnit 11 for testing with strict configuration

Static Analysis & Linting Policy

All issues reported by static analysis tools MUST be fixed. The project uses a comprehensive static analysis setup:

• Psalm: Conservative Level 5 with targeted suppressions for valid patterns
• PHPStan: Level 6 analysis with Laravel compatibility
• Rector: Safe automated improvements (return types, string casting, etc.)
• PHPCS: PSR-12 compliance enforcement
• SonarQube: Cloud-based code quality and security analysis (quality gate must pass)

Issue Resolution Priority:

1. Fix the underlying issue (preferred approach)
2. Refactor code to avoid the issue pattern
3. Use safe automated fixes via composer lint:fix
4. Ask before suppressing - Suppression should be used only as an absolute last resort and requires explicit discussion

Zero-Tolerance Policy:

• ALL issues must be addressed - this includes ERROR, WARNING, and INFO level issues
• INFO-level issues are NOT acceptable - they indicate potential problems that should be resolved
• Never ignore or suppress issues without explicit approval and documented justification
• Psalm INFO messages should be addressed by:
  • Refactoring code to avoid the pattern
  • Adding proper type hints and assertions
  • Using @psalm-suppress ONLY when absolutely necessary and with clear comments explaining why
• Exit code must be 0 - any non-zero exit from linting tools is a failure

Tip: Use git stash before running composer lint:fix to easily revert changes if needed.

SonarQube-Specific Guidelines

SonarQube is a static analysis tool that analyzes code structure, not runtime behavior. Unlike human reviewers, it does NOT understand:

• PHPUnit's expectException() mechanism
• Test intent or context
• Comments explaining why code is written a certain way

Common SonarQube issues and their fixes:

1. S1848: Useless object instantiation

   • Issue: new ClassName() in tests that expect exceptions
   • Why it occurs: SonarQube doesn't understand expectException() means the object creation is the test
   • Fix: Assign to variable and add assertion: $obj = new ClassName(); $this->assertInstanceOf(...)

2. S4833: Replace require_once with use statement

   • Issue: Direct file inclusion instead of autoloading
   • Fix: Use composer's autoloader and proper use statements

3. S1172: Remove unused function parameter

   • Issue: Callback parameters that aren't used in the function body
   • Fix: Remove unused parameters from function signature

4. S112: Define dedicated exception instead of generic one

   • Issue: Throwing \RuntimeException or \Exception directly
   • Fix: Use project-specific exceptions like RuleExecutionException, MaskingOperationFailedException

5. S1192: Define constant instead of duplicating literal

   • Issue: String/number literals repeated 3+ times
   • Fix: Add to TestConstants or MaskConstants and use the constant reference

6. S1481: Remove unused local variable

   • Issue: Variable assigned but never read
   • Fix: Remove assignment or use the variable

IMPORTANT: Comments and docblocks do NOT fix SonarQube issues. The code structure itself must be changed.

Code Quality

Constant Usage

To reduce code duplication and improve maintainability (as required by SonarQube), the project uses centralized constants:

• MaskConstants (src/MaskConstants.php): Mask replacement values (e.g., MASK_MASKED, MASK_REDACTED)
• TestConstants (tests/TestConstants.php): Test data values, patterns, field paths, messages

Always use constants instead of hardcoded strings for values defined in these files. Use the constant checker to identify hardcoded values:

# Scan for hardcoded constant values
php check_for_constants.php

# Show line context for each match
php check_for_constants.php --verbose

The checker intelligently scans all PHP files and reports where constant references should be used:

• MaskConstants checked in both src/ and tests/ directories
• TestConstants checked only in tests/ directory (not enforced in production code)
• Filters out common false positives like array keys and internal identifiers
• Helps maintain SonarQube code quality standards

Important Notes

• Always run composer lint:fix before manual fixes
• Fix all linting issues - suppression requires explicit approval
• Use constants instead of hardcoded values - run php check_for_constants.php to verify
• The library focuses on GDPR compliance - be careful when modifying masking logic
• Default patterns include Finnish SSN, US SSN, IBAN, credit cards, emails, phones, and IPs
• Audit logging feature can track when sensitive data was masked for compliance
• All static analysis tools are configured to work harmoniously without conflicts