# دليل استخدام Excel في Filament 5

## نظرة عامة
تم تثبيت حزمة `maatwebsite/excel` (الإصدار 3.1.68) كبديل لحزم Excel المحذوفة مع الترقية إلى Filament 5.

## الميزات المتاحة

### 1. تصدير البيانات (Export)

#### إضافة زر تصدير لجدول Resource

```php
use Filament\Tables\Actions\Action;
use Maatwebsite\Excel\Facades\Excel;
use App\Exports\UsersExport; // ستقوم بإنشاء هذا الملف

// في دالة table() داخل UserResource.php
public static function table(Table $table): Table
{
    return $table
        ->columns([...])
        ->headerActions([
            Action::make('export')
                ->label(__('Export to Excel'))
                ->icon('heroicon-o-arrow-down-tray')
                ->action(function () {
                    return Excel::download(new UsersExport, 'users.xlsx');
                })
                ->color('success'),
        ])
        ->filters([...])
        ->actions([...]);
}
```

#### إنشاء Export Class

قم بإنشاء ملف `app/Exports/UsersExport.php`:

```php
<?php

namespace App\Exports;

use App\Models\User;
use Maatwebsite\Excel\Concerns\FromCollection;
use Maatwebsite\Excel\Concerns\WithHeadings;
use Maatwebsite\Excel\Concerns\WithMapping;

class UsersExport implements FromCollection, WithHeadings, WithMapping
{
    public function collection()
    {
        return User::all();
    }

    public function headings(): array
    {
        return [
            'ID',
            'Name',
            'Email',
            'Created At',
        ];
    }

    public function map($user): array
    {
        return [
            $user->id,
            $user->name,
            $user->email,
            $user->created_at->format('Y-m-d H:i:s'),
        ];
    }
}
```

### 2. استيراد البيانات (Import)

#### إضافة زر استيراد

```php
use Filament\Forms\Components\FileUpload;
use Maatwebsite\Excel\Facades\Excel;
use App\Imports\UsersImport;

// في دالة table() داخل UserResource.php
->headerActions([
    Action::make('import')
        ->label(__('Import from Excel'))
        ->icon('heroicon-o-arrow-up-tray')
        ->form([
            FileUpload::make('file')
                ->label(__('Excel File'))
                ->acceptedFileTypes([
                    'application/vnd.ms-excel',
                    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
                ])
                ->required(),
        ])
        ->action(function (array $data) {
            $file = storage_path('app/public/' . $data['file']);
            Excel::import(new UsersImport, $file);
            
            \Filament\Notifications\Notification::make()
                ->success()
                ->title(__('Import completed'))
                ->body(__('Users imported successfully'))
                ->send();
        })
        ->color('warning'),
])
```

#### إنشاء Import Class

قم بإنشاء ملف `app/Imports/UsersImport.php`:

```php
<?php

namespace App\Imports;

use App\Models\User;
use Illuminate\Support\Facades\Hash;
use Maatwebsite\Excel\Concerns\ToModel;
use Maatwebsite\Excel\Concerns\WithHeadingRow;

class UsersImport implements ToModel, WithHeadingRow
{
    public function model(array $row)
    {
        return new User([
            'name'     => $row['name'],
            'email'    => $row['email'],
            'password' => Hash::make($row['password'] ?? 'password'),
        ]);
    }
}
```

### 3. تصدير مع فلاتر

```php
use App\Exports\FilteredUsersExport;

Action::make('export_filtered')
    ->label(__('Export Filtered'))
    ->icon('heroicon-o-funnel')
    ->action(function ($livewire) {
        $query = $livewire->getFilteredTableQuery();
        return Excel::download(
            new FilteredUsersExport($query),
            'filtered_users.xlsx'
        );
    })
```

```php
<?php

namespace App\Exports;

use Illuminate\Database\Eloquent\Builder;
use Maatwebsite\Excel\Concerns\FromQuery;
use Maatwebsite\Excel\Concerns\WithHeadings;

class FilteredUsersExport implements FromQuery, WithHeadings
{
    protected $query;

    public function __construct(Builder $query)
    {
        $this->query = $query;
    }

    public function query()
    {
        return $this->query;
    }

    public function headings(): array
    {
        return ['ID', 'Name', 'Email', 'Created At'];
    }
}
```

## الأوامر المساعدة

### نشر ملف الإعدادات
```bash
php artisan vendor:publish --provider="Maatwebsite\Excel\ExcelServiceProvider" --tag=config
```

### إنشاء Export حديد
```bash
php artisan make:export UsersExport --model=User
```

### إنشاء Import جديد
```bash
php artisan make:import UsersImport --model=User
```

## مثال كامل - User Resource

إليك مثال كامل لإضافة Export و Import إلى UserResource:

```php
<?php

namespace App\Filament\Resources\Users;

use Filament\Tables\Actions\Action;
use Filament\Forms\Components\FileUpload;
use Maatwebsite\Excel\Facades\Excel;
use App\Exports\UsersExport;
use App\Imports\UsersImport;
use Filament\Notifications\Notification;

class UserResource extends Resource
{
    // ... existing code ...

    public static function table(Table $table): Table
    {
        return $table
            ->columns([
                // ... existing columns ...
            ])
            ->headerActions([
                // زر التصدير
                Action::make('export')
                    ->label(__('Export'))
                    ->icon('heroicon-o-arrow-down-tray')
                    ->action(function () {
                        return Excel::download(new UsersExport, 'users-' . now()->format('Y-m-d') . '.xlsx');
                    })
                    ->color('success'),
                
                // زر الاستيراد
                Action::make('import')
                    ->label(__('Import'))
                    ->icon('heroicon-o-arrow-up-tray')
                    ->form([
                        FileUpload::make('file')
                            ->label(__('Excel File'))
                            ->acceptedFileTypes([
                                'application/vnd.ms-excel',
                                'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
                            ])
                            ->required()
                            ->maxSize(5120), // 5MB
                    ])
                    ->action(function (array $data) {
                        try {
                            $filePath = storage_path('app/public/' . $data['file']);
                            Excel::import(new UsersImport, $filePath);
                            
                            Notification::make()
                                ->success()
                                ->title(__('Import successful'))
                                ->body(__('Users have been imported successfully'))
                                ->send();
                                
                        } catch (\Exception $e) {
                            Notification::make()
                                ->danger()
                                ->title(__('Import failed'))
                                ->body($e->getMessage())
                                ->send();
                        }
                    })
                    ->color('warning'),
            ])
            ->filters([
                // ... existing filters ...
            ])
            ->actions([
                // ... existing actions ...
            ]);
    }
}
```

## ملاحظات مهمة

1. **الأداء**: للجداول الكبيرة، استخدم `FromQuery` بدلاً من `FromCollection` لتحسين الأداء
2. **الذاكرة**: استخدم `WithChunking` للبيانات الضخمة
3. **التنسيق**: يمكنك استخدام `WithStyles` و `WithColumnFormatting` لتنسيق متقدم
4. **الترجمة**: استخدم `__()` helper لترجمة العناوين والرسائل

## الموارد المفيدة

- [Laravel Excel Documentation](https://docs.laravel-excel.com/)
- [Filament Tables Documentation](https://filamentphp.com/docs/5.x/tables/getting-started)
- [Filament Actions Documentation](https://filamentphp.com/docs/5.x/actions/overview)

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

لأي مشاكل تتعلق بـ Excel، تحقق من:
1. صلاحيات المجلد `storage/app/public`
2. حجم الملف المحدد في `php.ini` (`upload_max_filesize`, `post_max_size`)
3. timeout للسكريبت في حالة الملفات الكبيرة