Troubleshooting

🆘 Troubleshooting Guide

This comprehensive guide helps you resolve common issues when using Laravel Safeguard. Issues are organized by category with step-by-step solutions.

📦 Installation Issues

Package Not Found

Problem: composer require fails with "Package not found"

Symptoms:

Could not find package grazulex/laravel-safeguard

Solutions:

1. Update Composer:

composer self-update

2. Clear Composer cache:

composer clear-cache

3. Check package name:

# Correct package name
composer require --dev grazulex/laravel-safeguard

# NOT grazulex/safeguard or laravel-safeguard

4. Check Composer configuration:

composer config --list

Dependency Conflicts

Problem: Composer reports dependency conflicts

Symptoms:

Your requirements could not be resolved to an installable set of packages.

Solutions:

1. Check conflicts:

composer why-not grazulex/laravel-safeguard

2. Update dependencies:

composer update --with-dependencies

3. Check requirements:

   • PHP: 8.3 or higher
   • Laravel: 12.19 or higher

4. Force resolution (last resort):

composer require --dev grazulex/laravel-safeguard --ignore-platform-reqs

Service Provider Not Registered

Problem: Commands not available after installation

Symptoms:

php artisan safeguard:check
# Command "safeguard:check" is not defined.

Solutions:

1. Clear Laravel caches:

php artisan cache:clear
php artisan config:clear
php artisan route:clear

2. Re-discover packages:

php artisan package:discover --ansi

3. Check if commands are available:

php artisan list | grep safeguard

4. Manual registration (if auto-discovery fails):

// config/app.php
'providers' => [
    // ...
    Grazulex\\LaravelSafeguard\\LaravelSafeguardServiceProvider::class,
],

⚙️ Configuration Issues

Config File Not Found

Problem: "Configuration file not found" error

Symptoms:

Configuration file config/safeguard.php not found

Solutions:

1. Publish configuration:

php artisan vendor:publish --tag=safeguard-config

2. Check if file exists:

ls -la config/safeguard.php

3. Force republish if needed:

php artisan vendor:publish --tag=safeguard-config --force

4. Check file permissions:

chmod 644 config/safeguard.php

Rules Not Loading

Problem: Custom rules not being detected

Symptoms:

php artisan safeguard:list
# Custom rules don't appear in the list

Solutions:

1. Check file location:

ls -la app/SafeguardRules/

2. Verify namespace:

// In your custom rule file
namespace App\\SafeguardRules;

use Grazulex\\LaravelSafeguard\\Contracts\\SafeguardRule;

3. Check configuration:

// config/safeguard.php
'custom_rules_path' => app_path('SafeguardRules'),
'custom_rules_namespace' => 'App\\\\SafeguardRules',

4. Verify rule implementation:

class MyCustomRule implements SafeguardRule
{
    // Must implement all required methods
    public function id(): string { }
    public function check(): SafeguardResult { }
    public function appliesToEnvironment(string $env): bool { }
    public function severity(): string { }
}

5. Clear caches:

php artisan config:clear
php artisan cache:clear

Invalid Configuration Syntax

Problem: Configuration file has syntax errors

Symptoms:

PHP Parse error: syntax error, unexpected '}' in config/safeguard.php

Solutions:

1. Check PHP syntax:

php -l config/safeguard.php

2. Validate configuration:

php artisan safeguard:config validate

3. Common syntax issues:

// ❌ Missing comma
'rules' => [
    'rule1' => true
    'rule2' => true,  // Missing comma after true
],

// ✅ Correct syntax
'rules' => [
    'rule1' => true,
    'rule2' => true,
],

4. Republish if corrupted:

php artisan vendor:publish --tag=safeguard-config --force

🔍 Runtime Issues

"Command Not Found" Error

Problem: Commands work sometimes but not others

Symptoms:

php artisan safeguard:check
# Sometimes works, sometimes doesn't

Solutions:

1. Check Laravel environment:

php artisan --version
php artisan env

2. Verify package is still installed:

composer show grazulex/laravel-safeguard

3. Check for conflicting packages:

composer show | grep safeguard

4. Reinstall package:

composer remove --dev grazulex/laravel-safeguard
composer require --dev grazulex/laravel-safeguard

No Rules Being Executed

Problem: Command runs but no rules are checked

Symptoms:

php artisan safeguard:check
# 🎯 0 checks run

Solutions:

1. Check enabled rules:

php artisan safeguard:list --enabled

2. Verify configuration:

// config/safeguard.php
'rules' => [
    'app-key-is-set' => true, // Make sure some rules are enabled
    'csrf-enabled' => true,
],

3. Check environment-specific rules:

# Try different environment
php artisan safeguard:check --env=production

# Or use all rules instead of environment-specific
php artisan safeguard:check --env=production # Uses all enabled rules

4. Debug rule loading:

php artisan safeguard:check --verbose

Memory or Timeout Issues

Problem: Commands fail with memory or timeout errors

Symptoms:

Fatal error: Allowed memory size of X bytes exhausted
Maximum execution time exceeded

Solutions:

1. Increase memory limit:

php -d memory_limit=512M artisan safeguard:check

2. Configure in safeguard.php:

'performance' => [
    'memory_limit' => '1G',
    'timeout_seconds' => 600,
    'max_scan_files' => 5000,
],

3. Reduce scan scope:

'scan_paths' => [
    'app/',
    'config/',
    // Remove large directories like 'vendor/', 'node_modules/'
],

4. Enable parallel processing:

'performance' => [
    'parallel_processing' => true,
],

5. Use caching:

php artisan safeguard:cache rebuild

📊 Output and Formatting Issues

No Output or Empty Results

Problem: Command runs but produces no output

Symptoms:

php artisan safeguard:check
# (no output)

Solutions:

1. Check output buffering:

php artisan safeguard:check --verbose

2. Try different format:

php artisan safeguard:check --format=json

3. Check log files:

tail -f storage/logs/laravel.log

4. Test with specific rule:

php artisan safeguard:test-rule app-key-is-set

JSON Format Issues

Problem: Invalid JSON output

Symptoms:

{
  \"status\": \"failed\",
  // Trailing comma or syntax error
}

Solutions:

1. Validate JSON output:

php artisan safeguard:check --format=json | jq .

2. Check for encoding issues:

php artisan safeguard:check --format=json | iconv -f utf-8 -t utf-8//IGNORE

3. Use alternative format:

php artisan safeguard:check --format=cli

Incorrect Colors or Formatting

Problem: Output has wrong colors or formatting

Solutions:

1. Disable colors for CI:

php artisan safeguard:check --ci

2. Force colors:

php artisan safeguard:check --ansi

3. Check terminal support:

echo $TERM
# Should support colors

🏗️ Custom Rules Issues

Custom Rule Not Executing

Problem: Custom rule exists but doesn't run

Solutions:

1. Check rule is enabled:

// config/safeguard.php
'rules' => [
    'my-custom-rule' => true, // Must be enabled
],

2. Verify rule ID matches:

// In your custom rule
public function id(): string
{
    return 'my-custom-rule'; // Must match config key
}

3. Check namespace and autoloading:

composer dump-autoload

4. Test rule individually:

php artisan safeguard:test-rule my-custom-rule

Custom Rule Errors

Problem: Custom rule throws exceptions

Solutions:

1. Check error handling:

public function check(): SafeguardResult
{
    try {
        // Your logic here
        return SafeguardResult::pass('Check passed');
    } catch (Exception $e) {
        return SafeguardResult::fail('Check failed: ' . $e->getMessage());
    }
}

2. Validate dependencies:

public function check(): SafeguardResult
{
    if (!function_exists('some_required_function')) {
        return SafeguardResult::fail('Required function not available');
    }
    
    // Continue with check
}

3. Debug with verbose output:

php artisan safeguard:test-rule my-custom-rule --verbose

🚀 CI/CD Issues

GitHub Actions Failures

Problem: Security checks fail in GitHub Actions but work locally

Solutions:

1. Check PHP version consistency:

# .github/workflows/security.yml
- name: Setup PHP
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.3' # Match your local version

2. Ensure .env file exists:

- name: Create .env file
  run: |
    cp .env.example .env
    php artisan key:generate

3. Check dependencies:

- name: Install dependencies
  run: composer install --prefer-dist --no-progress --no-interaction

4. Debug with verbose output:

- name: Run security checks
  run: php artisan safeguard:check --verbose --fail-on-error

GitLab CI Issues

Problem: Security checks fail in GitLab CI

Solutions:

1. Check Docker image:

security_check:
  image: php:8.3-cli
  before_script:
    - apt-get update -yqq
    - apt-get install -yqq git unzip

2. Install Composer:

before_script:
  - curl -sS https://getcomposer.org/installer | php
  - mv composer.phar /usr/local/bin/composer

3. Check file permissions:

script:
  - chmod +x vendor/bin/*
  - php artisan safeguard:check --fail-on-error

Docker Issues

Problem: Security checks fail in Docker containers

Solutions:

1. Check file permissions:

# In your Dockerfile
RUN chown -R www-data:www-data /var/www
RUN chmod -R 755 /var/www/storage

2. Install required extensions:

RUN docker-php-ext-install pdo_mysql mbstring

3. Set proper working directory:

WORKDIR /var/www
COPY . .
RUN composer install --no-dev

🐛 Debugging Techniques

Enable Debug Mode

# Laravel debug mode
APP_DEBUG=true php artisan safeguard:check --verbose

# PHP error reporting
php -d display_errors=1 -d error_reporting=E_ALL artisan safeguard:check

Check Logs

# Laravel logs
tail -f storage/logs/laravel.log

# System logs (if applicable)
tail -f /var/log/php_errors.log

Isolate Issues

# Test individual components
php artisan safeguard:list
php artisan safeguard:config validate
php artisan safeguard:test-rule app-key-is-set

# Check Laravel installation
php artisan --version
php artisan env

Performance Profiling

# Time execution
time php artisan safeguard:check

# Memory usage
php -d memory_limit=1G artisan safeguard:check --verbose

# Profile with xdebug (if available)
php -d xdebug.profiler_enable=1 artisan safeguard:check

🔧 Environment-Specific Issues

Local Development Problems

Common Issues:

• Missing .env file
• Incorrect file permissions
• Database connection issues

Solutions:

# Setup local environment
cp .env.example .env
php artisan key:generate
chmod 755 storage/
chmod 755 bootstrap/cache/

Production Environment Problems

Common Issues:

• Strict file permissions
• Limited PHP extensions
• Memory/timeout limits

Solutions:

# Check production requirements
php --version
php -m | grep required_extension

# Optimize for production
composer install --no-dev --optimize-autoloader
php artisan config:cache

CI/CD Environment Problems

Common Issues:

• Missing dependencies
• Incorrect environment variables
• Timeout limits

Solutions:

# Use appropriate timeouts
php -d max_execution_time=300 artisan safeguard:check

# Set proper environment
export APP_ENV=testing
export APP_DEBUG=false

📞 Getting Help

Before Asking for Help

1. ✅ Check this troubleshooting guide
2. ✅ Read the FAQ
3. ✅ Search existing issues
4. ✅ Try with --verbose flag
5. ✅ Test with minimal configuration

When Reporting Issues

Include this information:

# System information
php --version
composer --version
php artisan --version

# Package information
composer show grazulex/laravel-safeguard

# Laravel environment
php artisan env

# Error output with verbose flag
php artisan safeguard:check --verbose

Where to Get Help

1. 📖 Documentation: Laravel Safeguard Wiki
2. 🐛 Bug Reports: GitHub Issues
3. 💬 Questions: GitHub Discussions
4. 📧 Security Issues: Contact maintainers directly

Creating a Minimal Reproduction

# Create new Laravel project
composer create-project laravel/laravel test-safeguard
cd test-safeguard

# Install Laravel Safeguard
composer require --dev grazulex/laravel-safeguard

# Publish config
php artisan vendor:publish --tag=safeguard-config

# Test with minimal configuration
php artisan safeguard:check --verbose

🎯 Common Patterns and Solutions

Pattern: "It works locally but not in CI"

Checklist:

• Same PHP version
• Same Laravel version
• Same package versions (composer.lock)
• Environment variables set
• File permissions correct
• Required extensions installed

Pattern: "Slow performance on large projects"

Solutions:

• Reduce scan_paths
• Increase timeout_seconds
• Enable parallel_processing
• Use rule caching
• Limit max_scan_files

Pattern: "False positives in security checks"

Solutions:

• Customize secret_patterns
• Exclude test directories
• Use environment-specific rules
• Create custom rules for specific needs

---

Still having issues? Check the ❓ FAQ or create an issue on GitHub.

🏠 Home | ❓ FAQ | ⚡ Quick Start | ⚙️ Configuration