A comprehensive Laravel code scanner that detects security vulnerabilities, performance issues, and code quality problems with a modern web interface and AI-powered auto-fix capabilities.
β οΈ Important: This package is designed for local development environments only. It is not recommended for production use.
- β¨ Features
- π Requirements
- π Installation
- β‘ Quick Start
- βοΈ Configuration
- π Scanning Categories
- π€ AI Integration
- π Current Status
- οΏ½οΈ Roadmap
- οΏ½π Package Structure
- π€ Contributing
- π Security
- π License
π Comprehensive Scanning
- β Security vulnerability detection (SQL injection, XSS, hardcoded credentials)
- β Performance optimization suggestions (N+1 queries, missing indexes, cache opportunities)
- β Code quality analysis (complexity, naming conventions, documentation)
- β Laravel best practices enforcement (Eloquent, routes, validation)
- β Blade template analysis (XSS protection, CSRF, accessibility, SEO)
- β Context-aware exception handling for inheritance and constants
π¨ Modern Web Interface
- β Complete dark/light mode support with user preferences
- β Livewire-powered interactive dashboard with expandable details
- β Tailwind CSS styling with responsive design and modern hover effects
- β Real-time filtering, sorting, and bulk operations
- β Enhanced file grouping with collapsible sections and smooth animations
π Flexible Scanning Options
- β Single file scanning with detailed analysis
- β Directory scanning with exclusion patterns
- β Full codebase scanning with progress tracking
- β Category-based filtering (security, performance, quality, laravel)
- β Intelligent queue management with auto-start functionality
- β Real-time queue status monitoring and automatic worker detection
- β Queue worker protection - Prevents job dispatch when worker not running, saves AI tokens
π§ Developer Integration
- β Comprehensive Artisan commands with flexible options
- β Export capabilities (JSON, CSV, database storage)
- β Detailed reports with code context and suggestions
- β Configuration-driven behavior with extensive options
- β Automatic queue detection and management for background processing
π€ AI Smart Assistant
- β Complete AI-powered chat interface for code scanning assistance
- β OpenAI integration with conversation management
- β Context-aware suggestions, tips, and best practices
- β Real-time markdown rendering with code syntax highlighting
- β Dark/light mode optimized interface with smooth scrolling
π€ AI-Ready Architecture
- β Professional chat interface with loading indicators
- β Robust response processing for complex AI output
- β UTF-8 character support and encoding handling
- π§ Context-aware suggestion framework (expandable)
- π§ Safe code generation with preview system (coming soon)
- π§ Cost tracking and safety limits (planned)
-
PHP: 8.1 or higher with required extensions:
mbstring- Multi-byte string handlingcurl- API requests and HTTP communicationxml- XML parsing for configurationzip- Archive handlingbcmath- Arbitrary precision mathematicstokenizer- PHP code tokenization for scanningjson- JSON encoding/decodingpdo- Database connectivityfileinfo- File type detection
-
Laravel: 10.0, 11.0, or 12.0
- Livewire 2.x or 3.x (automatically installed)
- Alpine.js (included with Livewire)
-
Database (for local development):
- MySQL 5.7+ / MariaDB 10.3+
- PostgreSQL 10+
- SQLite 3.8+
- Minimum 50MB free space for scan results
-
Local Environment:
- Minimum 512MB RAM (1GB+ recommended)
- PHP
max_execution_timeβ₯ 300 seconds (for large scans) - Two terminal windows (one for app, one for queue worker)
- PHP
memory_limitβ₯ 256MB (512MB+ recommended) - Disk space: 100MB+ for package and scan data
CRITICAL: The AI Auto-Fix and Fix All features require proper queue and cache configuration:
- β
Supported:
file,redis,database - β NOT Supported:
array(doesn't persist across processes) - Why: Queue workers and web interface must share progress data
- β
Supported:
database,redis,beanstalkd,sqs - β NOT Supported:
sync(blocks the interface) - Why: AI fixes run in background to prevent timeouts
- Must have at least one worker running:
php artisan queue:work - Supervisor recommended for production
- CodeSnoutr includes automatic worker detection
To use AI-powered automatic fixing:
-
OpenAI Account: platform.openai.com
- Valid API key with access to GPT-4 or GPT-3.5
- Minimum $5 credit balance recommended
- Rate limits: See OpenAI tier documentation
-
Internet Connection: Stable connection for API requests
-
Recommended Models:
gpt-4- Best quality, higher cost (~$0.03/issue)gpt-4-turbo- Faster, more cost-effective (~$0.01/issue)gpt-3.5-turbo- Budget option (~$0.002/issue)
-
Cost Estimation:
- Small project (50 issues): $0.10 - $1.50
- Medium project (200 issues): $0.40 - $6.00
- Large project (1000 issues): $2.00 - $30.00
-
Modern Browser:
- Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
- JavaScript enabled
- LocalStorage enabled (for theme preferences)
-
Screen Resolution: 1024x768 minimum (responsive design)
Before installing CodeSnoutr, ensure your system meets these requirements:
- PHP: 8.1 or higher with the following extensions:
mbstring,curl,xml,zip,bcmath,tokenizer
- Laravel: 10.0, 11.0, or 12.0
- Database: MySQL 5.7+, PostgreSQL 10+, or SQLite 3.8+
- Composer: Latest version recommended
- Frontend: Modern browser with JavaScript enabled
Install the package using Composer:
composer require rafaelogic/codesnoutrExecute the installation command to set up CodeSnoutr:
php artisan codesnoutr:installThis interactive installation will:
- Publish Configuration: Creates
config/codesnoutr.phpwith default settings - Run Migrations: Sets up database tables for scans, issues, and settings
- Publish Assets: Copies CSS and JavaScript files to
public/vendor/codesnoutr/ - Create Directories: Sets up necessary storage directories
- Configure Routes: Registers web and API routes
- Set Permissions: Ensures proper file permissions
Add CodeSnoutr-specific environment variables to your .env file:
# Basic Configuration
CODESNOUTR_ENABLED=true
# Queue Management (Recommended for Better Performance)
CODESNOUTR_QUEUE_ENABLED=true
CODESNOUTR_QUEUE_CONNECTION=database
CODESNOUTR_QUEUE_AUTO_START=true
# Cache Driver (REQUIRED for Fix All Progress Tracking)
# β οΈ CRITICAL: Do NOT use 'array' driver - it doesn't persist between processes!
CACHE_DRIVER=file # Recommended for development
# CACHE_DRIVER=redis # Recommended for production
# CACHE_DRIVER=database # Alternative if you have cache table
# Queue Driver (Required for Background Processing)
QUEUE_CONNECTION=database # Recommended for most cases
# QUEUE_CONNECTION=redis # Better for high-volume production
# AI Integration (Optional)
CODESNOUTR_AI_ENABLED=false
OPENAI_API_KEY=your_openai_api_key_here
CODESNOUTR_AI_MODEL=gpt-4
# Security & Access
CODESNOUTR_ACCESS_MIDDLEWARE=web
β οΈ Important Cache ConfigurationThe Fix All Issues feature requires a persistent cache driver to track progress between the queue worker and web interface. The
arraycache driver will NOT work because it's per-process memory and doesn't share data between processes.Supported Cache Drivers:
- β
file- Works out of the box, good for development- β
redis- Best performance, recommended for production- β
database- Requiresphp artisan cache:table && php artisan migrate- β
array- Does NOT work (no cross-process sharing)Why This Matters:
- Queue workers run in separate processes from your web server
- Progress updates must be shared between these processes
- Without proper cache driver, progress bars won't update
- AI fixes may waste tokens if jobs run unexpectedly
β οΈ Important: CodeSnoutr is designed for local development environments only. Do not use in production.
For the Fix All Issues feature to work properly, you MUST configure both queue and cache drivers:
# 1. Set cache driver in .env (DO NOT use 'array')
CACHE_DRIVER=file
# 2. Set queue driver in .env
QUEUE_CONNECTION=database
# 3. If using database queue, create the table (only once)
php artisan queue:table
php artisan migrate
# 4. Start queue worker in a separate terminal (required for background processing)
php artisan queue:work --verbose --timeout=300The Fix All progress tracking requires a cache driver that persists across processes:
| Driver | Status | Setup | Use Case |
|---|---|---|---|
| file | β Recommended | Works out of box | Local development |
| database | β Supported | Run php artisan cache:table |
Alternative option |
| array | β Won't Work | N/A | Queue workers can't share data |
Why This Matters:
Web Server Process Queue Worker Process
β β
[Read Progress] ββββ [Shared Cache] ββββ [Write Progress]
(file/database)
β With 'array': Each process has its own memory - NO SHARING
β
With 'file': Both read/write to same file - WORKS
Open a new terminal window and run:
# Start queue worker (keep this running)
php artisan queue:work --verbose --timeout=300Tips:
- Keep the queue worker running in a separate terminal
- Use
--verboseflag to see jobs being processed - Press
Ctrl+Cto stop the worker when done - Restart worker after code changes to pick up new code
CodeSnoutr includes automatic queue worker detection to prevent wasting AI tokens:
- β Before Fix All: Checks if queue worker is running
- β Blocks Dispatch: If no worker detected, shows error with instructions
- π° Saves Tokens: Prevents jobs from accumulating and running unexpectedly
- π User Notification: Clear error message with recommendations
What You'll See:
β Queue Worker Not Running
Cannot dispatch Fix All job. Jobs would accumulate and run
unexpectedly later, wasting AI tokens.
Recommendations:
β Start queue worker: php artisan queue:work
β Or run synchronously: Use "Run Fix All (Sync)" button
β Or enable auto-start in config: CODESNOUTR_QUEUE_AUTO_START=true
The Fix All feature includes comprehensive logging:
Browser Console (F12):
π wire:poll #5 (1000ms since last)
β
Changes detected: currentStep: 2β3, fixedCount: 0β1Laravel Logs:
# Watch progress updates in real-time
tail -f storage/logs/laravel.log | grep "wire:poll"
# Or use the provided monitoring script
./watch_poll_logs.shTroubleshooting:
# Check if queue worker is running
ps aux | grep "queue:work"
# Check failed jobs
php artisan queue:failed
# Clear failed jobs
php artisan queue:flush
# Restart queue worker
php artisan queue:restartNavigate to the CodeSnoutr dashboard:
http://your-app.com/codesnoutr
You should see:
- β Dashboard with welcome message
- β Navigation menu with all sections
- β Dark/light mode toggle
- β Ready-to-use scanning interface
# Fix storage permissions
chmod -R 755 storage/
chown -R www-data:www-data storage/
# Fix published assets permissions
chmod -R 755 public/vendor/codesnoutr/# Re-run migrations if needed
php artisan migrate:refresh
# Check database connection
php artisan tinker
>>> \DB::connection()->getPdo()# Force republish assets
php artisan vendor:publish --tag=codesnoutr-assets --force
# Clear and rebuild cache
php artisan config:clear
php artisan route:clear
php artisan view:clear
php artisan cache:clearImportant: CodeSnoutr now includes queue worker protection to prevent wasting AI tokens. If you try to run Fix All without a queue worker running, you'll see an error message and the job will not be dispatched.
# Check queue status
php artisan queue:status
# Restart queue workers
php artisan queue:restart
# Test queue functionality
php artisan queue:work --once
# Start queue worker for Fix All jobs
php artisan queue:work --verboseWhy This Matters:
- Prevents jobs from being queued when they can't execute
- Saves AI API tokens by not dispatching unprocessable jobs
- Provides immediate feedback when queue worker is missing
- Clear instructions on how to start the worker
See QUEUE_WORKER_PROTECTION.md for detailed documentation.
If you prefer manual installation or need custom configuration:
# Publish configuration only
php artisan vendor:publish --tag=codesnoutr-config
# Publish assets only
php artisan vendor:publish --tag=codesnoutr-assets
# Publish migrations only
php artisan vendor:publish --tag=codesnoutr-migrations
# Publish all at once
php artisan vendor:publish --provider="Rafaelogic\CodeSnoutr\CodeSnoutrServiceProvider"php artisan migrateIf you want to customize routes, add to your routes/web.php:
Route::group(['prefix' => 'code-scanner', 'middleware' => ['web', 'auth']], function () {
require base_path('vendor/rafaelogic/codesnoutr/routes/web.php');
});When updating to a new version:
# Update the package
composer update rafaelogic/codesnoutr
# Republish assets and config
php artisan vendor:publish --tag=codesnoutr-assets --force
php artisan vendor:publish --tag=codesnoutr-config --force
# Run any new migrations
php artisan migrate
# Clear caches
php artisan config:clear
php artisan view:clear
php artisan route:clearTo completely remove CodeSnoutr:
# Remove the package
composer remove rafaelogic/codesnoutr
# Remove database tables (optional)
php artisan migrate:rollback --path=database/migrations/codesnoutr
# Remove published files (optional)
rm -rf config/codesnoutr.php
rm -rf public/vendor/codesnoutr/
# Clear caches
php artisan config:clear
php artisan route:clear
php artisan view:clearFor Docker environments, add to your Dockerfile:
# Install CodeSnoutr
RUN composer require rafaelogic/codesnoutr
# Install and configure
RUN php artisan codesnoutr:install --no-interaction
# Set up queue worker (add to supervisord.conf)
COPY docker/supervisord/codesnoutr.conf /etc/supervisor/conf.d/For production environments:
- Optimize Performance:
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan optimize- Set Up Monitoring:
# Monitor queue workers
php artisan horizon # If using Laravel Horizon- Configure Logging:
// In config/logging.php
'channels' => [
'codesnoutr' => [
'driver' => 'daily',
'path' => storage_path('logs/codesnoutr.log'),
'level' => 'info',
'days' => 7,
],
],- Set Up Scheduled Tasks (Optional):
// In app/Console/Kernel.php
protected function schedule(Schedule $schedule)
{
// Schedule periodic scans
$schedule->command('codesnoutr:scan codebase --save')
->daily()
->withoutOverlapping();
}After installation, get your first scan results immediately:
# Scan a single file for quick testing
php artisan codesnoutr:scan file app/Models/User.php
# Or scan your entire application
php artisan codesnoutr:scan codebase --save-
Open the Dashboard: Visit
http://your-app.com/codesnoutr -
Start Your First Scan:
- Click "New Scan" or "Scan Wizard"
- Choose scan type: File, Directory, or Full Codebase
- Select categories: Security, Performance, Quality, Laravel
- Click "Start Scan"
-
View Results:
- Real-time progress updates during scanning
- Automatic redirect to results when complete
- Filter by severity: Critical, High, Medium, Low, Info
- Expand issue groups for detailed analysis
-
Explore Features:
- Dark Mode: Toggle in the top navigation
- AI Assistant: Click the floating AI button (with OpenAI configured)
- Export: Download results as JSON or CSV
- Settings: Configure scanning preferences
# Focus on security issues only
php artisan codesnoutr:scan codebase --categories=security --format=json# Check for N+1 queries and performance issues
php artisan codesnoutr:scan codebase --categories=performance# Analyze code quality and Laravel best practices
php artisan codesnoutr:scan directory app --categories=quality,laravel# Comprehensive scan before deployment
php artisan codesnoutr:scan codebase --save --export-path=deployment-report.jsonAccess your CodeSnoutr dashboard:
http://your-app.com/codesnoutr
The web interface provides:
- Dashboard: Overview with statistics and recent scans
- Scanner: Interactive scanning with real-time progress and automatic queue management
- Results: Advanced filtering, sorting, and issue management with expandable details
- AI Assistant: Smart chat interface for code scanning help and best practices
- Settings: Configuration management and AI setup
CodeSnoutr provides a seamless scanning experience with modern UI/UX features:
- Smart File Grouping: Issues are intelligently grouped by file with collapsible sections
- Expandable Details: Click to expand issue details in the detailed table view
- Modern Hover Effects: Elegant glow border effects provide visual feedback
- Automatic Redirects: Smooth workflow transitions after resolving issues
- Real-Time Updates: Live status updates without page refreshes
- Responsive Design: Works perfectly on desktop, tablet, and mobile devices
CodeSnoutr intelligently manages Laravel queues for optimal performance:
- Auto-Detection: Automatically checks if queue workers are running before starting scans
- Smart Start: Launches queue workers automatically if none are detected
- Real-Time Status: Shows queue status during scan preparation
- Background Processing: All scans run in background jobs for better performance
- Progress Tracking: Real-time updates without blocking the UI
No Configuration Required: Queue management works out-of-the-box with sensible defaults. Customize behavior in config/codesnoutr.php if needed.
The AI Assistant provides intelligent help throughout your code scanning experience:
- Context-Aware Conversations: Ask questions about code scanning, security, performance, and Laravel best practices
- Real-Time Markdown Rendering: Beautiful formatting for code examples, bullet points, and structured responses
- Smart Suggestions: Get personalized tips based on your current scanning context
- Code Examples: Interactive code snippets with syntax highlighting
- Best Practices: Expert advice on PHP/Laravel development standards
Access the AI Assistant: Look for the floating AI button in the bottom-right corner of the interface, or navigate to any CodeSnoutr page where it's available as a slide-out panel.
Configuration: Set up your OpenAI API key in Settings β AI Integration to unlock the full potential of AI-powered assistance.
Scan entire codebase:
php artisan codesnoutr:scan codebaseScan specific file:
php artisan codesnoutr:scan file app/Models/User.phpScan directory:
php artisan codesnoutr:scan directory app/ModelsFilter by categories:
php artisan codesnoutr:scan codebase --categories=security,performanceExport results:
# Export as JSON
php artisan codesnoutr:scan codebase --format=json --export-path=results.json
# Export as CSV
php artisan codesnoutr:scan codebase --format=csv --export-path=results.csv
# Save to database (default)
php artisan codesnoutr:scan codebase --saveThe configuration file is published to config/codesnoutr.php with comprehensive options:
return [
'enabled' => env('CODESNOUTR_ENABLED', true),
// Scanning configuration
'scan' => [
'paths' => ['app', 'config', 'routes', 'database/migrations', 'resources/views'],
'exclude_paths' => ['vendor', 'node_modules', 'storage', 'bootstrap/cache'],
'file_extensions' => ['php', 'blade.php'],
'max_file_size' => 1024 * 1024, // 1MB
'timeout' => 300, // 5 minutes
],
// Queue management configuration
'queue' => [
'enabled' => env('CODESNOUTR_QUEUE_ENABLED', true),
'name' => env('CODESNOUTR_QUEUE_NAME', 'default'),
'connection' => env('CODESNOUTR_QUEUE_CONNECTION', config('queue.default')),
'auto_start' => env('CODESNOUTR_QUEUE_AUTO_START', true),
'timeout' => env('CODESNOUTR_QUEUE_TIMEOUT', 300),
'memory' => env('CODESNOUTR_QUEUE_MEMORY', 512),
],
// Scanner rules configuration
'scanners' => [
'security' => ['enabled' => true, 'rules' => [...]],
'performance' => ['enabled' => true, 'rules' => [...]],
'quality' => ['enabled' => true, 'rules' => [...]],
'laravel' => ['enabled' => true, 'rules' => [...]],
],
// AI integration (ready for implementation)
'ai' => [
'enabled' => env('CODESNOUTR_AI_ENABLED', false),
'provider' => env('CODESNOUTR_AI_PROVIDER', 'openai'),
'openai' => [
'api_key' => env('OPENAI_API_KEY'),
'model' => env('CODESNOUTR_AI_MODEL', 'gpt-4'),
],
],
// UI preferences
'ui' => [
'theme' => ['default' => 'system', 'persist' => true],
'pagination' => ['per_page' => 25, 'max_per_page' => 100],
],
];Implemented Detection Rules:
- β SQL injection vulnerabilities (raw queries, unsafe concatenation)
- β XSS risks (unescaped output, dangerous HTML tags)
- β Hardcoded credentials (passwords, API keys, secrets)
- β Insecure file operations (unsafe uploads, directory traversal)
- β Weak cryptography (MD5, SHA1 usage)
- β Unsafe deserialization and eval() usage
Implemented Analysis Rules:
- β N+1 query detection and eager loading suggestions
- β Missing database indexes identification
- β Cache opportunity detection for expensive operations
- β Memory usage optimization (chunking large datasets)
- β Loop efficiency improvements (count() in conditions)
- β File operation optimization suggestions
Implemented Quality Checks:
- β Code complexity analysis (deep nesting, long methods)
- β Naming convention enforcement (variables, classes, methods)
- β Documentation requirements (PHPDoc for public methods)
- β Code standards (line length, trailing whitespace)
- β Best practices (magic numbers, empty catch blocks)
- β Dead code and unused variable detection
- β Context-aware variable validation with snake_case exception handling
- β Intelligent inheritance and interface analysis
Implemented Laravel Rules:
- β Eloquent optimization (select(*) usage, raw SQL in models)
- β Route efficiency (missing names, model binding opportunities)
- β Blade template quality (PHP blocks, deep nesting)
- β Validation completeness and rule strength
- β Service container best practices
- β Migration quality and safety checks
- β Enhanced console command and artisan command analysis
Comprehensive Blade Template Scanning:
- β XSS vulnerability detection (unescaped output, dangerous functions)
- β CSRF protection validation for forms
- β Performance optimization (N+1 queries, inline styles, complex loops)
- β Template complexity analysis (nesting depth, logic separation)
- β Accessibility compliance (alt text, form labels, ARIA attributes)
- β SEO optimization (meta tags, structured content)
- β Code quality (deprecated syntax, hardcoded values, unused variables)
- β Best practices enforcement (component usage, section structure)
The package includes complete infrastructure for AI integration:
- β Configuration Framework: OpenAI API setup and cost tracking
- β UI Components: Settings interface for AI configuration
- β Safety Systems: Preview and approval mechanisms
- β Context Engine: Code analysis and suggestion generation framework
- Get an API key from OpenAI
- Configure in your
.env:
OPENAI_API_KEY=your_api_key_here
CODESNOUTR_AI_ENABLED=true
CODESNOUTR_AI_MODEL=gpt-4- Or configure via the web interface at
/codesnoutr/settings
- Smart Auto-fixes: Context-aware code improvements
- Explanation Generation: Detailed explanations of issues
- Best Practice Suggestions: Laravel-specific recommendations
- Safety Checks: Preview changes before applying
- Cost Management: Usage tracking and monthly limits
β οΈ Local Development Only: This package is designed for local development environments.
Before using AI Auto-Fix, ensure you have:
- β Queue Worker Running (in a separate terminal)
- β Persistent Cache (file or database driver, NOT array)
- β OpenAI API Key (from platform.openai.com)
- β Code Backup (always backup before running auto-fix)
Open a new terminal and run:
# Terminal 1: Queue worker (keep this running)
php artisan queue:work --verbose --timeout=300
# Terminal 2: Your Laravel app
php artisan serveIn your .env:
# DO NOT use 'array' - it won't work with queue workers
CACHE_DRIVER=file # Recommended for local developmentOr use database cache:
php artisan cache:table
php artisan migrate
# Then in .env:
CACHE_DRIVER=databaseGet your API key from platform.openai.com/api-keys
Option 1: Configure in .env:
OPENAI_API_KEY=sk-your-actual-key-here
CODESNOUTR_AI_ENABLED=true
CODESNOUTR_AI_MODEL=gpt-4-turbo
# Optional: Set limits
CODESNOUTR_AI_MAX_TOKENS=4000
CODESNOUTR_AI_TEMPERATURE=0.2Option 2: Use Web Interface:
- Navigate to
/codesnoutr/settings - Go to "AI Integration" tab
- Enter your API key and save
# Check queue is working
php artisan queue:status
# Test cache (should return "working")
php artisan tinker
>>> Cache::put('test', 'working', 60);
>>> Cache::get('test');- Navigate to scan results
- Click on an issue to expand details
- Click "AI Auto-Fix" button
- Review the proposed fix in the preview
- Click "Apply Fix" to implement
-
Navigate to scan results
-
Click "Fix All with AI" button
-
Confirm you want to proceed
-
Monitor progress in real-time:
- Progress bar shows completion
- Live updates every second
- Success/failure count
- Estimated time remaining
-
Review summary when complete:
- Fixed issues count
- Failed issues count
- Total cost (AI tokens used)
- Link to detailed results
"Queue Worker Not Running" Error:
# Start queue worker in separate terminal
php artisan queue:work --verbose --timeout=300Progress Bar Not Updating:
- Make sure
CACHE_DRIVER=file(notarray) - Test cache:
Cache::put('test', 1); Cache::get('test'); - Check browser console (F12) for errors
OpenAI Errors:
- Rate Limit: Wait and retry, or reduce concurrent fixes
- Invalid Key: Check
.envhas correct key starting withsk- - No Credits: Add funds at platform.openai.com/account/billing
Cost Management:
# Use cheaper model for simple fixes
CODESNOUTR_AI_MODEL=gpt-3.5-turbo
# Reduce token usage
CODESNOUTR_AI_MAX_TOKENS=2000- β Test Small First: Try a few issues before Fix All
- β Review Fixes: Always review AI changes before committing
- β Use Git: Commit your code before running auto-fix
- β Monitor Costs: Track OpenAI usage and set budget alerts
- β Backup Code: Always have backups before automated fixes
β οΈ Code Privacy: AI sends your code to OpenAI servers- π Protect Keys: Never commit API keys to version control
Core Package - 100% Complete
- Complete package structure with service provider
- Database migrations and Eloquent models
- Core ScanManager with full scanning capabilities
- All four rule engines fully implemented
- Comprehensive Artisan commands
- Professional configuration system
Web Interface - 100% Complete
- Modern Livewire components (Dashboard, Scanner, Results, Settings)
- Complete dark/light mode system with user preferences
- Responsive design with Tailwind CSS and modern hover effects
- Interactive features with Alpine.js and smooth animations
- Advanced filtering, sorting, and bulk operations
- Enhanced file grouping with expandable issue details
- Export functionality (JSON, CSV)
- Real-time queue status monitoring and management
- Automatic redirects and workflow optimization
Developer Experience - 100% Complete
- Comprehensive documentation and setup guides
- Professional code quality with testing framework
- Flexible CLI interface with multiple output formats
- Extensive configuration options
- Professional error handling and validation
- Context-aware static analysis with inheritance support
- Enhanced queue management with auto-detection
AI Integration - Infrastructure Complete
- OpenAI configuration framework
- Cost tracking and safety systems
- UI components for AI settings
- OpenAI API client implementation
- Auto-fix generation algorithms
Advanced Features - Framework Ready
- Export system foundation
- Analytics data structure
- Debugbar integration (custom collector)
- PDF report generation
- Scheduled scanning capabilities
- Total Files: 50+ source files
- Lines of Code: 8,000+ lines of professional PHP
- Test Coverage: Unit test framework established
- Documentation: Complete with examples and guides
- Code Quality: PSR-4, PHPStan, Laravel Pint configured
- UI Components: Modern Livewire components with enhanced UX
- Recent Updates: Enhanced queue management, expandable details, modern hover effects
For detailed information about our AI integration plans, see the OpenAI Client Roadmap.
Quick Overview:
π v1.1.0 (Q4 2025) - Stability Release
- Enhanced error handling with retry logic
- Improved JSON parsing for AI responses
- Better validation and testing
- Configuration wizard
π v1.2.0 (Q1 2026) - Performance Release
- Intelligent caching (30-50% cost savings)
- Prompt optimization (20-30% token reduction)
- Smart model selection
- Cost reduction features
π v1.3.0 (Q2 2026) - Advanced Features
- OpenAI Function calling integration
- Streaming responses for real-time feedback
- Enhanced progress tracking
- Vision API for diagram analysis
π v2.0.0 (Q3 2026) - Intelligence Release
- Feedback loop system
- Pattern recognition and learning
- Custom rule suggestions
- Fine-tuning support
π v2.1.0 (Q4 2026) - Expansion Release
- Multi-file refactoring
- Automated test generation
- Security vulnerability patching
- PR/commit automation
π v3.0.0 (2027) - Multi-Provider Release
- Support for Claude, Gemini, and local models
- Provider abstraction layer
- Hybrid optimization
- Enterprise features
Current Focus:
- β Core AI features implemented (v1.0.0)
- π§ Stability improvements in progress
- π Performance optimization planned
See OPENAI_CLIENT_ROADMAP.md for complete details including:
- Detailed feature breakdown per phase
- Success metrics and KPIs
- Technical debt tracking
- Contribution opportunities
src/
βββ CodeSnoutrServiceProvider.php # Main service provider
βββ ScanManager.php # Core scanning orchestrator
βββ Commands/ # Artisan commands
β βββ InstallCommand.php # Package installation
β βββ ScanCommand.php # CLI scanning interface
βββ Http/
β βββ Controllers/
β β βββ DashboardController.php # Web interface controller
β βββ Livewire/ # Interactive components
β βββ Dashboard.php # Main dashboard with statistics
β βββ ScanForm.php # Interactive scanning interface
β βββ ScanResults.php # Advanced results management
β βββ Settings.php # Configuration management
β βββ DarkModeToggle.php # Theme switching
βββ Models/ # Eloquent models
β βββ Scan.php # Scan records and relationships
β βββ Issue.php # Detected issues with metadata
β βββ Setting.php # Configuration storage
βββ Scanners/ # Core scanning engines
βββ AbstractScanner.php # Base scanner class
βββ FileScanHandler.php # Single file scanning
βββ DirectoryScanHandler.php # Directory scanning
βββ CodebaseScanHandler.php # Full codebase scanning
βββ Rules/ # Analysis rule engines
βββ AbstractRuleEngine.php # Base rule engine
βββ SecurityRules.php # Security vulnerability detection
βββ PerformanceRules.php # Performance optimization
βββ QualityRules.php # Code quality analysis
βββ LaravelRules.php # Laravel best practices
config/
βββ codesnoutr.php # Comprehensive configuration
database/migrations/ # Database schema
βββ create_codesnoutr_scans_table.php
βββ create_codesnoutr_issues_table.php
βββ create_codesnoutr_settings_table.php
resources/ # UI assets and views
βββ views/
β βββ layouts/app.blade.php # Main layout with navigation
β βββ pages/ # Page templates
β βββ livewire/ # Component views
βββ css/codesnoutr.css # Custom styles with dark mode
βββ js/codesnoutr.js # Interactive features
routes/web.php # Web and API routes
tests/ # Testing framework
We welcome contributions! Please see CONTRIBUTING.md for details.
- Clone the repository
git clone https://github.com/rafaelogic/codesnoutr.git
cd codesnoutr- Install dependencies
composer install- Set up a test Laravel application
composer create-project laravel/laravel test-app
cd test-app- Link the package for development
# In composer.json, add:
"repositories": [
{
"type": "path",
"url": "../codesnoutr"
}
]
# Then require the package
composer require rafaelogic/codesnoutr:dev-main- Run tests and quality checks
composer test # Run PHPUnit tests
composer format # Format code with Laravel Pint
composer analyse # Static analysis with PHPStan
composer all-checks # Run all quality checksThe package includes professional development tools:
- Laravel Pint: Code formatting and style enforcement
- PHPStan: Static analysis for type safety and bugs
- PHPUnit: Unit and feature testing framework
- GitHub Actions: Automated CI/CD pipeline
If you discover any security-related issues, please email [email protected] instead of using the issue tracker. All security vulnerabilities will be promptly addressed.
The package itself includes:
- Input Validation: Comprehensive path and parameter validation
- Output Sanitization: Safe rendering of code snippets and user data
- Access Control: Configurable access restrictions
- Data Protection: Secure storage of scan results and configurations
The MIT License (MIT). Please see License File for more information.
- Rafa Rafael - Creator and maintainer
- All Contributors - Community contributions
Please see CHANGELOG for more information on what has changed recently.
- OpenAI API Client: Complete implementation with rate limiting
- Auto-Fix Generation: Context-aware code improvements
- Safety Systems: Preview and approval mechanisms
- Cost Management: Usage tracking and budget controls
- Debugbar Integration: Custom collector with quick access
- PDF Reports: Professional report generation
- Scheduled Scanning: Automated periodic scans
- Advanced Analytics: Trend analysis and historical comparisons
- Team Collaboration: Multi-user support and shared configurations
- Public API: RESTful API for third-party integrations
- Custom Rule Builder: Visual interface for creating custom rules
- Advanced Integrations: CI/CD pipeline integration tools
We welcome contributions! CodeSnoutr is open source and available on GitHub.
- GitHub: https://github.com/rafaelogic/codesnoutr
- Issues: Report bugs or request features
- Discussions: Join the community
- Clone the repository:
git clone https://github.com/rafaelogic/codesnoutr.git
cd codesnoutr- Install dependencies:
composer install- Run the test suite:
composer test- Format code:
composer format- Run static analysis:
composer analyse- Fork the repository and create your branch from
main - Write tests for any new functionality
- Follow PSR-12 coding standards
- Update documentation for any API changes
- Create a pull request with a clear description
When reporting bugs, please include:
- Laravel version
- PHP version
- CodeSnoutr version
- Steps to reproduce
- Expected vs actual behavior
We're always interested in new ideas! Please check existing issues first, then create a new issue with:
- Use case description
- Proposed implementation approach
- Any relevant examples or mockups
CodeSnoutr is open-sourced software licensed under the MIT license.
- Complete implementation with professional code quality
- Comprehensive testing and validation
- Extensive documentation and examples
- Ready for enterprise deployment
- Efficient scanning algorithms with chunking for large codebases
- Indexed database queries for fast result retrieval
- Memory-optimized processing with configurable limits
- Lazy loading and pagination for responsive UI
- Beautiful, responsive interface that works on all devices
- Intuitive workflow from scanning to issue resolution
- Dark/light mode with user preference persistence
- Real-time updates and interactive components
- Flexible CLI interface with multiple output formats
- Comprehensive configuration options
- Extensible architecture for custom rules
- Professional documentation and examples
Built with β€οΈ for the Laravel community
CodeSnoutr v1.0.0 - Production ready as of August 2025
Q: Is CodeSnoutr ready for production use? A: Yes! CodeSnoutr v1.0.0 is production-ready with comprehensive testing, professional code quality, and full Laravel compatibility.
Q: What Laravel versions are supported? A: CodeSnoutr supports Laravel 10.0, 11.0, and 12.0 with PHP 8.1+.
Q: Does CodeSnoutr slow down my application? A: No. CodeSnoutr runs scans in background queues and doesn't affect your application's performance. The web interface is lightweight and optimized.
Q: Do I need to set up queues? A: While optional, queues are highly recommended for better performance. CodeSnoutr can auto-manage queue workers or you can set up dedicated workers.
Q: Can I customize which files are scanned?
A: Yes! Configure scan paths, exclusions, and file types in config/codesnoutr.php or through the web interface.
Q: How do I update CodeSnoutr?
A: Run composer update rafaelogic/codesnoutr and republish assets with php artisan vendor:publish --tag=codesnoutr-assets --force.
Q: What types of issues can CodeSnoutr detect? A: CodeSnoutr detects 50+ types of issues including security vulnerabilities, performance problems, code quality issues, and Laravel best practice violations.
Q: Can I export scan results? A: Yes! Export results as JSON, CSV, or store them in your database. Use the web interface or CLI commands.
Q: Is AI integration required? A: No. AI features are optional and require an OpenAI API key. All core functionality works without AI integration.
Q: Can I create custom scanning rules?
A: Yes! Extend the AbstractRuleEngine class to create custom rules. See the source code examples in src/Scanners/Rules/.
Q: Does CodeSnoutr work with Docker? A: Yes! CodeSnoutr is fully compatible with Docker. See the installation guide for Docker-specific instructions.
Q: Can I integrate CodeSnoutr with CI/CD? A: Absolutely! Use the CLI commands in your CI/CD pipeline to automatically scan code and fail builds on critical issues.
Q: Scans are not starting or taking too long A: Check your queue configuration. Ensure queue workers are running or enable auto-start in the configuration.
Q: Getting permission errors A: Make sure your web server has read permissions on your codebase and write permissions on storage directories.
Q: Web interface not loading properly
A: Clear Laravel caches (php artisan cache:clear) and ensure assets are published (php artisan vendor:publish --tag=codesnoutr-assets --force).
Q: UI appears broken with no CSS styling A: This means the assets weren't published correctly. Run:
php artisan codesnoutr:install --force
# or
php artisan vendor:publish --provider="Rafaelogic\CodeSnoutr\CodeSnoutrServiceProvider" --tag="codesnoutr-assets" --forceVerify assets exist at public/vendor/codesnoutr/build/. See CSS_TROUBLESHOOTING.md for detailed help.
- π Documentation: Comprehensive guides in this README
- π Bug Reports: GitHub Issues
- π¬ Discussions: GitHub Discussions
- π§ Security Issues: [email protected]
- β Star the Project: GitHub Repository
- π¦ Follow Updates: @rafaelogic
- πΌ Professional Support: Available for enterprise customers
We're always looking to improve! Submit feature requests through:
- GitHub Issues with the "enhancement" label
- GitHub Discussions in the "Ideas" category
- Direct email for enterprise features
