Download the PHP package hamoi1/eloquent-encryptable without Composer

🔐 Eloquent Encryptable

A powerful Laravel package for encrypting Eloquent model attributes using the Hill Cipher algorithm with multi-language support.

✨ Features

• 🔒 Hill Cipher Encryption: Advanced matrix-based encryption algorithm
• 🌐 Multi-language Support: English, Kurdish, and Arabic character sets
• 🚀 Automatic Encryption/Decryption: Seamless model attribute handling
• ✅ Validation Rules: Built-in unique and exists validation for encrypted fields
• 🎨 Blade Directives: Easy encryption/decryption in views
• 🔄 Key Rotation: Re-encrypt data with new keys using console commands
• ⚡ Performance Optimized: Chunked processing for large datasets

📋 Table of Contents

• Installation
• Configuration
• Usage
  • Basic Usage
  • Validation Rules
  • Blade Directives
  • Console Commands
• Advanced Usage
• API Reference
• Troubleshooting
• Contributing
• License

🚀 Installation

Install the package via Composer:

Publish the configuration file:

⚙️ Configuration

After publishing, configure your encryption settings in config/eloquent-encryptable.php:

🔑 Key Matrix Requirements

• Size: 2x2 or 3x3 square matrix
• Invertible: Must have a determinant that is coprime with the alphabet size
• Format: JSON string representation of the matrix

Example valid matrices:

📖 Usage

Basic Usage

Add the EncryptAble trait to your Eloquent model and define the $encryptAble property:

Now your specified attributes will be automatically encrypted when saving and decrypted when retrieving:

Validation Rules

The package provides custom validation rules for encrypted fields:

Unique Rule

Ensure encrypted field values are unique:

Exists Rule

Validate that encrypted field value exists:

Blade Directives

Use convenient Blade directives in your views:

Example in a Blade template:

Console Commands

Re-encrypt Data

When rotating encryption keys, use the console command to re-encrypt existing data:

This command will:

1. Load models from the configuration
2. Decrypt data using the previous key
3. Re-encrypt using the new key
4. Show progress bars and timing information
5. Process data in chunks for memory efficiency

🔧 Advanced Usage

Manual Encryption/Decryption

Access the encryption service directly:

Batch Operations

Process multiple model attributes:

Custom Key Matrix Generation

Generate a random invertible key matrix:

📚 API Reference

EncryptAble Trait

EloquentEncryptAbleService

Validation Rules

🔍 Troubleshooting

Common Issues

1. Invalid Key Matrix Error

Solution: Ensure your key matrix is:

• A valid JSON string
• Square (2x2 or 3x3)
• Invertible (determinant coprime with alphabet size)

2. Memory Issues with Large Datasets

Solution: The re-encrypt command processes data in chunks of 100. For very large datasets, consider:

• Increasing PHP memory limit
• Processing models individually
• Running during off-peak hours

3. Character Encoding Issues

Solution: Ensure your database columns support UTF-8 encoding:

Debug Mode

Enable debug logging by adding to your model:

🤝 Contributing

We welcome contributions! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Follow the development setup below
4. Make your changes and add tests
5. Ensure all tests pass and code follows PSR-12 standards
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Development Setup

1. Clone the repository

2. Install dependencies

3. Set up testing environment

4. Create test configuration Create config/eloquent-encryptable.php for testing:

Project Structure

Adding New Features

When adding new features:

1. Create tests first (TDD approach)
2. Follow existing patterns in the codebase
3. Update documentation in README.md
4. Add PHPDoc comments for all public methods

5. Consider backward compatibility

📄 License

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