vernova/INSTALL-WINDOWS-XAMPP.md

# 🏗️ Vernova - راهنمای نصب روی ویندوز + XAMPP + VSCode

## پیش‌نیازها

### ۱. نصب XAMPP
دانلود XAMPP با PHP 8.2+ از:
👉 https://www.apachefriends.org/download.html

نسخه‌ای که PHP 8.2 یا 8.3 داره رو انتخاب کنید.

بعد از نصب، مطمئن بشید XAMPP در مسیر زیر هست:
```
C:\xampp
```

### ۲. نصب Composer
دانلود از:
👉 https://getcomposer.org/download/

⚠️ حتماً موقع نصب، مسیر PHP رو بهش بدید:
```
C:\xampp\php\php.exe
```

### ۳. نصب Node.js
دانلود LTS از:
👉 https://nodejs.org/

### ۴. نصب Git (اختیاری ولی پیشنهادی)
👉 https://git-scm.com/download/win

### ۵. نصب VSCode
👉 https://code.visualstudio.com/

---

## مرحله ۱: بررسی پیش‌نیازها

CMD (Command Prompt) رو باز کنید و بزنید:

```cmd
php -v
```
باید PHP 8.2+ نشون بده. اگه نشناخت:
```
سیستم > متغیرهای محیطی > Path > اضافه کنید:
C:\xampp\php
```

```cmd
composer --version
node -v
npm -v
```

همه باید جواب بده. ✅

---

## مرحله ۲: فعال‌کردن اکستنشن‌های PHP

فایل زیر رو با Notepad یا VSCode باز کنید:
```
C:\xampp\php\php.ini
```

این خطوط رو پیدا کنید و سمی‌کالن (;) اولشون رو حذف کنید:

```ini
; قبل:
;extension=intl
;extension=pdo_mysql
;extension=mbstring
;extension=fileinfo
;extension=openssl
;extension=curl

; بعد:
extension=intl
extension=pdo_mysql
extension=mbstring
extension=fileinfo
extension=openssl
extension=curl
```

⚠️ **اکستنشن `intl` خیلی مهمه!** برای تبدیل اعداد و ارز لازمه.

بعد از تغییر، Apache رو از پنل XAMPP ری‌استارت کنید.

---

## مرحله ۳: ساخت دیتابیس

1. پنل XAMPP → **MySQL** رو Start کنید
2. مرورگر رو باز کنید: `http://localhost/phpmyadmin`
3. روی **New** کلیک کنید
4. نام دیتابیس: `projectra`
5. Collation: `utf8mb4_unicode_ci`
6. **Create** رو بزنید

---

## مرحله ۴: ساخت پروژه Laravel

CMD رو باز کنید:

```cmd
cd C:\xampp\htdocs

composer create-project laravel/laravel projectra
```

این مرحله ممکنه ۳-۵ دقیقه طول بکشه. ⏳

---

## مرحله ۵: کپی فایل‌های Projectra

فایل ZIP (`projectra-laravel.zip`) رو Extract کنید.

### فایل‌هایی که باید کپی بشن:

```
از ZIP → به C:\xampp\htdocs\projectra\
```

| پوشه/فایل | عملیات |
|-----------|---------|
| `app/` | جایگزین (overwrite) |
| `config/projectra.php` | کپی |
| `config/projectra_app_additions.php` | کپی |
| `database/migrations/` | جایگزین |
| `database/seeders/` | جایگزین |
| `resources/views/` | جایگزین |
| `resources/lang/` | جایگزین |
| `resources/css/` | جایگزین |
| `resources/js/` | جایگزین |
| `routes/web.php` | جایگزین |
| `routes/api.php` | جایگزین |
| `composer.json` | جایگزین |
| `package.json` | جایگزین |
| `vite.config.js` | جایگزین |
| `tailwind.config.js` | جایگزین |
| `postcss.config.js` | جایگزین |
| `.env.example` | جایگزین |

---

## مرحله ۶: نصب وابستگی‌ها

```cmd
cd C:\xampp\htdocs\projectra

:: نصب پکیج‌های PHP
composer install

:: نصب پکیج‌های Frontend
npm install
```

اگه `composer install` ارور داد پکیج‌ها رو پیدا نمی‌کنه:
```cmd
composer update
```

---

## مرحله ۷: تنظیم فایل .env

```cmd
copy .env.example .env
php artisan key:generate
```

فایل `.env` رو با VSCode باز کنید و این بخش رو ویرایش کنید:

```env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=projectra
DB_USERNAME=root
DB_PASSWORD=
```

> 💡 در XAMPP، کاربر پیش‌فرض MySQL `root` هست و رمز عبور **خالیه** (بدون رمز).

---

## مرحله ۸: تنظیم config/app.php

فایل `config/app.php` رو باز کنید:

### اضافه کردن Providers:
```php
'providers' => [
    // ... provider های موجود ...
    
    // Vernova
    Spatie\Permission\PermissionServiceProvider::class,
    Morilog\Jalali\JalaliServiceProvider::class,
    Maatwebsite\Excel\ExcelServiceProvider::class,
    Barryvdh\DomPDF\ServiceProvider::class,
    App\Providers\BladeServiceProvider::class,
],
```

### اضافه کردن Aliases:
```php
'aliases' => [
    // ... alias های موجود ...
    
    // Vernova
    'Jalali' => Morilog\Jalali\JalaliFacade::class,
    'Excel' => Maatwebsite\Excel\Facades\Excel::class,
    'PDF' => Barryvdh\DomPDF\Facade\Pdf::class,
],
```

### تغییر locale پیش‌فرض:
```php
'locale' => env('APP_LOCALE', 'fa'),
'fallback_locale' => 'en',
```

---

## مرحله ۹: تنظیم autoload

فایل `composer.json` رو باز کنید. در بخش `autoload` اضافه کنید:

```json
"autoload": {
    "psr-4": {
        "App\\": "app/",
        "Database\\Factories\\": "database/factories/",
        "Database\\Seeders\\": "database/seeders/"
    },
    "files": [
        "app/Helpers/helpers.php"
    ]
},
```

سپس:
```cmd
composer dump-autoload
```

---

## مرحله ۱۰: اجرای Migration و Seeder

```cmd
php artisan migrate
php artisan db:seed
```

اگه ارور `Specified key was too long` گرفتید، در `AppServiceProvider.php` در متد `boot()` اضافه کنید:
```php
Schema::defaultStringLength(191);
```

---

## مرحله ۱۱: ساخت Asset‌ها

```cmd
npm run build
```

برای توسعه (با auto-refresh):
```cmd
npm run dev
```

---

## مرحله ۱۲: اجرای پروژه 🚀

### روش ۱: با artisan (پیشنهادی)
```cmd
php artisan serve
```
مرورگر: `http://localhost:8000`

### روش ۲: با Apache (XAMPP)
1. Apache رو در XAMPP استارت کنید
2. مرورگر: `http://localhost/projectra/public`

> 💡 برای روش ۲، بهتره Virtual Host تنظیم کنید (مرحله بعدی).

---

## 🔧 تنظیم Virtual Host (اختیاری ولی حرفه‌ای)

فایل زیر رو باز کنید:
```
C:\xampp\apache\conf\extra\httpd-vhosts.conf
```

اضافه کنید:
```apache
<VirtualHost *:80>
    DocumentRoot "C:/xampp/htdocs/projectra/public"
    ServerName projectra.test
    <Directory "C:/xampp/htdocs/projectra/public">
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>
```

فایل hosts ویندوز رو باز کنید (با Notepad به صورت Run as Administrator):
```
C:\Windows\System32\drivers\etc\hosts
```

اضافه کنید:
```
127.0.0.1  projectra.test
```

Apache رو ری‌استارت کنید و بعد:
👉 `http://projectra.test`

---

## 👤 حساب‌های پیش‌فرض

| نقش | ایمیل | رمز عبور |
|------|-------|----------|
| Super Admin | admin@projectra.ir | password |
| Admin (سازندگی سپید) | admin@sepideh.ir | password |
| Project Manager | manager@sepideh.ir | password |
| Admin (Global) | admin@global.com | password |

---

## 🛠️ تنظیمات VSCode

### اکستنشن‌های پیشنهادی:

| اکستنشن | کاربرد |
|---------|---------|
| **Laravel Blade** | رنگ‌بندی Blade templates |
| **PHP Intelephense** | autocomplete و تحلیل PHP |
| **Tailwind CSS IntelliSense** | autocomplete کلاس‌های Tailwind |
| **Alpine.js IntelliSense** | autocomplete Alpine.js |
| **Laravel Artisan** | اجرای دستورات Artisan از VSCode |
| **PHP Debug** | دیباگ PHP با Xdebug |
| **Prettier** | فرمت‌بندی کد |

### تنظیم Xdebug (اختیاری):

فایل `C:\xampp\php\php.ini` اضافه کنید:
```ini
[xdebug]
zend_extension=xdebug
xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.client_port=9003
```

در VSCode فایل `.vscode/launch.json`:
```json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003
        }
    ]
}
```

---

## ❓ مشکلات رایج ویندوز

### ۱. ارور "php not recognized"
```
Path اضافه کنید: C:\xampp\php
سیستم > متغیرهای محیطی > Path > Edit > New
```

### ۲. ارور "composer not recognized"
```
Path اضافه کنید: C:\ProgramData\ComposerSetup\bin
یا Composer رو دوباره نصب کنید
```

### ۳. ارور "SSL Certificate" در composer
```cmd
composer config -g -- disable-tls false
composer config -g -- secure-http false
```

### ۴. ارور "Allowed memory size exhausted"
```cmd
php -d memory_limit=-1 C:\path\to\composer.phar install
```

### ۵. ارور "npm ERR!" 
```cmd
npm cache clean --force
npm install
```

### ۶. ارور مخفف نشدن صفحه (blank page)
```cmd
php artisan config:clear
php artisan cache:clear
php artisan view:clear
php artisan route:clear
```

### ۷. ارور permission در storage
```cmd
icacls storage /grant Everyone:F /T
icacls bootstrap\cache /grant Everyone:F /T
```

---

## 📌 خلاصه سریع (Quick Start)

```cmd
:: 1. ساخت پروژه
cd C:\xampp\htdocs
composer create-project laravel/laravel projectra

:: 2. کپی فایل‌ها از ZIP → projectra/

:: 3. نصب وابستگی‌ها
cd projectra
composer install
npm install

:: 4. تنظیم env
copy .env.example .env
php artisan key:generate

:: 5. تنظیم config/app.php (Providers + Aliases)
:: 6. تنظیم composer.json autoload (helpers.php)
composer dump-autoload

:: 7. ساخت دیتابیس در phpMyAdmin: projectra

:: 8. Migration + Seed
php artisan migrate
php artisan db:seed

:: 9. Build
npm run build

:: 10. اجرا! 🚀
php artisan serve
```

مرورگر → `http://localhost:8000` ✅