Skip to content

Commit f7b8063

Browse files
wazzacwazzac
authored
Merge pull request #1 from wazzac/develop/v0.1.0
Develop/v0.1.0: First Alpha release.
2 parents 482b66c + 737c394 commit f7b8063

25 files changed

+11514
-3
lines changed

‎.gitignore

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Node.js
2+
node_modules/
3+
.npm/
4+
.yarn/
5+
6+
# Editor-specific
7+
/.vscode/
8+
9+
# Generated files
10+
.idx/
11+
12+
# Composer
13+
vendor/

‎CHANGELOG.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
## v0.1.0-alpha `2025-06-14`
2+
3+
Initial Alpha release. The package is functional, with documentation and unit tests included.
4+
5+
### Added
6+
7+
- Complete package scaffolding and setup.
8+
- Database migration for encrypted data storage.
9+
- Encryption table Eloquent model.
10+
- Reusable trait for model property/attribute encryption.
11+
- Core encryption controller.
12+
- Comprehensive documentation, including installation and usage guides.
13+
- Configuration file for package customization.

‎CODE_OF_CONDUCT.md

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our
6+
community a harassment-free experience for everyone, regardless of age, body
7+
size, visible or invisible disability, ethnicity, sex characteristics, gender
8+
identity and expression, level of experience, education, socio-economic status,
9+
nationality, personal appearance, race, religion, or sexual identity
10+
and orientation.
11+
12+
We pledge to act and interact in ways that contribute to an open, welcoming,
13+
diverse, inclusive, and healthy community.
14+
15+
## Our Standards
16+
17+
Examples of behavior that contributes to a positive environment for our
18+
community include:
19+
20+
* Demonstrating empathy and kindness toward other people
21+
* Being respectful of differing opinions, viewpoints, and experiences
22+
* Giving and gracefully accepting constructive feedback
23+
* Accepting responsibility and apologizing to those affected by our mistakes,
24+
and learning from the experience
25+
* Focusing on what is best not just for us as individuals, but for the
26+
overall community
27+
28+
Examples of unacceptable behavior include:
29+
30+
* The use of sexualized language or imagery, and sexual attention or
31+
advances of any kind
32+
* Trolling, insulting or derogatory comments, and personal or political attacks
33+
* Public or private harassment
34+
* Publishing others' private information, such as a physical or email
35+
address, without their explicit permission
36+
* Other conduct which could reasonably be considered inappropriate in a
37+
professional setting
38+
39+
## Enforcement Responsibilities
40+
41+
Community leaders are responsible for clarifying and enforcing our standards of
42+
acceptable behavior and will take appropriate and fair corrective action in
43+
response to any behavior that they deem inappropriate, threatening, offensive,
44+
or harmful.
45+
46+
Community leaders have the right and responsibility to remove, edit, or reject
47+
comments, commits, code, wiki edits, issues, and other contributions that are
48+
not aligned to this Code of Conduct, and will communicate reasons for moderation
49+
decisions when appropriate.
50+
51+
## Scope
52+
53+
This Code of Conduct applies within all community spaces, and also applies when
54+
an individual is officially representing the community in public spaces.
55+
Examples of representing our community include using an official e-mail address,
56+
posting via an official social media account, or acting as an appointed
57+
representative at an online or offline event.
58+
59+
## Enforcement
60+
61+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
62+
reported to the community leaders responsible for enforcement at
63+
realstoman@gmail.com.
64+
All complaints will be reviewed and investigated promptly and fairly.
65+
66+
All community leaders are obligated to respect the privacy and security of the
67+
reporter of any incident.
68+
69+
## Enforcement Guidelines
70+
71+
Community leaders will follow these Community Impact Guidelines in determining
72+
the consequences for any action they deem in violation of this Code of Conduct:
73+
74+
### 1. Correction
75+
76+
**Community Impact**: Use of inappropriate language or other behavior deemed
77+
unprofessional or unwelcome in the community.
78+
79+
**Consequence**: A private, written warning from community leaders, providing
80+
clarity around the nature of the violation and an explanation of why the
81+
behavior was inappropriate. A public apology may be requested.
82+
83+
### 2. Warning
84+
85+
**Community Impact**: A violation through a single incident or series
86+
of actions.
87+
88+
**Consequence**: A warning with consequences for continued behavior. No
89+
interaction with the people involved, including unsolicited interaction with
90+
those enforcing the Code of Conduct, for a specified period of time. This
91+
includes avoiding interactions in community spaces as well as external channels
92+
like social media. Violating these terms may lead to a temporary or
93+
permanent ban.
94+
95+
### 3. Temporary Ban
96+
97+
**Community Impact**: A serious violation of community standards, including
98+
sustained inappropriate behavior.
99+
100+
**Consequence**: A temporary ban from any sort of interaction or public
101+
communication with the community for a specified period of time. No public or
102+
private interaction with the people involved, including unsolicited interaction
103+
with those enforcing the Code of Conduct, is allowed during this period.
104+
Violating these terms may lead to a permanent ban.
105+
106+
### 4. Permanent Ban
107+
108+
**Community Impact**: Demonstrating a pattern of violation of community
109+
standards, including sustained inappropriate behavior, harassment of an
110+
individual, or aggression toward or disparagement of classes of individuals.
111+
112+
**Consequence**: A permanent ban from any sort of public interaction within
113+
the community.
114+
115+
## Attribution
116+
117+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
118+
version 2.0, available at
119+
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
120+
121+
Community Impact Guidelines were inspired by [Mozilla's code of conduct
122+
enforcement ladder](https://github.com/mozilla/diversity).
123+
124+
[homepage]: https://www.contributor-covenant.org
125+
126+
For answers to common questions about this code of conduct, see the FAQ at
127+
https://www.contributor-covenant.org/faq. Translations are available at
128+
https://www.contributor-covenant.org/translations.

‎CONTRIBUTING.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Contributing
2+
3+
Thank you for considering to contribute to `laravel-db-encryption` 💖
4+
5+
We are always open for code improvements and features.
6+
7+
Please note that this project is released with a [Code of Conduct](https://github.com/wazzac/laravel-db-encryption/blob/main/CODE_OF_CONDUCT.md). By participating you agree to abide by its terms.
8+
9+
Since this package provides encryption features, please be mindful what data is written to the log file.
10+
11+
Lastly, for any new coding updates; please also include a unit test. Thank you 😉
12+
13+
## Setup
14+
15+
#### Fork this repo
16+
17+
[https://github.com/wazzac/laravel-db-encryption](https://github.com/wazzac/laravel-db-encryption)
18+
19+
#### Check the issues section if there are already issues and see if you can fix them
20+
21+
22+
[https://github.com/wazzac/laravel-db-encryption/issues](https://github.com/wazzac/laravel-db-encryption/issues)
23+
24+
#### If the issue is new, add the code to the fork of the repository and then create a pull request.
25+
26+
#### Add Feat or Fix to the pull request title so maintainer understand what this issue is about.

‎LICENSE

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
MIT License
22

3-
Copyright (c) 2024 Warren Coetzee
3+
Copyright (c) 2025 Warren Coetzee
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

‎README.md

Lines changed: 117 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,117 @@
1-
# laravel-db-encryption
2-
A Laravel package that helps encrypt & decrypt certain defined table columns ensuring the data is secure in the database but can be accessed by the models.
1+
# Laravel DB Encryptor
2+
3+
A Laravel package for secure, transparent encryption and decryption of sensitive model attributes, storing them in a dedicated table while keeping your main tables clean and fast.
4+
5+
## Features
6+
- Seamless encryption/decryption of model attributes via a simple trait
7+
- Encrypted data is stored in a separate `encrypted_attributes` table
8+
- Only non-table attributes can be encrypted (enforced at runtime)
9+
- Automatic loading and saving of encrypted attributes using Eloquent events
10+
- **Search/filter on encrypted properties using SHA-256 hash**
11+
- No sensitive values are ever logged
12+
- Easy integration: just add the trait and define `$encryptedProperties` in your model
13+
- Compatible with Laravel 9+
14+
15+
## Requirements
16+
- PHP 8.1+
17+
- Laravel 9 or higher
18+
- OpenSSL PHP extension
19+
20+
## How It Works
21+
1. Add the `HasEncryptedAttributes` trait to your Eloquent model.
22+
2. Define a public array property `$encryptedProperties` listing the attributes you want encrypted (these must NOT exist as columns in the model's table).
23+
3. When you load a model, encrypted attributes are automatically decrypted and available as normal properties.
24+
4. When you save a model, encrypted attributes are removed from the main table and securely stored in the `encrypted_attributes` table.
25+
5. **You can filter/search on encrypted properties using the provided query scope.**
26+
27+
**Example Model:**
28+
```php
29+
use Wazza\DbEncrypt\Traits\HasEncryptedAttributes;
30+
31+
class User extends Model
32+
{
33+
use HasEncryptedAttributes;
34+
35+
protected $fillable = ['name', 'email'];
36+
37+
// Only non-table attributes can be encrypted!
38+
public array $encryptedProperties = [
39+
'social_security_number',
40+
'private_note',
41+
];
42+
}
43+
```
44+
45+
## Usage
46+
- Use your model as normal:
47+
```php
48+
$user = User::find(1);
49+
$user->social_security_number = '123-45-6789';
50+
$user->private_note = 'Sensitive info';
51+
$user->save();
52+
53+
// When you retrieve the user again, encrypted attributes are automatically decrypted:
54+
$user = User::find(1);
55+
echo $user->social_security_number; // '123-45-6789'
56+
```
57+
- If you try to add an attribute to `$encryptedProperties` that already exists as a column, an exception will be thrown.
58+
59+
### Filtering/Search on Encrypted Properties
60+
You can filter or search for models by encrypted property value using the built-in query scope:
61+
62+
```php
63+
// Find users with a specific social security number
64+
$users = User::whereEncrypted('social_security_number', '123-45-6789')->get();
65+
```
66+
67+
This uses the SHA-256 hash of the value and joins the `encrypted_attributes` table for efficient searching, without ever exposing the decrypted value in the query or logs.
68+
69+
## Installation Steps
70+
1. Require the package in your Laravel project:
71+
```sh
72+
composer require wazza/laravel-db-encryption
73+
```
74+
2. Publish the config and migration files (if needed):
75+
```sh
76+
php artisan vendor:publish --provider="Wazza\DbEncrypt\DbEncryptServiceProvider"
77+
```
78+
3. Run the migration to create the `encrypted_attributes` table:
79+
```sh
80+
php artisan migrate
81+
```
82+
4. Add the trait and `$encryptedProperties` to your models as shown above.
83+
84+
## Monitoring & Logs
85+
- All encryption/decryption operations are logged (without sensitive values).
86+
- To monitor package logs:
87+
```sh
88+
tail -f storage/logs/laravel.log | grep db-encrypt
89+
```
90+
91+
## Testing
92+
- Run the test suite using Pest:
93+
```sh
94+
./vendor/bin/pest
95+
96+
PASS Tests\Unit\EncryptorTest
97+
✓ it correctly hashes the value 0.40s
98+
✓ it correctly encrypts and decrypts data 0.15s
99+
✓ it returns different ciphertext for same plaintext (random IV) 0.12s
100+
✓ it throws on null input for encrypt 0.13s
101+
✓ it throws on null input for decrypt 0.13s
102+
✓ it throws on invalid base64 for decrypt 0.14s
103+
✓ it throws on missing key in config 0.19s
104+
105+
PASS Tests\Unit\ExampleTest
106+
✓ that true is true 0.28s
107+
108+
PASS Tests\Feature\ExampleTest
109+
✓ it contains a successful example feature test 0.18s
110+
111+
Tests: 9 passed (9 assertions)
112+
Duration: 1.98s
113+
```
114+
- Ensure your models and encrypted attributes behave as expected.
115+
116+
---
117+
For more details, see the source code and comments. Contributions and issues welcome!

‎composer.json

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
{
2+
"name": "wazza/laravel-db-encryption",
3+
"description": "A Laravel package that helps encrypt & decrypt certain defined table columns ensuring the data is secure in the database but can be accessed by the models.",
4+
"type": "library",
5+
"keywords": [
6+
"laravel",
7+
"encryption",
8+
"db-encryption",
9+
"secure",
10+
"package"
11+
],
12+
"homepage": "https://www.wazzac.dev",
13+
"repository": "https://github.com/wazzac/laravel-db-encryption",
14+
"readme": "README.md",
15+
"require": {
16+
"ext-json": "*",
17+
"illuminate/support": "^12.0",
18+
"php": "^8.2 || ^8.3"
19+
},
20+
"require-dev": {
21+
"fakerphp/faker": "^1.20.0",
22+
"laravel/legacy-factories": "~1",
23+
"mockery/mockery": "^1.2",
24+
"orchestra/testbench": "^10.0",
25+
"pestphp/pest": "^3.8",
26+
"pestphp/pest-plugin-laravel": "^3.2",
27+
"phpunit/phpunit": "^11.0"
28+
},
29+
"license": "MIT",
30+
"autoload": {
31+
"psr-4": {
32+
"Wazza\\DbEncrypt\\": "src/"
33+
}
34+
},
35+
"autoload-dev": {
36+
"psr-4": {
37+
"Wazza\\DbEncrypt\\": "src/",
38+
"Wazza\\DbEncrypt\\Tests\\": "tests/",
39+
"Wazza\\DbEncrypt\\Database\\Factories\\": "database/factories/",
40+
"Wazza\\DbEncrypt\\Database\\Seeders\\": "database/seeders/"
41+
}
42+
},
43+
"extra": {
44+
"laravel": {
45+
"providers": [
46+
"Wazza\\DbEncrypt\\Providers\\DbEncryptServiceProvider"
47+
],
48+
"aliases": {
49+
"DbEncrypt": "Wazza\\DbEncrypt\\Facades\\DbEncrypt"
50+
}
51+
}
52+
},
53+
"authors": [
54+
{
55+
"name": "Warren Coetzee",
56+
"email": "warren.coetzee@gmail.com",
57+
"homepage": "https://www.wazzac.dev"
58+
}
59+
],
60+
"support": {
61+
"issues": "https://github.com/wazzacdev/laravel-db-encryption/issues",
62+
"source": "https://github.com/wazzacdev/laravel-db-encryption"
63+
},
64+
"scripts": {
65+
"post-autoload-dump": [
66+
"@php ./vendor/bin/testbench package:discover --ansi"
67+
]
68+
},
69+
"minimum-stability": "stable",
70+
"prefer-stable": true,
71+
"config": {
72+
"allow-plugins": {
73+
"pestphp/pest-plugin": true
74+
}
75+
}
76+
}

0 commit comments

Comments
 (0)