ZFast Framework v1.0.0

إطار عمل PHP خفيف للغاية مُحسّن للاستضافات المشتركة (InfinityFree)
Compile First · Fast by Default · Lightweight by Design

---

📋 نظرة عامة

ZFast هو إطار عمل PHP حديث صُمم من الصفر ليعمل بكفاءة قصوى على الاستضافات المشتركة ذات الموارد المحدودة مثل InfinityFree. يتبع الإطار فلسفة Compile First Development حيث تتم عمليات التحليل والتجميع أثناء أمر البناء، وليس أثناء كل طلب HTTP.

المبادئ الأساسية

• Fast by default, lightweight by design — سريع افتراضياً، خفيف بالتصميم
• Compile First — تجميع كل شيء أثناء البناء
• Lazy Loading — لا تهيئة أي خدمة إلا عند الحاجة
• Native PHP — استخدام PHP الأصلي كلغة قوالب
• Minimal File I/O — أقل قدر ممكن من قراءة/كتابة الملفات
• No Daemons — لا يحتاج عمليات خلفية أو Redis أو Supervisor

---

✨ الميزات الكاملة

🏗️ النواة (Core)

الميزة	الوصف
Application	نواة صغيرة جداً (<5ms bootstrap)
Container	DI Container مع Lazy Loading كامل
ClassLoader	PSR-4 + ClassMap مُجمّع (O(1) lookup)

🛣️ Routing

الميزة	الوصف
Router	مطابقة سريعة بـ regex مُجمّع
Route Compiler	تجميع المسارات لملف PHP واحد
Route Groups	تجميع المسارات بـ prefix وmiddleware
Named Routes	توليد URLs بأسماء المسارات
Parameters	دعم {id}, {id:[0-9]+}, {slug?}

🌐 HTTP Layer

الميزة	الوصف
Request	معالجة GET/POST/JSON/Files/Cookies
Response	JSON/HTML/Redirect/Text responses
Middleware	نظام وسطاء قابل للتخصيص
Cookie	كوكيز آمنة مع signed cookies

🗃️ Database

الميزة	الوصف
Connection	Lazy PDO مع إعدادات InfinityFree
Query Builder	Fluent builder مع Prepared Statements
Model	Base Model اختياري (ActiveRecord خفيف)
Migration	نظام ترحيلات مع rollback
Seeder	ملء قاعدة البيانات ببيانات أولية

📄 Templates (Native PHP)

الميزة	الوصف
Template engine	PHP الأصلي - الأسرع
Layouts	وراثة القوالب
Sections	blocks قابلة للإعادة
Partials	تضمين قوالب جزئية
Helpers	e(), csrf_field(), asset(), url()

💾 Cache

الميزة	الوصف
FileCache	كاش ملفات خفيف بدون Redis
Atomic writes	كتابة آمنة مع LOCK_EX
TTL	دعم انتهاء الصلاحية
remember()	جلب من الكاش أو تنفيذ

🔒 Security

الميزة	الوصف
CSRF	حماية كاملة مع token
Sanitizer	تنظيف strings, emails, slugs, HTML
Security Headers	CSP, HSTS, X-Frame-Options, إلخ
Hash	bcrypt + HMAC + UUID + tokens

✅ Validation

الميزة	الوصف
Fluent API	Validator::make($data, $rules)
20+ rules	required, email, url, min, max, regex, إلخ
Arabic messages	رسائل خطأ بالعربية افتراضياً
Custom messages	تخصيص كامل

📦 Upload

الميزة	الوصف
MIME detection	فحص MIME الحقيقي (لا يثق بـ $_FILES)
Extension validation	منع امتدادات خطيرة (php, exe, إلخ)
Multiple files	دعم رفع عدة ملفات
Path traversal protection	حماية من تجاوز المجلدات

🛠️ Console CLI

php zfast build              # تجميع للإنتاج
php zfast migrate            # تنفيذ الترحيلات
php zfast migrate:status     # حالة الترحيلات
php zfast make:migration X   # إنشاء ترحيل
php zfast serve              # خادم التطوير
php zfast routes             # عرض المسارات
php zfast info               # معلومات النظام

📊 Support Utilities

• Str - slug, camel, snake, kebab, uuid, random
• Arr - dot notation, pluck, chunk, depth
• Paginator - pagination مع HTML جاهز
• Logger - سجلات يومية مع rotation
• DotEnv - قراءة .env بدون تبعيات
• Config - إعدادات مع dot notation

---

📁 بنية المشروع

php-framework/
├── app/                          # كود التطبيق
│   ├── Middleware/               # الوسطاء
│   ├── Modules/                  # الوحدات (Modular)
│   │   ├── Home/                 # الوحدة الرئيسية
│   │   │   ├── Controllers/      # HomeController, PostController
│   │   │   └── Views/            # قوالب الوحدة
│   │   ├── Admin/                # وحدة لوحة التحكم
│   │   │   ├── Controllers/      # DashboardController
│   │   │   └── Views/            # dashboard, users, posts, system
│   │   └── Api/                  # وحدة REST API
│   │       └── Controllers/      # ApiController
│   ├── Modules/BaseController.php
│   └── bootstrap.php             # ملف الإقلاع
├── config/                       # الإعدادات
│   ├── app.php
│   ├── database.php
│   └── routes.php                # تعريف المسارات
├── database/                     # قاعدة البيانات
│   ├── migrations/               # ترحيلات (3 ملفات)
│   ├── seeders/                  # بيانات أولية (Users, Posts)
│   └── schema.sql                # SQL كامل بديل
├── public/                       # DocumentRoot
│   ├── index.php                 # نقطة الدخول
│   └── .htaccess                 # Apache config
├── storage/                      # التخزين
│   ├── cache/                    # الكاش المُجمّع
│   ├── logs/                     # السجلات
│   └── framework/
├── system/                       # نواة الإطار
│   ├── Core/                     # Application, Container, ClassLoader
│   ├── Http/                     # Request, Response, Middleware, Cookie
│   ├── Routing/                  # Router, Route, RouteCompiler
│   ├── Database/                 # Connection, QueryBuilder, Model, Migration, Seeder
│   ├── Cache/                    # FileCache
│   ├── View/                     # Template
│   ├── Security/                 # Csrf, Sanitizer, SecurityHeaders, Hash
│   ├── Validation/               # Validator
│   ├── Upload/                   # FileUploader
│   ├── Console/                  # Console CLI
│   └── Support/                  # Config, DotEnv, Logger, Paginator, Str, Arr
├── build.php                     # أمر البناء
├── zfast                         # أداة CLI
├── composer.json
├── .env.example
├── .htaccess
├── README.md
└── QUICKSTART.md

---

🚀 البدء السريع

1️⃣ التطوير المحلي

cd php-framework
cp .env.example .env
# عدّل قيم DB_* في .env

# (اختياري) رفع DB schema
mysql -u user -p database < database/schema.sql

# أو استخدام migrations
php zfast migrate
php zfast seed  # (يتطلب إضافة seed command في Console)

# تشغيل خادم التطوير
php zfast serve
# أو
php -S localhost:8000 -t public/

افتح: http://localhost:8000

2️⃣ بناء الإنتاج

php zfast build

سينشئ:

• storage/cache/routes.php — المسارات المُجمّعة
• storage/cache/config.php — الإعدادات المُجمّعة
• storage/cache/classmap.php — خريطة الفئات

3️⃣ النشر على InfinityFree

1. ارفع كل الملفات إلى htdocs/ عبر FTP
2. تأكد أن .htaccess و public/.htaccess مرفوعين
3. أنشئ قاعدة بيانات MySQL من cPanel
4. عدّل .env ببيانات قاعدة بياناتك
5. استورد database/schema.sql عبر phpMyAdmin
6. شغّل php zfast build محلياً قبل الرفع

---

📖 أمثلة الاستخدام

تعريف المسارات (Routes)

// config/routes.php

use ZFast\System\Routing\Router;
use App\Modules\Home\Controllers\HomeController;
use App\Modules\Api\Controllers\ApiController;

/** @var Router $router */

// مسارات بسيطة
$router->get('/', [HomeController::class, 'index'])->name('home');
$router->get('/user/{id:[0-9]+}', [HomeController::class, 'user']);

// Route Group
$router->group(['prefix' => 'api/v1'], function (Router $router) {
    $router->post('/auth/login', [ApiController::class, 'login']);
    $router->get('/posts', [ApiController::class, 'listPosts']);
    $router->get('/posts/{id:[0-9]+}', [ApiController::class, 'showPost']);
    $router->post('/posts', [ApiController::class, 'createPost']);
    $router->put('/posts/{id:[0-9]+}', [ApiController::class, 'updatePost']);
    $router->delete('/posts/{id:[0-9]+}', [ApiController::class, 'deletePost']);
});

// مع middleware
$router->group([
    'prefix' => 'admin',
    'middleware' => [\App\Middleware\AuthMiddleware::class],
], function (Router $router) {
    $router->get('/dashboard', [AdminController::class, 'dashboard']);
});

Query Builder

use function ZFast\db;

// SELECT
$users = db('users')->where('active', 1)->orderBy('name')->limit(10)->get();
$user  = db('users')->where('id', 1)->first();

// JOIN + Pagination
$posts = QueryBuilder::table('posts')
    ->select('posts.*', 'users.name as author')
    ->join('users', 'users.id', '=', 'posts.user_id')
    ->where('posts.published', 1)
    ->forPage($page, 15)
    ->get();

// INSERT
$id = db('users')->insert(['name' => 'Ali', 'email' => 'ali@x.com']);

// UPDATE
db('users')->where('id', $id)->update(['name' => 'Ali M.']);

// DELETE
db('users')->where('id', $id)->delete();

// Aggregate
$count = db('users')->where('active', 1)->count();
$exists = db('users')->where('email', 'x@y.com')->exists();

// Upsert
db('users')->upsert(
    ['email' => 'a@b.com', 'name' => 'A', 'updated_at' => date('Y-m-d H:i:s')],
    ['name', 'updated_at']
);

Validation

use ZFast\System\Validation\Validator;

$validator = Validator::make($_POST, [
    'name'     => 'required|string|min:3|max:100',
    'email'    => 'required|email',
    'password' => 'required|min:8|confirmed',
    'age'      => 'required|int|between:18:120',
    'role'     => 'required|in:admin,user,editor',
]);

if (!$validator->validate()) {
    $errors = $validator->firstErrors();
    // ['name' => 'حقل name مطلوب', ...]
}

Templates (Native PHP)

<?php /** @var array $data */ ?>
<?php $this->extends('layouts/app') ?>

<?php $this->start('content') ?>
    <h1><?= $this->e($data['title']) ?></h1>
    <p>مرحباً <?= $this->e($data['user']['name']) ?></p>

    <?php foreach ($data['posts'] as $post): ?>
        <div class="post">
            <h3><?= $this->e($post['title']) ?></h3>
            <p><?= $this->e(Str::limit($post['content'], 200)) ?></p>
        </div>
    <?php endforeach; ?>

    <?php $this->partial('partials/pagination', ['paginator' => $data['paginator']]) ?>
<?php $this->end() ?>

Cache

// remember - الأكثر استخداماً
$posts = cache()->remember('posts.featured', function () {
    return db('posts')->where('featured', 1)->limit(5)->get();
}, 600); // 10 دقائق

// get/put
$user = cache()->get('user.1');
cache()->put('user.1', $userData, 3600);

// increment للعدادات
cache()->increment('page.views', 1, 86400);

// forget
cache()->forget('user.1');

// cleanup
cache()->gc();

Security

use ZFast\System\Security\Csrf;
use ZFast\System\Security\Sanitizer;
use ZFast\System\Security\Hash;

// CSRF
$token = Csrf::token();
$valid = Csrf::verify($_POST['_token']);

// Sanitizer
$email = Sanitizer::email($_POST['email']);
$slug  = Sanitizer::slug($_POST['title']);
$clean = Sanitizer::array($_POST, [
    'name'  => 'string:100',
    'age'   => 'int:1:120',
    'email' => 'email',
]);

// Hash
$hashed = Hash::make('password');
$valid  = Hash::verify('password', $hashed);
$token  = Hash::randomToken(32);
$uuid   = Hash::uuid();

Logger

logger()->info('User logged in', ['user_id' => 42]);
logger()->error('Payment failed', ['order_id' => 1001, 'amount' => 99.50]);
logger()->warning('Rate limit approaching', ['ip' => $request->ip()]);

File Upload

use ZFast\System\Upload\FileUploader;

$uploader = new FileUploader(__DIR__ . '/uploads', 5_242_880);

try {
    $result = $uploader->upload($_FILES['document']);
    echo "Uploaded: " . $result['name'];
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

---

⚡ مقارنة الأداء (تقديرية)

المقياس	Laravel	ZFast
زمن الإقلاع	80-120ms	2-5ms
استهلاك الذاكرة	25-40MB	2-4MB
عدد الملفات المُحمّلة	200+	5-10
Reflection في الطلب	نعم	لا
تبعيات Composer	50+	0

---

🛡️ توافق InfinityFree

المورد	حد InfinityFree	تحسينات ZFast
CPU	محدود	زمن تنفيذ < 50ms
RAM	256MB	2-4MB لكل طلب
MySQL	5 connections	Lazy + non-persistent
Disk	5GB	ClassMap يقلل I/O 95%
Bandwidth	Unlimited	Gzip + Browser Cache
Background	No daemons	لا يحتاج أي daemon

---

🆘 استكشاف الأخطاء

المشكلة	الحل
"No input file specified"	تأكد من RewriteRule ^ index.php [L]
500 Internal Server Error	راجع storage/logs/errors.log
DB connection failed	DB_HOST=localhost + تحقق من الاسم
CPU limit exceeded	شغّل php zfast build قبل الرفع
404 على المسارات	تأكد أن catch-all هو آخر route
Session لا تعمل	تأكد من session_start() في middleware

---

📜 الترخيص

MIT License — حر للاستخدام التجاري والشخصي.

---

ZFast Framework v1.0.0 — Build Fast. Run Light. Scale Smart.