# دليل استخدام PHPStan لفحص جودة الكود

## 🔍 نظرة عامة

تم إعداد **PHPStan** مع **Larastan** لفحص جودة الكود وال type safety في مشروع Laravel.

---

## 📦 التثبيت

### 1. تثبيت PHPStan و Larastan

```bash
composer require --dev larastan/larastan
```

### 2. التحقق من التثبيت

```bash
./vendor/bin/phpstan --version
```

---

## ⚙️ الإعداد

تم إنشاء ملف `phpstan.neon` في جذر المشروع مع الإعدادات التالية:

```yaml
includes:
    - vendor/larastan/larastan/extension.neon
    - vendor/nesbot/carbon/extension.neon

parameters:
    paths:
        - app/
    
    level: 5  # من 0 إلى 9
    
    checkModelProperties: true
    checkPhpDocMissingParamType: true
    checkPhpDocMethodSignatures: true
```

---

## 🚀 الاستخدام

### 1. تشغيل الفحص الكامل

```bash
./vendor/bin/phpstan analyse
```

### 2. فحص مجلد محدد

```bash
./vendor/bin/phpstan analyse app/Services
```

### 3. فحص مع level محدد

```bash
./vendor/bin/phpstan analyse --level=6
```

### 4. إنشاء baseline (تجاهل الأخطاء الحالية)

```bash
./vendor/bin/phpstan analyse --generate-baseline
```

---

## 📊 مستويات الفحص (Levels)

| Level | الوصف |
|-------|--------|
| 0 | فحص أساسي جداً |
| 1-4 | فحوصات متدرجة |
| **5** | **مستوى موصى به** (الحالي) |
| 6-8 | فحوصات صارمة |
| 9 | أقصى صرامة |

---

## 🎯 الأخطاء الشائعة وحلولها

### 1. Missing Type Hints

**الخطأ:**
```
Method App\Services\MyService::process() has no return type specified
```

**الحل:**
```php
// ❌ قبل
public function process($data)
{
    return $result;
}

// ✅ بعد
public function process(array $data): bool
{
    return true;
}
```

### 2. Undefined Properties

**الخطأ:**
```
Access to an undefined property App\Models\User::$custom_field
```

**الحل:**
```php
// في Model
/**
 * @property string $custom_field
 */
class User extends Model
{
    //
}
```

### 3. Possibly Null

**الخطأ:**
```
Cannot call method on possibly null value
```

**الحل:**
```php
// ❌ قبل
$user = User::find($id);
$name = $user->name;

// ✅ بعد
$user = User::find($id);
if ($user) {
    $name = $user->name;
}

// أو
$user = User::findOrFail($id);
$name = $user->name;
```

### 4. Wrong Parameter Type

**الخطأ:**
```
Parameter #1 expects int, string given
```

**الحل:**
```php
// ❌ قبل
function process($id)
{
    // $id might be string
}

// ✅ بعد
function process(int $id): void
{
    // $id is definitely int
}
```

---

## 🔧 إضافة PHPStan إلى CI/CD

### GitHub Actions

```yaml
name: PHPStan

on: [push, pull_request]

jobs:
  phpstan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
      
      - name: Install Dependencies
        run: composer install
      
      - name: Run PHPStan
        run: ./vendor/bin/phpstan analyse
```

---

## 📝 أوامر مفيدة

### فحص مع تفاصيل أكثر

```bash
./vendor/bin/phpstan analyse -v
```

### فحص مع Memory أكبر

```bash
./vendor/bin/phpstan analyse --memory-limit=2G
```

### عرض التقدم

```bash
./vendor/bin/phpstan analyse --progress
```

### تنسيق الخرج

```bash
# JSON format
./vendor/bin/phpstan analyse --error-format=json

# Table format
./vendor/bin/phpstan analyse --error-format=table
```

---

## 🎓 أفضل الممارسات

### 1. فحص دوري

```bash
# إضافة إلى composer scripts
{
    "scripts": {
        "phpstan": "./vendor/bin/phpstan analyse"
    }
}

# تشغيل
composer phpstan
```

### 2. Pre-commit Hook

```bash
# في .git/hooks/pre-commit
#!/bin/bash
./vendor/bin/phpstan analyse --no-progress
```

### 3. زيادة Level تدريجياً

```bash
# ابدأ بـ level 5
./vendor/bin/phpstan analyse --level=5

# بعد إصلاح الأخطاء، ارفع إلى 6
./vendor/bin/phpstan analyse --level=6
```

---

## 📊 تقرير النتائج

بعد الفحص، ستحصل على تقرير مثل:

```
 ------ --------------------------------------------------------- 
  Line   app/Services/MyService.php                              
 ------ --------------------------------------------------------- 
  15     Method process() has no return type specified.         
  23     Cannot call method on possibly null value.             
 ------ --------------------------------------------------------- 

 [ERROR] Found 2 errors
```

---

## 🔍 Ignore Errors (استخدام بحذر)

### في الكود مباشرة

```php
/** @phpstan-ignore-next-line */
$value = $object->dynamicProperty;
```

### في ملف الإعداد

```yaml
parameters:
    ignoreErrors:
        - '#Access to an undefined property#'
```

---

## 🎯 الهدف

الوصول إلى **0 errors** على Level 5 أو أعلى:

```bash
 [OK] No errors

✨ القاعدة الذهبية: كل كود جديد يجب أن يمر PHPStan بدون أخطاء
```

---

## 📚 موارد إضافية

- [PHPStan Documentation](https://phpstan.org/user-guide/getting-started)
- [Larastan Documentation](https://github.com/larastan/larastan)
- [PHPStan Rules](https://phpstan.org/user-guide/rules)

---

## ✅ Checklist

قبل كل Commit:

- [ ] تشغيل `./vendor/bin/phpstan analyse`
- [ ] إصلاح جميع الأخطاء
- [ ] التأكد من وجود Type Hints
- [ ] مراجعة DocBlocks
- [ ] التأكد من null safety

---

**🎉 كود نظيف = كود بدون أخطاء PHPStan!**