Quick Start

⚡ Quick Start Guide

Get up and running with Laravel Safeguard in just a few minutes! This guide will walk you through installing the package and running your first security check.

📥 Installation

composer require --dev grazulex/laravel-safeguard
php artisan vendor:publish --tag=safeguard-config

Already installed? Skip to Your First Security Check

🛡️ Your First Security Check

Run a basic security audit:

php artisan safeguard:check

Example Output:

🔐 Laravel Safeguard Security Check
═══════════════════════════════════════

Environment: local

✅ APP_KEY is set
✅ Storage directories are writable
✅ CSRF protection enabled
⚠️  APP_DEBUG is enabled (acceptable in local environment)

═══════════════════════════════════════
🎯 All checks passed! (4 checks)

📊 Understanding the Results

Laravel Safeguard uses clear icons to show the status of each security check:

• ✅ Green checkmark: Rule passed successfully
• ❌ Red X: Rule failed (needs immediate attention)
• ⚠️ Yellow warning: Rule has warnings (review recommended)
• 🚨 Red alert: Critical security issue found

🔧 Common First Steps

1. Check Available Rules

See what security rules are available:

php artisan safeguard:list

Output:

🛡️ Available Security Rules:
───────────────────────────────────────

Environment & Configuration:
✓ app-debug-false-in-production
✓ env-has-all-required-keys
✓ app-key-is-set
✓ no-secrets-in-code

Security Rules:
✓ csrf-enabled
✓ composer-package-security
...

2. Environment-Specific Checks

Run checks for production environment:

php artisan safeguard:check --env=production

3. JSON Output for Automation

Get machine-readable output for scripts and CI/CD:

php artisan safeguard:check --format=json

⚙️ Essential Configuration

Edit config/safeguard.php to customize your security rules:

return [
    'rules' => [
        // 🔐 Essential security rules (recommended to keep enabled)
        'app-key-is-set' => true,
        'app-debug-false-in-production' => true,
        'csrf-enabled' => true,
        
        // 🛡️ Optional rules (enable based on your needs)
        'no-secrets-in-code' => true,
        'env-file-permissions' => true,
        'database-connection-encrypted' => false, // Enable for production
    ],
    
    // 🎯 Environment-specific rules
    'environments' => [
        'production' => [
            'app-debug-false-in-production',
            'app-key-is-set',
            'env-file-permissions',
            'database-connection-encrypted',
        ],
        'local' => [
            'app-key-is-set',
            'csrf-enabled',
        ],
    ],
];

🌍 Real-World Example

Here's what a typical security check might reveal in a production environment:

php artisan safeguard:check --env=production

🔐 Laravel Safeguard Security Check
═══════════════════════════════════════

Environment: production

✅ APP_KEY is set
❌ APP_DEBUG is true in production
✅ CSRF protection enabled
❌ Secret found in config/services.php (STRIPE_SECRET)
✅ Storage directories are writable
⚠️  HTTPS not enforced (rule disabled)

═══════════════════════════════════════
🎯 2 issues found, 4 checks passed

🔧 Fixing the Issues

1. APP_DEBUG issue: Set APP_DEBUG=false in your production .env
2. Hardcoded secret: Move STRIPE_SECRET to environment variables:

   // Before (config/services.php):
   'stripe' => [
       'secret' => 'sk_live_xxxxxxxxxxxx', // ❌ Hardcoded
   ],
   
   // After (config/services.php):
   'stripe' => [
       'secret' => env('STRIPE_SECRET'), // ✅ Environment variable
   ],
   
   // Add to .env:
   STRIPE_SECRET=sk_live_xxxxxxxxxxxx

🚀 Integration Examples

GitHub Actions

Add to .github/workflows/security.yml:

name: Security Audit
on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: 8.3
      - name: Install dependencies
        run: composer install --no-dev --optimize-autoloader
      - name: Run security checks
        run: php artisan safeguard:check --env=production --fail-on-error

Pre-deployment Script

Create a deployment checklist script:

#!/bin/bash
echo "🔐 Running pre-deployment security checks..."
php artisan safeguard:check --env=production --fail-on-error

if [ $? -eq 0 ]; then
    echo "✅ Security checks passed! Safe to deploy."
else
    echo "❌ Security issues found! Please fix before deploying."
    exit 1
fi

Make it executable and use it:

chmod +x scripts/security-check.sh
./scripts/security-check.sh

📚 What's Next?

Now that you have Laravel Safeguard running, explore these features:

🎯 Next Steps by Experience Level

Beginner Path:

1. ⚙️ Configuration Guide - Learn to configure rules for your needs
2. 💡 Examples Collection - See real-world usage examples
3. 📝 Rules Reference - Understand all available security rules

Intermediate Path:

1. 🚀 CI/CD Integration - Automate security checks
2. 🌍 Environment Rules - Environment-specific configurations
3. 📊 Output Formats - Customize output for different tools

Advanced Path:

1. 🏗️ Custom Rules - Create application-specific security rules
2. 📖 API Reference - Programmatic usage
3. ⚡ Performance - Optimize for large applications

🆘 Common Issues

"Command not found"

If the safeguard:check command doesn't work:

# Check if package is installed
composer show grazulex/laravel-safeguard

# Check if commands are available
php artisan list | grep safeguard

"Config file not found"

Make sure you've published the configuration:

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

No rules enabled

Check your config/safeguard.php file has rules set to true:

'rules' => [
    'app-key-is-set' => true, // ← Make sure this is true
    'csrf-enabled' => true,   // ← And this
    // ...
],

Permission issues

Ensure Laravel can write to required directories:

chmod -R 755 storage/
chmod -R 755 bootstrap/cache/

🤝 Help & Support

• ❓ FAQ - Common questions and answers
• 🆘 Troubleshooting - Solutions to common problems
• GitHub Issues - Report bugs or request features

---

Next Step: ⚙️ Configure security rules for your application

🏠 Home | 📦 Installation | ⚙️ Configuration | 💡 Examples