README

⚙️ Maatify Bootstrap

Unified Environment Initialization & Diagnostics Layer

Project: maatify:bootstrap
Version: 1.0.3
License: MIT
Author: Mohamed Abdulalim (megyptm)
© 2025 Maatify.dev

🔗 بالعربي 🇸🇦

🧭 Overview

maatify/bootstrap is the core foundation for the entire Maatify ecosystem —
providing standardized environment initialization, diagnostics, timezone setup, and safe startup checks
for every Maatify PHP library and application.

It ensures consistent, predictable, and secure runtime behavior across:

• Local development
• CI/CD pipelines
• Staging and production environments

⚙️ Installation

composer require maatify/bootstrap

📦 Dependencies

This library relies on:

maatify/bootstrap builds upon these open-source libraries to provide a unified and secure initialization layer across the entire Maatify ecosystem.

🧩 Internal Dependency Hierarchy

maatify/bootstrap follows a hierarchical dependency chain within the Maatify ecosystem, ensuring that all foundational layers are automatically included — without redundancy or version conflicts.

🧩 Note: Installing maatify/bootstrap automatically includes both maatify/common and maatify/psr-logger. You do not need to manually require them — they are resolved internally via Composer dependencies.

📦 Dependency Chain Diagram

graph TD
    A[maatify/psr-logger]:::core --> B[maatify/common]:::core
    B --> C[maatify/bootstrap]:::main
    C --> D["Other Maatify Libraries (rate-limiter, redis-cache, security-guard...)"]:::ext

    classDef core fill:#0066cc,color:#ffffff,stroke:#003366,stroke-width:2px;
    classDef main fill:#009933,color:#ffffff,stroke:#004d1a,stroke-width:2px;
    classDef ext fill:#ffcc00,color:#000000,stroke:#996600,stroke-width:2px;

This diagram shows how each Maatify package inherits initialization and logging automatically through the unified bootstrap layer — ensuring consistent configuration and predictable startup behavior.

🧩 Version Compatibility Matrix

⚙️ Notes:

• Official testing and CI pipelines target PHP 8.3 and 8.4.
• Backward compatibility with PHP 8.2 is limited and not guaranteed.
• All Maatify core packages maintain synchronized versioning and consistent dependency alignment.

🧩 Features

• 🔐 Unified .env file loader with priority-based detection
• 🌍 Timezone configuration (APP_TIMEZONE → default Africa/Cairo)
• 🧠 Smart environment caching via EnvHelper
• 🧱 Cross-library bootstrap via Bootstrap::init()
• 🚦 Safe Mode activation for production protection
• 🧪 Full PHPUnit test coverage with CI integration
• 🐳 Docker & GitHub Actions ready

🧠 Environment Loading Priority

maatify/bootstrap loads only one .env file per execution — based on strict precedence:

Once a file is found, loading stops immediately — ensuring lower-priority files cannot override higher ones. Uses Dotenv::createImmutable() (from vlucas/phpdotenv) for safety, preventing accidental overwrites.

🧠 Usage Example

use Maatify\Bootstrap\Core\Bootstrap;

Bootstrap::init();

// Access loaded variables
$env = $_ENV['APP_ENV'] ?? 'production';
echo "Running in environment: $env";

or for diagnostic mode:

use Maatify\Bootstrap\Core\BootstrapDiagnostics;
use Maatify\PsrLogger\LoggerFactory;

$logger = LoggerFactory::create('bootstrap');
$diag = new BootstrapDiagnostics($logger);

print_r($diag->run());

🧰 Docker Integration

For consistent environment parity between local and CI:

docker compose up --build
docker compose exec bootstrap composer run-script test

🧪 Testing

Run tests locally:

composer run-script test

CI is automatically triggered via GitHub Actions:

.github/workflows/tests.yml

📄 Documentation

Full technical documentation covering all phases (1 → 7): 👉 docs/README.full.md

Maatify Bootstrap — “Initialize once, stabilize everywhere.”

📚 Built Upon

maatify/bootstrap is proudly built upon and extends several foundational open-source projects:

Special thanks to the maintainers of these open-source libraries for providing the stable foundations that make this project possible. ❤️

🪪 License

MIT license © Maatify.dev
You’re free to use, modify, and distribute this library with attribution.

🧱 Authors & Credits

Developed by: Maatify.dev
Maintainer: Mohamed Abdulalim
Project: maatify:bootstrap