Download the PHP package wazza/laravel-db-encryption without Composer

Laravel DB Encryption

A production-ready Laravel package for secure, transparent encryption of sensitive model attributes. Store encrypted data in a dedicated table while keeping your main tables clean and performant.

🔐 Why This Package?

• Transparent Encryption: Automatic encryption/decryption via Eloquent trait
• Separate Storage: Encrypted data stored in dedicated encrypted_attributes table
• Searchable: Filter encrypted data using SHA-256 hash indexes
• Zero Configuration: Works out of the box with sensible defaults
• Production Ready: Comprehensive error handling, logging, and security features
• Performance: Batch operations and optimized queries
• Compliance Ready: Helps meet GDPR, HIPAA, PCI DSS requirements

📋 Requirements

• PHP: 8.2 or higher
• Laravel: 12.x
• OpenSSL: PHP OpenSSL extension

🚀 Installation

1. Install via Composer

2. Publish Configuration & Migrations

3. Generate Encryption Key

This adds DB_ENCRYPT_KEY to your .env file.

4. Run Migrations

📖 Usage

Basic Setup

Add the HasEncryptedAttributes trait to your model and define which attributes should be encrypted:

Working with Encrypted Attributes

Searching Encrypted Data

Use the whereEncrypted scope to search encrypted attributes:

Using the Facade

For direct encryption/decryption operations:

🛠️ Advanced Features

Artisan Commands

Generate Encryption Key

Re-encrypt Data (Key Rotation)

Prune Orphaned Records

Configuration

Edit config/db-encrypt.php:

Custom Exceptions

The package provides specific exceptions for better error handling:

🔒 Security Best Practices

1. Key Management

• Never commit encryption keys to version control
• Use different keys for each environment
• Rotate keys periodically using db-encrypt:re-encrypt
• Consider using a Key Management Service (KMS) in production

2. What to Encrypt

✅ Good candidates:

• Social Security Numbers
• Credit card numbers
• Passwords (though hashing is usually better)
• Medical records
• Personal identification numbers
• Private notes

❌ Bad candidates:

• Primary keys or foreign keys
• Data you need to sort by
• Data used in mathematical operations
• High-cardinality lookup values

3. Performance Considerations

• Encryption adds overhead—only encrypt truly sensitive data
• Use indexes on your main tables for performance
• Consider caching decrypted data for read-heavy operations
• Use batch operations when encrypting/decrypting multiple values

4. Backup Strategy

• Always backup before key rotation
• Test key rotation in staging first
• Keep old keys until you verify re-encryption succeeded

See SECURITY.md for comprehensive security guidelines.

🧪 Testing

🐛 Troubleshooting

"Encryption key is not set"

Solution: Run php artisan db-encrypt:generate-key or manually set DB_ENCRYPT_KEY in .env

"Cannot encrypt attribute 'name' because it exists as a column"

Solution: Encrypted properties must NOT exist as database columns. Remove the column or choose a different property name.

"Decryption failed"

Possible causes:

• Wrong encryption key
• Corrupted data
• Key was rotated but data wasn't re-encrypted

Solution:

1. Verify DB_ENCRYPT_KEY is correct
2. Check logs for detailed error messages
3. Restore from backup if data is corrupted

Performance issues

Solutions:

• Ensure indexes are created on encrypted_attributes table (done automatically)
• Reduce logging level in production (DB_ENCRYPT_LOG_LEVEL=0)
• Use batch operations for multiple encryptions
• Consider caching frequently accessed encrypted data

Search not finding records

Check:

• Ensure you're using whereEncrypted() scope
• Verify the exact value (encryption is case-sensitive)
• Check that hash_index was generated correctly

📊 Monitoring

View Package Logs

Check Encryption Status

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Write tests for your changes
4. Ensure all tests pass (./vendor/bin/pest)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📜 License

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

👨‍💻 Author

Warren Coetzee

• Website: wazzac.dev
• Email: [email protected]
• GitHub: @wazzac

🙏 Acknowledgments

• Built for the Laravel community
• Inspired by the need for simple, secure database encryption
• Thanks to all contributors and users

☕ Support

If this package helps you, consider buying me a coffee!

📝 Changelog

See CHANGELOG.md for what has changed recently.

🛡️ Security

Please review our security policy for reporting security vulnerabilities.

Made with ❤️ for the Laravel community