Skip to content

Commit 118e7c3

Browse files
megyptmmegyptm
committed
fix(env-loader): prevent dotenv override and preserve runtime/test variables
Ensure EnvironmentLoader no longer overrides existing $_ENV / putenv values. Added pre-load snapshot + post-load restore mechanism to protect local, CI, and PHPUnit variables from unexpected .env overwrites. Improves reliability across libraries and guarantees test isolation.
1 parent 2b9414c commit 118e7c3

4 files changed

Lines changed: 409 additions & 53 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 115 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,117 @@
1-
# 🧾 Changelog — maatify/bootstrap
1+
# 🧾 **CHANGELOG — Maatify Bootstrap**
2+
3+
> **Project:** `maatify/bootstrap`
4+
> **Maintainer:** Mohamed Abdulalim (megyptm)
5+
> **Organization:** Maatify.dev
6+
> **License:** MIT
7+
8+
---
9+
10+
## [1.0.2] — 2025-11-13
11+
12+
### 🔒 **Stable Environment Loader (No Override Mode)**
13+
14+
A major improvement ensuring complete safety and determinism in environment loading.
15+
16+
#### ✨ Added
17+
18+
* **Pre-load snapshot system**
19+
Captures all `$_ENV` + `putenv()` variables before loading `.env`, ensuring no value is lost.
20+
21+
* **Post-load variable restoration**
22+
Re-assigns all pre-existing variables, preventing `.env` files from overriding runtime, CI, or PHPUnit test variables.
23+
24+
* **Full isolation for test environments**
25+
Guarantees that any env variables injected by PHPUnit (`putenv`, `$_ENV`) remain untouched.
26+
27+
#### 🛠 Improved
28+
29+
* Environment handling is now **predictable, deterministic, and override-proof**.
30+
* Perfect consistency across Maatify libraries (`data-adapters`, `rate-limiter`, etc.).
31+
* Strengthened compatibility with CI/CD pipelines and Dockerized environments.
32+
33+
#### 🧪 Testing
34+
35+
* Updated integration tests confirm that `.env` loading **never overrides** runtime or test variables.
36+
* Verified support for parallel test runners and isolated env contexts.
37+
38+
---
39+
40+
## [1.0.1] — 2025-11-12
41+
42+
### 📦 Dependency Update
43+
44+
* Updated requirement: `"maatify/common": "^1.0"`
45+
* Internal helpers refactored for compatibility with latest `maatify/common`.
46+
47+
*No functional or breaking changes in this release.*
48+
49+
---
250

351
## [1.0.0] — 2025-11-09
4-
### Added
5-
- Core Bootstrap initialization
6-
- Environment Loader with priority-based `.env` resolution
7-
- Diagnostics and Safe Mode system
8-
- Path & Env Helpers
9-
- Full PHPUnit coverage
10-
- GitHub Actions CI/CD workflow
11-
- Docker testing environment
12-
- Complete developer documentation
13-
14-
### Improved
15-
- Timezone fallback logic
16-
- Error handling and logging hooks
52+
53+
### 🧱 **Initial Stable Release**
54+
55+
The foundational version that introduced the full bootstrap system:
56+
57+
#### 🚀 Features
58+
59+
* `Bootstrap::init()` unified entry point
60+
* Smart `.env` loader with priority:
61+
`.env.local` → `.env.testing` → `.env` → `.env.example`
62+
* Immutable Dotenv mode
63+
* Automatic timezone setup
64+
* Diagnostics + Safe Mode
65+
* Helpers (EnvHelper, PathHelper)
66+
* Full CI & Docker integration
67+
* Complete documentation & PHPUnit coverage
68+
69+
---
70+
71+
# 📌 Summary of Recent Changes
72+
73+
| Version | Purpose | Stability |
74+
|-----------|--------------------------------------|-----------|
75+
| **1.0.2** | No override env loader + test safety | 🟢 Stable |
76+
| **1.0.1** | Update dependencies | 🟢 Stable |
77+
| **1.0.0** | Initial public release | 🟢 Stable |
78+
79+
---
80+
81+
## [1.0.0] — 2025-11-09
82+
### 🧱 Phase 1 — Foundation Setup
83+
- Initialized project structure and Composer package.
84+
- Implemented PSR-4 autoloading for `Maatify\Bootstrap\`.
85+
- Added `.env.example` and base PHPUnit configuration.
86+
- Introduced `EnvironmentLoader` with timezone fallback to `Africa/Cairo`.
87+
88+
### ⚙️ Phase 2 — Bootstrap Core
89+
- Added main `Bootstrap::init()` entry point.
90+
- Integrated environment loader and error handler.
91+
- Ensured idempotent initialization and runtime safety.
92+
93+
### 🧩 Phase 3 — Helpers & Utilities
94+
- Added `EnvHelper` (cached environment variable access).
95+
- Added `PathHelper` (consistent path resolution).
96+
- Integrated with `maatify/common` utilities.
97+
98+
### 🔗 Phase 4 — Integration Layer
99+
- Verified multi-library boot order with `maatify/data-adapters`, `maatify/rate-limiter`, and `maatify/security-guard`.
100+
- Ensured environment variables load only once per runtime.
101+
- Added CI integration tests for shared initialization.
102+
103+
### 🧠 Phase 5 — Diagnostics & Safe Mode
104+
- Implemented `BootstrapDiagnostics` class with environment, timezone, and error-handler validation.
105+
- Added Safe Mode detection when `.env.local` or `.env.testing` exist under production environment.
106+
- Integrated PSR-3 logging for diagnostic reporting.
107+
- Updated `EnvironmentLoader` to include `.env.example` as fallback.
108+
- Added complete environment-file priority documentation.
109+
- All PHPUnit tests passing across environments.
110+
111+
---
112+
113+
## 🌐 Upcoming — Phase 6: Advanced Integration & Release
114+
- Add GitHub Actions workflow for automated CI/CD.
115+
- Add Dockerfile + docker-compose for local bootstrap testing.
116+
- Auto-generate and validate documentation during CI.
117+
- Tag release **v1.0.0** and publish to Packagist.

‎CONTRIBUTING.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# 🤝 Contributing to **maatify/bootstrap**
2+
3+
Thank you for your interest in contributing to **maatify/bootstrap** —
4+
the unified initialization, environment loading, and diagnostics layer powering the entire **Maatify ecosystem**.
5+
6+
Your contributions help ensure that all Maatify projects start consistently, securely, and predictably across local, testing, and production environments.
7+
8+
---
9+
10+
## 🧩 Development Standards
11+
12+
Please follow the standards below to keep the library clean, stable, and production-ready.
13+
14+
---
15+
16+
## ⚙️ Code Style
17+
18+
* Follow **[PSR-12](https://www.php-fig.org/psr/psr-12/)** standards.
19+
* All PHP files must include:
20+
21+
```php
22+
declare(strict_types=1);
23+
```
24+
* All new classes should be declared **final** unless extensibility is explicitly required.
25+
* Add clear and consistent **DocBlocks** for:
26+
27+
* Classes
28+
* Methods
29+
* Properties
30+
* Exceptions
31+
* Avoid introducing global state — use dependency injection where possible.
32+
* Keep the bootstrap logic **idempotent** (initializes once per runtime).
33+
34+
---
35+
36+
## 🧪 Testing
37+
38+
Bootstrap controls the startup of the entire Maatify stack —
39+
therefore, **every change must be covered with PHPUnit tests**.
40+
41+
* Run the full test suite before submitting PRs:
42+
43+
```bash
44+
vendor/bin/phpunit
45+
```
46+
* Required coverage: **≥95%**.
47+
* Tests must cover:
48+
49+
* Environment loading priority
50+
* No-override safety
51+
* Timezone fallback behavior
52+
* Safe Mode detection
53+
* Bootstrap initialization idempotency
54+
55+
If your PR introduces environment-sensitive logic, include tests for:
56+
57+
* When `.env.local` is present
58+
* When `.env.testing` is present
59+
* When no `.env` file exists
60+
* When variables are pre-loaded via `putenv()` / `$_ENV`
61+
62+
---
63+
64+
## 📚 Documentation
65+
66+
* All new features require documentation under `/docs/`.
67+
* If a core phase is changed, update the corresponding
68+
`docs/README.phaseX.md` file (e.g., phase for diagnostics, loader, helpers).
69+
* Major changes must be reflected in:
70+
71+
* `README.md` (public summary)
72+
* `docs/README.full.md` (developer documentation)
73+
74+
Use fenced code blocks for examples:
75+
76+
```php
77+
Bootstrap::init();
78+
```
79+
80+
---
81+
82+
## 🧾 Changelog Rules
83+
84+
Every PR must update **[CHANGELOG.md](CHANGELOG.md)** under:
85+
86+
* `### Added`
87+
* `### Changed`
88+
* `### Fixed`
89+
* `### Removed`
90+
91+
Example:
92+
93+
```md
94+
### Fixed
95+
- Prevented `.env.testing` from loading during production bootstrap.
96+
```
97+
98+
Versioning follows **Semantic Versioning (SemVer)**:
99+
100+
* `MAJOR`: Breaking changes
101+
* `MINOR`: New features (no breaking changes)
102+
* `PATCH`: Fixes or improvements
103+
104+
---
105+
106+
## 🪄 Commit Message Format
107+
108+
Follow conventional commits:
109+
110+
| Type | Meaning | Example |
111+
| -------- | -------------------------- | -------------------------------------- |
112+
| `feat:` | New feature | `feat: add SafeMode diagnostics` |
113+
| `fix:` | Bug fix | `fix: prevent .env override in loader` |
114+
| `docs:` | Documentation update | `docs: improve bootstrap examples` |
115+
| `test:` | Adding or updating tests | `test: cover timezone fallback` |
116+
| `chore:` | Maintenance, CI, versions… | `chore(release): prepare v1.0.2` |
117+
118+
---
119+
120+
## 🧭 Branch Naming Guidelines
121+
122+
| Purpose | Prefix Example |
123+
| ------- | ---------------------------- |
124+
| Feature | `feature/env-loader-upgrade` |
125+
| Fix | `fix/timezone-override` |
126+
| Docs | `docs/add-diagnostics-guide` |
127+
| Release | `release/v1.0.2` |
128+
129+
---
130+
131+
## 🔀 Pull Request Process
132+
133+
1. Fork the repository.
134+
2. Create a branch with a proper prefix.
135+
3. Add/update tests for all new logic.
136+
4. Update `/docs/` and `README.md` if needed.
137+
5. Update `CHANGELOG.md`.
138+
6. Ensure all CI checks pass.
139+
7. Submit your PR with:
140+
141+
* Clear summary
142+
* Explanation of what changed and why
143+
* Screenshots/logs if relevant
144+
145+
PRs without tests or documentation will be requested for revision.
146+
147+
---
148+
149+
## 🪪 License & Attribution
150+
151+
By contributing, you agree that your code will be licensed under the **MIT License** and attributed to **Maatify.dev**.
152+
153+
---
154+
155+
## 👤 Maintainer
156+
157+
**Mohamed Abdulalim ([@megyptm](https://github.com/megyptm))**
158+
Backend Lead & Technical Architect
159+
📧 [mohamed@maatify.dev](mailto:mohamed@maatify.dev)
160+
🌐 [https://www.maatify.dev](https://www.maatify.dev)
161+
162+
**© 2025 Maatify.dev — All Rights Reserved**
163+
Engineered with precision & consistency for the entire Maatify ecosystem.
164+
165+
📘 Full documentation & source code:
166+
🔗 [https://github.com/Maatify/bootstrap](https://github.com/Maatify/bootstrap)
167+
168+
---
169+
170+
> 🚀 **Consistency starts here.**
171+
> Your contributions help bootstrap the entire Maatify ecosystem.
172+
173+
---
174+
175+
<p align="center">
176+
<sub><span style="color:#777">Built with ❤️ by <a href="https://www.maatify.dev">Maatify.dev</a> — Unified Ecosystem for Modern PHP Libraries</span></sub>
177+
</p>
178+
179+
180+

0 commit comments

Comments
 (0)