README

A comprehensive Laravel package for source code obfuscation using PHPBolt. Protect your Laravel application's source code with advanced obfuscation techniques, perfect for CI/CD pipelines and deployment workflows.

Features

🔒 PHPBolt Integration - Uses PHPBolt engine for professional-grade obfuscation
⚙️ Highly Configurable - Extensive configuration options for fine-tuned control
📁 Smart File Selection - Include/exclude patterns for precise file targeting
🔄 Automatic Backups - Create backups before obfuscation with rotation
🚀 CI/CD Ready - Designed for seamless integration into deployment pipelines
📊 Detailed Reporting - Generate comprehensive obfuscation reports
🎯 Multiple Commands - CLI commands for various obfuscation tasks
⚡ Performance Optimized - Parallel processing support for large codebases
🛡️ Safe Operation - Dry-run mode and validation checks

Requirements

PHP >= 7.4
Laravel >= 8.0 (8.x, 9.x, 10.x, 11.x, 12.x)
PHPBolt extension (bolt.so) - Get it here

Installation

1. Install via Composer

composer require aflorea4/laravel-source-obfuscator

2. Install PHPBolt Extension

PHPBolt is a free PHP extension for code obfuscation. Install the bolt.so extension:

# Download bolt.so for your PHP version from https://github.com/arshidkv12/phpBolt
# Or use the provided installation script

# Copy to PHP extensions directory
sudo cp bolt.so $(php-config --extension-dir)/

# Enable the extension
echo "extension=bolt.so" | sudo tee /etc/php/$(php -r 'echo PHP_MAJOR_VERSION.".".PHP_MINOR_VERSION;')/mods-available/bolt.ini
sudo phpenmod bolt

# Restart PHP-FPM
sudo systemctl restart php$(php -r 'echo PHP_MAJOR_VERSION.".".PHP_MINOR_VERSION;')-fpm

# Verify installation
php -m | grep bolt

Note: The extension must be loaded both during obfuscation AND at runtime in production.

3. Publish Configuration

php artisan vendor:publish --provider="Aflorea4\LaravelSourceObfuscator\ObfuscatorServiceProvider" --tag="config"

This will create config/obfuscator.php in your Laravel application.

4. Configure Encryption Key

Edit .env file and add:

# Encryption key (leave empty to auto-generate)
PHPBOLT_KEY=

# OR set a specific key (min 6 characters)
PHPBOLT_KEY=your-secret-key-here

# Output directories
OBFUSCATOR_OUTPUT_DIR=production/obfuscated
OBFUSCATOR_BACKUP_DIR=backups/pre-obfuscation

Important: The encryption key will be shown after obfuscation. You must set it as PHP_BOLT_KEY constant in production.

Runtime Configuration (Production)

After obfuscating your code, you need to configure your production environment:

1. Install bolt.so Extension in Production

# The bolt.so extension MUST be installed in production
sudo cp bolt.so $(php-config --extension-dir)/
echo "extension=bolt.so" | sudo tee /etc/php/8.2/mods-available/bolt.ini
sudo phpenmod bolt
sudo systemctl restart php8.2-fpm

2. Define PHP_BOLT_KEY Constant

Add to your public/index.php or bootstrap file:

<?php
// Define encryption key (use the key shown after obfuscation)
define('PHP_BOLT_KEY', 'your-encryption-key-here');

// Or load from environment
define('PHP_BOLT_KEY', env('PHPBOLT_KEY'));

// Rest of your Laravel bootstrap code...

Without these steps, your obfuscated code will NOT run!

Configuration

The package configuration file (config/obfuscator.php) provides extensive options:

PHPBolt Extension Configuration

'extension_name' => 'bolt',  // Extension name to check
'encryption_key' => env('PHPBOLT_KEY', ''),  // Leave empty to auto-generate
'key_length' => env('PHPBOLT_KEY_LENGTH', 6),  // Key length if auto-generated

Include/Exclude Paths

'include_paths' => [
    'app',
    'routes',
    'config',
    'database/migrations',
    'database/seeders',
],

'exclude_paths' => [
    'tests',
    'vendor',
    'node_modules',
    'storage',
    '*.blade.php',  // Exclude Blade templates
    '*.md',
    '*.json',
],

Obfuscation Options

'obfuscation' => [
    'strip_comments' => true,        // Remove comments before encryption
    'strip_whitespace' => true,      // Remove unnecessary whitespace
    // Note: String encoding, variable scrambling, integrity checks,
    // and encryption are handled by bolt_encrypt() automatically
],

Backup Configuration

'backup' => [
    'enabled' => true,
    'path' => env('OBFUSCATOR_BACKUP_DIR', 'backups/pre-obfuscation'),
    'keep_last' => 5,  // Keep only the last 5 backups
],

CI/CD Mode

'ci_mode' => [
    'fail_on_error' => true,
    'generate_report' => true,
    'report_path' => 'build/obfuscation-report.json',
],

Performance Settings

'performance' => [
    'parallel_processes' => 0,      // 0 = auto-detect CPU cores
    'memory_limit' => '512M',
    'timeout' => 60,                // Timeout per file in seconds
],

Usage

Available Commands

The package provides four Artisan commands:

1. Obfuscate Source Code

Run the main obfuscation process:

php artisan obfuscate:run

Options:

--source=path - Override source paths (can be used multiple times: --source=app --source=routes)
--destination=path - Override output directory (default: production/obfuscated)
--production-ready - Create a complete Laravel project bundle with obfuscated files
--dry-run - Simulate obfuscation without modifying files
--backup - Create a backup before obfuscating (disabled by default)
--force - Skip confirmation prompt
-v|vv|vvv - Increase verbosity (Laravel built-in)

Examples:

# Basic obfuscation (only obfuscated files in output)
php artisan obfuscate:run

# Production-ready bundle (complete Laravel project with obfuscated files)
php artisan obfuscate:run --production-ready

# Dry run to preview changes
php artisan obfuscate:run --dry-run

# Create a backup before obfuscating
php artisan obfuscate:run --backup

# Run in CI/CD (non-interactive)
php artisan obfuscate:run --force

# Production-ready with only specific directories obfuscated
php artisan obfuscate:run --production-ready --source=app --source=routes

# Override output directory
php artisan obfuscate:run --destination=build/production

# Complete production bundle ready for deployment
php artisan obfuscate:run --production-ready --destination=dist --force

🚀 Production-Ready Bundle Mode

The --production-ready flag creates a complete, deployable Laravel project with obfuscated files. This is perfect for deployment scenarios where you want a ready-to-deploy directory.

How It Works

Copies entire Laravel project to the destination directory
Excludes unnecessary files (tests, node_modules, .git, etc.)
Obfuscates specified files (replaces originals with obfuscated versions)
Keeps everything else intact (config files, public assets, vendor, etc.)

Usage

# Create production-ready bundle (obfuscate all configured paths)
php artisan obfuscate:run --production-ready

# Production bundle with only specific directories obfuscated
php artisan obfuscate:run --production-ready --source=app --source=routes

# Complete CI/CD deployment package
php artisan obfuscate:run --production-ready --destination=dist/deploy --force

What Gets Included/Excluded

Excluded by default:

.git/, .github/, tests/ - Version control and test files
node_modules/, vendor/ - Dependencies (install via npm/composer in production)
.env* files - Environment-specific (create in production)
composer.lock, package-lock.json - Generated during install
Cache and log files from storage/ and bootstrap/cache/
Development configs (.editorconfig, phpunit.xml, etc.)

Always included:

composer.json - Required for composer install --no-dev
package.json - Required for npm install --production (if needed)
artisan, public/index.php, server.php
Your obfuscated source code (app/, routes/, etc.)
Views, config files, migrations, public assets

Configuration: Edit config/obfuscator.php → production_bundle section to customize.

📖 Full Deployment Guide: See docs/PRODUCTION_DEPLOYMENT.md for complete step-by-step deployment instructions.

Example: Deploy-Ready Package

# Create production bundle ready for deployment
php artisan obfuscate:run \
  --production-ready \
  --destination=deploy/production \
  --source=app \
  --source=routes \
  --force

# Result: deploy/production/ contains:
# - Complete Laravel application structure
# - app/ directory is obfuscated
# - routes/ directory is obfuscated
# - composer.json (for running: composer install --no-dev)
# - Everything else except vendor/, node_modules/, .env
#
# Deploy to server:
# 1. Upload deploy/production/ to server
# 2. cd /var/www/html
# 3. composer install --no-dev --optimize-autoloader
# 4. npm install --production (if needed)
# 5. cp .env.example .env && php artisan key:generate
# 6. php artisan config:cache && php artisan route:cache

2. Check Configuration

Verify PHPBolt installation and preview files to be obfuscated:

php artisan obfuscate:check

Options:

--show-files - Display complete list of files that will be obfuscated

Example:

php artisan obfuscate:check --show-files

3. View Status

Display obfuscation status and information:

php artisan obfuscate:status

Options:

--report - Display the last obfuscation report

Example:

php artisan obfuscate:status --report

4. Clear Output/Backups

Clean obfuscated output and backup directories:

php artisan obfuscate:clear

Options:

--output - Clear only the output directory
--backups - Clear only backup directories
--force - Skip confirmation prompt

Examples:

# Clear everything (with confirmation)
php artisan obfuscate:clear

# Clear only output directory
php artisan obfuscate:clear --output --force

# Clear only backups
php artisan obfuscate:clear --backups --force

CI/CD Integration

GitHub Actions Example

name: Deploy with Obfuscation

on:
    push:
        branches: [main]

jobs:
    deploy:
        runs-on: ubuntu-latest

        steps:
            - uses: actions/checkout@v3

            - name: Setup PHP
              uses: shivammathur/setup-php@v2
              with:
                  php-version: "8.2"

            - name: Install Dependencies
              run: composer install --no-dev --optimize-autoloader

            - name: Install PHPBolt
              run: |
                  # Install PHPBolt (adjust based on your setup)
                  wget https://your-phpbolt-url/phpbolt-installer.sh
                  bash phpbolt-installer.sh

            - name: Check Obfuscation Setup
              run: php artisan obfuscate:check

            - name: Obfuscate Source Code
              run: php artisan obfuscate:run --force

            - name: Upload Obfuscated Code
              uses: actions/upload-artifact@v3
              with:
                  name: obfuscated-application
                  path: production/obfuscated/

            - name: Upload Report
              uses: actions/upload-artifact@v3
              with:
                  name: obfuscation-report
                  path: build/obfuscation-report.json

GitLab CI Example

stages:
    - build
    - obfuscate
    - deploy

obfuscate:
    stage: obfuscate
    image: php:8.2
    before_script:
        - composer install --no-dev --optimize-autoloader
        - bash install-phpbolt.sh
    script:
        - php artisan obfuscate:check
        - php artisan obfuscate:run --force
    artifacts:
        paths:
            - production/obfuscated/
            - build/obfuscation-report.json
        expire_in: 1 week

Jenkins Pipeline Example

pipeline {
    agent any

    stages {
        stage('Install Dependencies') {
            steps {
                sh 'composer install --no-dev --optimize-autoloader'
            }
        }

        stage('Setup PHPBolt') {
            steps {
                sh 'bash install-phpbolt.sh'
            }
        }

        stage('Verify Configuration') {
            steps {
                sh 'php artisan obfuscate:check'
            }
        }

        stage('Obfuscate') {
            steps {
                sh 'php artisan obfuscate:run --force'
            }
        }

        stage('Archive Artifacts') {
            steps {
                archiveArtifacts artifacts: 'production/obfuscated/**/*', fingerprint: true
                archiveArtifacts artifacts: 'build/obfuscation-report.json', fingerprint: true
            }
        }
    }
}

Best Practices

1. Test Before Production

Always test obfuscated code in a staging environment:

# Use dry-run first
php artisan obfuscate:run --dry-run

# Check what will be obfuscated
php artisan obfuscate:check --show-files

# Run actual obfuscation
php artisan obfuscate:run

2. Exclude Blade Templates

Blade templates should generally not be obfuscated as they need to be parsed by Laravel:

'exclude_paths' => [
    '*.blade.php',
],

3. Be Careful with Function/Class Scrambling

Scrambling function and class names can break:

Reflection-based code
Dynamic method calls
External integrations

Start with these options disabled:

'scramble_functions' => false,
'scramble_classes' => false,

4. Maintain Backups

Always keep backups enabled:

'backup' => [
    'enabled' => true,
    'keep_last' => 5,
],

5. Version Control

Add to .gitignore:

/production/obfuscated/
/backups/
build/obfuscation-report.json

6. Monitor Performance

For large codebases, adjust performance settings:

'performance' => [
    'parallel_processes' => 4,  // Adjust based on available CPU
    'memory_limit' => '1G',
    'timeout' => 120,
],

Troubleshooting

PHPBolt Extension Not Loaded

Error: PHPBolt extension (bolt.so) is not loaded

Solution: Verify bolt.so extension is loaded:

# Check if extension is loaded
php -m | grep bolt

# Check extension directory
php -i | grep extension_dir

# Verify bolt.so exists
ls -l $(php-config --extension-dir)/bolt.so

# Check if enabled
php -r "var_dump(extension_loaded('bolt'));"

# If not loaded, enable it
echo "extension=bolt.so" | sudo tee /etc/php/8.2/mods-available/bolt.ini
sudo phpenmod bolt
sudo systemctl restart php8.2-fpm

Permission Denied

Error: Permission denied when creating output directory

Solution: Ensure Laravel has write permissions:

chmod -R 775 build/
chmod -R 775 backups/

Memory Limit Exceeded

Error: Allowed memory size exhausted

Solution: Increase memory limit in configuration:

'performance' => [
    'memory_limit' => '1G',  // Increase as needed
],

Files Not Being Obfuscated

Solution: Check your include/exclude patterns:

php artisan obfuscate:check --show-files

Security Considerations

Source Code Protection - Keep your original source code secure and separate from obfuscated versions
License Keys - Store PHPBolt license keys securely
Backup Security - Ensure backup directories are not publicly accessible
Deploy Only Obfuscated Code - Never deploy unobfuscated code to production
Access Control - Limit access to obfuscation commands in production environments

Performance Tips

Exclude Unnecessary Files - Only obfuscate what needs protection
Use Parallel Processing - Enable parallel processing for faster obfuscation
Optimize File Scanning - Use specific include paths rather than entire directories
CI/CD Caching - Cache PHPBolt installation in CI/CD pipelines

Support & Contributing

Issues

If you encounter any issues, please check:

PHPBolt installation and configuration
File permissions
Configuration file settings

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This package is open-sourced software licensed under the MIT license.

Credits

Alexandru Florea - Package Author
PHPBolt - Obfuscation Engine
Inspired by jaydeepukani/laravel-source-obfuscator for command-line path override ideas

Changelog

Version 1.0.0 (Initial Release)

PHPBolt integration
Configurable include/exclude paths
Four CLI commands (run, check, status, clear)
Automatic backup system
CI/CD support
Performance optimization options
Comprehensive reporting

Roadmap

Support for additional obfuscation engines
Web-based configuration UI
Real-time obfuscation monitoring
Integration with Laravel Forge
Docker support
Advanced scheduling options

Note: PHPBolt is a commercial product. You need a valid PHPBolt license to use this package. This package is not affiliated with or endorsed by PHPBolt.

aflorea4 / laravel-source-obfuscator

Maintainers

Details

README

Features

Requirements

Installation

1. Install via Composer

2. Install PHPBolt Extension

3. Publish Configuration

4. Configure Encryption Key

Runtime Configuration (Production)

1. Install bolt.so Extension in Production

2. Define PHP_BOLT_KEY Constant

Configuration

PHPBolt Extension Configuration

Include/Exclude Paths

Obfuscation Options

Backup Configuration

CI/CD Mode

Performance Settings

Usage

Available Commands

1. Obfuscate Source Code

🚀 Production-Ready Bundle Mode

How It Works

Usage

What Gets Included/Excluded

Example: Deploy-Ready Package

2. Check Configuration

3. View Status

4. Clear Output/Backups

CI/CD Integration

GitHub Actions Example

GitLab CI Example

Jenkins Pipeline Example

Best Practices

1. Test Before Production

2. Exclude Blade Templates

3. Be Careful with Function/Class Scrambling

4. Maintain Backups

5. Version Control

6. Monitor Performance

Troubleshooting

PHPBolt Extension Not Loaded

Permission Denied

Memory Limit Exceeded

Files Not Being Obfuscated

Security Considerations

Performance Tips

Support & Contributing

Issues

Contributing

License

Credits

Changelog

Version 1.0.0 (Initial Release)

Roadmap