README

A powerful PHP package that extends Jenssegers\Optimus to support both 64-bit and 32-bit ID obfuscation with intelligent auto-detection, multiple connections, and seamless Laravel integration.

✨ Features

🔧 Built on Jenssegers\Optimus: Leverages the proven and battle-tested 32-bit implementation
🚀 Dual Bit Support: Seamlessly handles both 32-bit and 64-bit integers with automatic detection
🔄 100% Backward Compatible: Drop-in replacement for existing Jenssegers\Optimus implementations
🔗 Multiple Connections: Configure and use multiple Optimus instances for different use cases
🧠 Intelligent Auto-Detection: Automatically selects the appropriate bit size based on input value
🎯 Laravel Ready: Complete Laravel integration with service provider, facade, and configuration
⚡ High Performance: Optimized for speed with minimal overhead
🧪 Thoroughly Tested: Comprehensive PHPUnit test suite with Orchestra Testbench
📦 Easy Installation: Simple Composer installation with auto-discovery

📋 Requirements

PHP: 8.1 or higher
Extensions: ext-gmp (for 64-bit operations)
Dependencies: jenssegers/optimus ^1.1
Laravel: 10.0+ (optional, for Laravel integration)

📦 Installation

Install the package via Composer:

composer require mostafaaminflakes/dual-optimus

Laravel Integration

The package automatically registers itself in Laravel 5.5+. For older versions, manually add to config/app.php:

'providers' => [
    MostafaAminFlakes\DualOptimus\DualOptimusServiceProvider::class,
],

'aliases' => [
    'DualOptimus' => MostafaAminFlakes\DualOptimus\Facades\DualOptimus::class,
],

Publish the configuration file:

php artisan vendor:publish --provider="MostafaAminFlakes\DualOptimus\DualOptimusServiceProvider"

⚙️ Configuration

Environment Variables

Add these variables to your .env file:

# 64-bit configuration (recommended for new projects)
DUAL_OPTIMUS_PRIME_64=9223372036854775783
DUAL_OPTIMUS_INVERSE_64=9223372036854775783
DUAL_OPTIMUS_RANDOM_64=4611686018427387904

# 32-bit configuration (for backward compatibility)
DUAL_OPTIMUS_PRIME_32=1580030173
DUAL_OPTIMUS_INVERSE_32=59260789
DUAL_OPTIMUS_RANDOM_32=1163945558

Configuration File

The published config/dual-optimus.php file contains:

return [
    'default' => 'main',
    
    'connections' => [
        'main' => [
            'prime'   => env('DUAL_OPTIMUS_PRIME_64', 9223372036854775783),
            'inverse' => env('DUAL_OPTIMUS_INVERSE_64', 9223372036854775783),
            'random'  => env('DUAL_OPTIMUS_RANDOM_64', 4611686018427387904),
            'size'    => 64,
        ],
        
        'legacy' => [
            'prime'   => env('DUAL_OPTIMUS_PRIME_32', 1580030173),
            'inverse' => env('DUAL_OPTIMUS_INVERSE_32', 59260789),
            'random'  => env('DUAL_OPTIMUS_RANDOM_32', 1163945558),
            'size'    => 32,
        ],
    ],
];

🚀 Usage

Basic Usage

use MostafaAminFlakes\DualOptimus\Facades\DualOptimus;

// Automatic bit-size detection
$encoded = DualOptimus::encode(123);           // Uses 32-bit (legacy connection)
$decoded = DualOptimus::decode($encoded);      // Returns: 123

// Large values automatically use 64-bit
$bigEncoded = DualOptimus::encode(9876543210); // Uses 64-bit (main connection)
$bigDecoded = DualOptimus::decode($bigEncoded); // Returns: 9876543210

Force 64-bit Operations

// Force 64-bit encoding for any value
$encoded64 = DualOptimus::encode64(123);
$decoded64 = DualOptimus::decode64($encoded64);

Multiple Connections

// Use specific connections
$mainConnection = DualOptimus::connection('main');     // 64-bit
$legacyConnection = DualOptimus::connection('legacy'); // 32-bit

$mainEncoded = $mainConnection->encode(123);
$legacyEncoded = $legacyConnection->encode(123);

// List available connections
$connections = DualOptimus::getConnections(); // ['main', 'legacy']

Direct Manager Usage

$manager = app('dual-optimus');

// Use default connection
$encoded = $manager->encode(123);
$decoded = $manager->decode($encoded);

// Get specific connection
$connection = $manager->connection('main');
$encoded = $connection->encode(123);

Access Underlying Optimus

// Access the Jenssegers\Optimus instance for 32-bit operations
$optimus32 = DualOptimus::getOptimus32();
$encoded = $optimus32->encode(123);

// Use Optimus utilities
$prime = \Jenssegers\Optimus\Optimus::generateRandomPrime();
$inverse = \Jenssegers\Optimus\Optimus::calculateInverse($prime);

🔧 Artisan Commands

Generate new Optimus keys:

# Generate 32-bit keys
php artisan dual-optimus:generate 32

# Generate 64-bit keys  
php artisan dual-optimus:generate 64

🧪 Testing

Run the complete test suite:

composer test

Run tests with coverage report:

composer test-coverage

Run specific test suites:

# Unit tests only
vendor/bin/phpunit tests/Unit

# Feature tests only  
vendor/bin/phpunit tests/Feature

🔄 Migration from Jenssegers\Optimus

Dual Optimus is a 100% drop-in replacement for Jenssegers\Optimus:

// Before (Jenssegers\Optimus)
$optimus = new \Jenssegers\Optimus\Optimus($prime, $inverse, $random);
$encoded = $optimus->encode(123);

// After (Dual Optimus) - same result!
$encoded = DualOptimus::encode(123);

// Access original Optimus if needed
$originalOptimus = DualOptimus::getOptimus32();

All existing encoded values will decode correctly - no data migration required!

📊 Performance

Dual Optimus adds minimal overhead while providing significant functionality:

32-bit operations: Identical performance to Jenssegers\Optimus (uses it directly)
64-bit operations: Optimized GMP operations with caching
Auto-detection: Simple integer comparison with negligible cost
Memory usage: Minimal additional memory footprint

🛡️ Security Considerations

Cryptographically Secure: Uses the same proven algorithms as Jenssegers\Optimus
No Data Leakage: Values are obfuscated, not encrypted (reversible by design)
Key Management: Store your prime/inverse/random values securely
Environment Variables: Use .env files and never commit keys to version control

🤝 Contributing

We welcome contributions! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Add tests for new functionality
Ensure all tests pass (composer test)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

git clone https://github.com/mostafaaminflakes/dual-optimus.git
cd dual-optimus
composer install
composer test

📝 Changelog

v1.0.0 - Initial Release

✅ 64-bit ID support with automatic detection
✅ Full backward compatibility with 32-bit IDs
✅ Multiple connections support
✅ Laravel service provider and facade
✅ Comprehensive test suite with 100% coverage
✅ Artisan command for key generation

📄 License

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

🙏 Credits

Mostafa Amin - Creator and maintainer
Jens Segers - Original Optimus package
All contributors who help improve this package

🆘 Support

Documentation: GitHub Wiki
Issues: GitHub Issues
Discussions: GitHub Discussions

Made with ❤️ for the PHP community

mostafaaminflakes / dual-optimus

Maintainers

Details