rafaelogic / codesnoutr
A comprehensive Laravel code scanner that detects security vulnerabilities, performance issues, and code quality problems with AI-powered fixes
Installs: 1
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
pkg:composer/rafaelogic/codesnoutr
Requires
- php: ^8.1
- illuminate/console: ^10.0|^11.0|^12.0
- illuminate/database: ^10.0|^11.0|^12.0
- illuminate/support: ^10.0|^11.0|^12.0
- livewire/livewire: ^3.6.4
- nikic/php-parser: ^4.0|^5.0
- seld/jsonlint: ^1.11
- symfony/finder: ^6.0|^7.0
Requires (Dev)
- larastan/larastan: ^2.0|^3.0
- laravel/pint: ^1.0
- mockery/mockery: ^1.4
- orchestra/testbench: ^8.0|^9.0|^10.0
- phpstan/extension-installer: ^1.1
- phpstan/phpstan-deprecation-rules: ^1.0
- phpstan/phpstan-phpunit: ^1.0
- phpunit/phpunit: ^10.0|^11.0
Suggests
- barryvdh/laravel-debugbar: For debugbar integration
- openai-php/client: For AI-powered fixes
- spatie/laravel-pdf: For PDF report generation
README
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.
📚 Table of Contents
- ✨ Features
- 📋 Requirements
- 🚀 Installation
- ⚡ Quick Start
- ⚙️ Configuration
- 🔍 Scanning Categories
- 🤖 AI Integration
- 📈 Current Status
- �️ Roadmap
- �📁 Package Structure
- 🤝 Contributing
- 🔒 Security
- 📄 License
✨ Features
🔍 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)
📋 Requirements
System Requirements
-
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
Queue & Cache Requirements (For AI Auto-Fix)
CRITICAL: The AI Auto-Fix and Fix All features require proper queue and cache configuration:
Cache Driver (Required)
- ✅ Supported:
file
,redis
,database
- ❌ NOT Supported:
array
(doesn't persist across processes) - Why: Queue workers and web interface must share progress data
Queue Driver (Required)
- ✅ Supported:
database
,redis
,beanstalkd
,sqs
- ❌ NOT Supported:
sync
(blocks the interface) - Why: AI fixes run in background to prevent timeouts
Queue Worker (Required)
- Must have at least one worker running:
php artisan queue:work
- Supervisor recommended for production
- CodeSnoutr includes automatic worker detection
AI Auto-Fix Requirements (Optional)
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
Frontend Requirements
-
Modern Browser:
- Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
- JavaScript enabled
- LocalStorage enabled (for theme preferences)
-
Screen Resolution: 1024x768 minimum (responsive design)
🚀 Installation
Prerequisites
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
Step 1: Install via Composer
Install the package using Composer:
composer require rafaelogic/codesnoutr
Step 2: Run Installation Command
Execute the installation command to set up CodeSnoutr:
php artisan codesnoutr:install
This interactive installation will:
- Publish Configuration: Creates
config/codesnoutr.php
with 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
Step 3: Configure Environment (Optional)
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 Configuration
The Fix All Issues feature requires a persistent cache driver to track progress between the queue worker and web interface. The
array
cache 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
Step 4: Configure Queue & Cache (Required for Fix All Features)
⚠️ Important: CodeSnoutr is designed for local development environments only. Do not use in production.
🎯 Quick Setup for Local Development
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=300
📋 Cache Driver Requirements
The 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
🔧 Queue Worker for Development
Open a new terminal window and run:
# Start queue worker (keep this running)
php artisan queue:work --verbose --timeout=300
Tips:
- Keep the queue worker running in a separate terminal
- Use
--verbose
flag to see jobs being processed - Press
Ctrl+C
to stop the worker when done - Restart worker after code changes to pick up new code
🛡️ Queue Worker Protection
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
📊 Monitoring Progress
The Fix All feature includes comprehensive logging:
Browser Console (F12):
🔄 wire:poll #5 (1000ms since last) ✅ Changes detected: currentStep: 2→3, fixedCount: 0→1
Laravel 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.sh
Troubleshooting:
# 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:restart
Step 5: Access the Dashboard
Navigate 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
Troubleshooting Installation
Permission Issues
# Fix storage permissions chmod -R 755 storage/ chown -R www-data:www-data storage/ # Fix published assets permissions chmod -R 755 public/vendor/codesnoutr/
Database Issues
# Re-run migrations if needed php artisan migrate:refresh # Check database connection php artisan tinker >>> \DB::connection()->getPdo()
Asset Publishing Issues
# 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:clear
Queue Worker Issues
Important: 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 --verbose
Why 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.
Manual Installation (Advanced)
If you prefer manual installation or need custom configuration:
1. Publish Components Individually
# 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"
2. Run Migrations Manually
php artisan migrate
3. Configure Custom Routes (Optional)
If 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'); });
Updating CodeSnoutr
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:clear
Uninstallation
To 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:clear
Docker Installation
For 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/
Production Deployment
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(); }
⚡ Quick Start
🚀 First Scan in 30 Seconds
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
🌐 Web Interface Walkthrough
-
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
🛠️ Common Use Cases
Security Audit
# Focus on security issues only
php artisan codesnoutr:scan codebase --categories=security --format=json
Performance Review
# Check for N+1 queries and performance issues
php artisan codesnoutr:scan codebase --categories=performance
Code Quality Check
# Analyze code quality and Laravel best practices
php artisan codesnoutr:scan directory app --categories=quality,laravel
Pre-deployment Scan
# Comprehensive scan before deployment
php artisan codesnoutr:scan codebase --save --export-path=deployment-report.json
Web Dashboard
Access 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
🔄 Enhanced User Experience
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
🔄 Automatic Queue Management
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.
🤖 AI Smart Assistant
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.
Artisan Commands
Scan entire codebase:
php artisan codesnoutr:scan codebase
Scan specific file:
php artisan codesnoutr:scan file app/Models/User.php
Scan directory:
php artisan codesnoutr:scan directory app/Models
Filter by categories:
php artisan codesnoutr:scan codebase --categories=security,performance
Export 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 --save
⚙️ Configuration
The 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], ], ];
🔍 Scanning Categories
Security 🔒
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
Performance ⚡
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
Code Quality 📝
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
Laravel Best Practices 🎯
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
Blade Template 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)
🤖 AI Integration (Ready for Implementation)
Current Status
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
Setup OpenAI (When Ready)
- 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
Planned AI Features
- 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
🤖 AI Auto-Fix Setup Guide
⚠️ Local Development Only: This package is designed for local development environments.
Prerequisites Checklist
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)
Quick Setup
1. Start Queue Worker
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 serve
2. Configure Cache Driver
In your .env
:
# DO NOT use 'array' - it won't work with queue workers CACHE_DRIVER=file # Recommended for local development
Or use database cache:
php artisan cache:table
php artisan migrate
# Then in .env:
CACHE_DRIVER=database
3. Set Up OpenAI API Key
Get 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.2
Option 2: Use Web Interface:
- Navigate to
/codesnoutr/settings
- Go to "AI Integration" tab
- Enter your API key and save
4. Verify Everything Works
# Check queue is working php artisan queue:status # Test cache (should return "working") php artisan tinker >>> Cache::put('test', 'working', 60); >>> Cache::get('test');
Using AI Auto-Fix
Single Issue Fix
- 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
Fix All Issues
-
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
Troubleshooting AI Auto-Fix
Common Issues
"Queue Worker Not Running" Error:
# Start queue worker in separate terminal
php artisan queue:work --verbose --timeout=300
Progress 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
.env
has 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
Best Practices
- ✅ 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
📈 Current Status
✅ Production Ready (v1.0.0)
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
� Ready for Implementation
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
📊 Package Statistics
- 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
�️ Roadmap
OpenAI API Client Implementation
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
�📁 Package Structure
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
🤝 Contributing
We welcome contributions! Please see CONTRIBUTING.md for details.
Development Setup
- 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 checks
Development Tools
The 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
🔒 Security
If you discover any security-related issues, please email security@rafaelogic.com instead of using the issue tracker. All security vulnerabilities will be promptly addressed.
Security Features
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
📄 License
The MIT License (MIT). Please see License File for more information.
👥 Credits
- Rafa Rafael - Creator and maintainer
- All Contributors - Community contributions
📝 Changelog
Please see CHANGELOG for more information on what has changed recently.
🚀 Roadmap
Phase 2: AI Integration (Q4 2025)
- 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
Phase 3: Advanced Features (Q1 2026)
- Debugbar Integration: Custom collector with quick access
- PDF Reports: Professional report generation
- Scheduled Scanning: Automated periodic scans
- Advanced Analytics: Trend analysis and historical comparisons
Phase 4: Enterprise Features (Q2 2026)
- 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
🤝 Contributing
We welcome contributions! CodeSnoutr is open source and available on GitHub.
📍 Repository
- GitHub: https://github.com/rafaelogic/codesnoutr
- Issues: Report bugs or request features
- Discussions: Join the community
🛠️ Development Setup
- 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
📝 Contributing Guidelines
- 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
🐛 Bug Reports
When reporting bugs, please include:
- Laravel version
- PHP version
- CodeSnoutr version
- Steps to reproduce
- Expected vs actual behavior
💡 Feature Requests
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
📄 License
CodeSnoutr is open-sourced software licensed under the MIT license.
🏆 Why Choose CodeSnoutr?
✅ Production Ready
- Complete implementation with professional code quality
- Comprehensive testing and validation
- Extensive documentation and examples
- Ready for enterprise deployment
⚡ Performance Optimized
- 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
🎨 Modern Experience
- 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
🔧 Developer Friendly
- 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
❓ Frequently Asked Questions
General Questions
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.
Installation & Setup
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
.
Features & Functionality
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.
Technical Questions
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.
Troubleshooting
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" --force
Verify assets exist at public/vendor/codesnoutr/build/
. See CSS_TROUBLESHOOTING.md for detailed help.
🆘 Support & Community
Getting Help
- 📖 Documentation: Comprehensive guides in this README
- 🐛 Bug Reports: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 📧 Security Issues: security@rafaelogic.com
Community
- ⭐ Star the Project: GitHub Repository
- 🐦 Follow Updates: @rafaelogic
- 💼 Professional Support: Available for enterprise customers
Feature Requests
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