base-api-scramble-mcp 1.0.0

package/docs/EXCEL-EXPORT-SERVICE.md

@@ -0,0 +1,349 @@
+# Excel Export Service Documentation
+
+Service ini menyediakan fitur export Excel yang lengkap dengan dukungan multiple sheets, multiple tables, custom styling, chunking untuk data besar, dan informasi export yang detail.
+
+## Features
+
+- ✅ **Multiple Sheets**: Export ke beberapa sheet dalam satu file
+- ✅ **Multiple Tables**: Export beberapa tabel dalam satu sheet
+- ✅ **Custom Styling**: Default styling dan custom styling
+- ✅ **Chunking**: Otomatis memproses data dalam chunk 1000 records
+- ✅ **Export Info**: Header informasi perusahaan, user, tanggal export
+- ✅ **Memory Management**: Manajemen memory dan execution time
+- ✅ **Flexible Headers**: Support custom headers dan column mapping
+
+## Configuration
+
+### Environment Variables
+Tambahkan variabel berikut ke `.env`:
+
+```env
+# Export Configuration
+EXPORT_AUTHOR_NAME="System Administrator"
+EXPORT_AUTHOR_EMAIL="admin@company.com"
+EXPORT_COMPANY_NAME="Your Company Name"
+EXPORT_COMPANY_ADDRESS="Company Address"
+EXPORT_COMPANY_PHONE="+62-xxx-xxx-xxx"
+EXPORT_COMPANY_WEBSITE="https://company.com"
+EXPORT_CHUNK_SIZE=1000
+EXPORT_MEMORY_LIMIT=512M
+EXPORT_MAX_EXECUTION_TIME=300
+EXPORT_TEMP_DIRECTORY=storage/exports/temp
+EXPORT_INCLUDE_INFO=true
+EXPORT_INCLUDE_TIMESTAMP=true
+EXPORT_INCLUDE_USER_INFO=true
+EXPORT_INCLUDE_COMPANY_INFO=true
+```
+
+### Config File
+File konfigurasi tersedia di `config/export_info.php` dengan pengaturan untuk:
+- Author information
+- Company details
+- Export settings
+- Default styles
+- Format configurations
+
+## Basic Usage
+
+### 1. Simple Table Export
+
+```php
+use App\Exports\SimpleTableExport;
+use App\Models\User;
+
+// Basic export
+$query = User::query();
+$headers = ['ID', 'Name', 'Email', 'Created At'];
+
+$export = SimpleTableExport::make($query, $headers, 'Users', 'Users Report');
+
+// Download file
+return $export->download();
+
+// Or save to file
+$filePath = $export->toFile();
+```
+
+### 2. Custom Column Mapping
+
+```php
+$headers = ['ID', 'Full Name', 'Email', 'Status', 'Join Date'];
+$columnMappings = [
+    'id',
+    'name',
+    'email',
+    function ($user) {
+        return $user->email_verified_at ? 'Verified' : 'Unverified';
+    },
+    function ($user) {
+        return $user->created_at->format('d/m/Y');
+    }
+];
+
+$export = SimpleTableExport::make($query, $headers, 'Users')
+    ->setColumnMappings($columnMappings)
+    ->setReportTitle('User Status Report');
+
+return $export->download();
+```
+
+### 3. Multiple Sheets Export
+
+```php
+use App\Exports\UsersPostsExport;
+use App\Models\User;
+use App\Models\Post;
+
+// Create export with multiple sheets
+$userQuery = User::whereDate('created_at', '>=', '2024-01-01');
+$postQuery = Post::whereDate('created_at', '>=', '2024-01-01');
+
+$export = new UsersPostsExport($userQuery, $postQuery);
+$export->setReportTitle('Q1 2024 Data Report');
+
+return $export->download();
+```
+
+## Advanced Usage
+
+### 1. Using ExcelExportService Directly
+
+```php
+use App\Services\ExcelExportService;
+use App\Models\User;
+
+$exportService = new ExcelExportService();
+
+// Create multiple sheets
+$exportService
+    ->createSheet('Users', true)
+    ->createSheet('Summary');
+
+// Add data to Users sheet
+$exportService
+    ->addExportInfo('Users', 'User Data Report')
+    ->addHeaders('Users', ['ID', 'Name', 'Email', 'Created At'])
+    ->addData('Users', User::select(['id', 'name', 'email', 'created_at']))
+    ->autoSizeColumns('Users')
+    ->freezePane('Users', 'A2');
+
+// Add summary to Summary sheet
+$summaryData = [
+    [
+        'title' => 'User Statistics',
+        'headers' => ['Metric', 'Value'],
+        'data' => [
+            ['Total Users', User::count()],
+            ['Active Users', User::whereNotNull('email_verified_at')->count()],
+            ['New Users This Month', User::whereMonth('created_at', now()->month)->count()],
+        ]
+    ]
+];
+
+$exportService
+    ->addExportInfo('Summary', 'Data Summary')
+    ->addMultipleTables('Summary', $summaryData)
+    ->autoSizeColumns('Summary');
+
+// Export
+$filename = 'user_report_' . now()->format('Y-m-d_H-i-s') . '.xlsx';
+return $exportService->download($filename);
+```
+
+### 2. Custom Styling
+
+```php
+// Define custom styles
+$customHeaderStyle = [
+    'font' => [
+        'bold' => true,
+        'size' => 14,
+        'color' => ['rgb' => 'FFFFFF'],
+    ],
+    'fill' => [
+        'fillType' => \PhpOffice\PhpSpreadsheet\Style\Fill::FILL_SOLID,
+        'startColor' => ['rgb' => '4CAF50'],
+    ],
+    'borders' => [
+        'allBorders' => [
+            'borderStyle' => \PhpOffice\PhpSpreadsheet\Style\Border::BORDER_THICK,
+            'color' => ['rgb' => '000000'],
+        ],
+    ],
+];
+
+$customBodyStyle = [
+    'font' => ['size' => 11],
+    'borders' => [
+        'allBorders' => [
+            'borderStyle' => \PhpOffice\PhpSpreadsheet\Style\Border::BORDER_THIN,
+            'color' => ['rgb' => 'DDDDDD'],
+        ],
+    ],
+];
+
+// Apply to SimpleTableExport
+$export = SimpleTableExport::make($query, $headers, 'Custom Report')
+    ->setCustomStyles($customBodyStyle);
+
+// Or apply directly to service
+$exportService
+    ->addHeaders('Sheet1', $headers)
+    ->applyStyle($worksheet, 'A1:D1', $customHeaderStyle)
+    ->addData('Sheet1', $data, 1, $customBodyStyle);
+```
+
+### 3. Column Width and Formatting
+
+```php
+$export = SimpleTableExport::make($query, $headers, 'Formatted Report')
+    ->setColumnWidths([
+        'A' => 20,  // ID column
+        'B' => 30,  // Name column
+        'C' => 35,  // Email column
+        'D' => 25   // Date column
+    ]);
+
+// Or use auto-size (default behavior)
+$export->autoSizeColumns('Sheet1');
+```
+
+## API Endpoints
+
+### Available Endpoints
+
+```
+GET /api/v1/export/users-posts          // Export users and posts
+GET /api/v1/export/users                // Export users only
+GET /api/v1/export/custom-styled        // Custom styled example
+GET /api/v1/export/multiple-tables      // Multiple tables example
+```
+
+### Query Parameters
+
+- `download=true/false` - Download file or return file path (default: true)
+- `date_from` - Filter data from date (YYYY-MM-DD)
+- `date_to` - Filter data to date (YYYY-MM-DD)
+- `search` - Search term for filtering
+- `verified=true/false` - Filter verified/unverified users
+
+### Example API Calls
+
+```bash
+# Download users and posts export
+curl -H "Authorization: Bearer {token}" \
+  "http://localhost:8000/api/v1/export/users-posts?download=true"
+
+# Get file path for users export with date filter
+curl -H "Authorization: Bearer {token}" \
+  "http://localhost:8000/api/v1/export/users?download=false&date_from=2024-01-01&date_to=2024-12-31"
+
+# Export verified users only
+curl -H "Authorization: Bearer {token}" \
+  "http://localhost:8000/api/v1/export/users?verified=true&search=john"
+```
+
+## Creating Custom Export Classes
+
+### 1. Extend BaseExport
+
+```php
+<?php
+
+namespace App\Exports;
+
+class CustomExport extends BaseExport
+{
+    protected $data;
+    protected $options;
+
+    public function __construct($data, array $options = [])
+    {
+        parent::__construct();
+        
+        $this->data = $data;
+        $this->options = $options;
+        $this->reportTitle = $options['title'] ?? 'Custom Report';
+    }
+
+    public function export()
+    {
+        $this->exportService
+            ->createSheet('Data', true)
+            ->addExportInfo('Data', $this->reportTitle);
+
+        // Your custom logic here
+        $headers = $this->options['headers'] ?? ['Column 1', 'Column 2'];
+        
+        $this->exportService
+            ->addHeaders('Data', $headers)
+            ->addData('Data', $this->data)
+            ->autoSizeColumns('Data')
+            ->freezePane('Data', 'A2');
+    }
+}
+```
+
+### 2. Use the Custom Export
+
+```php
+$data = collect([
+    ['Value 1', 'Value 2'],
+    ['Value 3', 'Value 4'],
+]);
+
+$export = new CustomExport($data, [
+    'title' => 'My Custom Report',
+    'headers' => ['Column A', 'Column B']
+]);
+
+return $export->download();
+```
+
+## Performance Tips
+
+1. **Use Chunking**: Service automatically chunks data per 1000 records
+2. **Memory Limit**: Adjust `EXPORT_MEMORY_LIMIT` in .env for large datasets
+3. **Execution Time**: Set `EXPORT_MAX_EXECUTION_TIME` appropriately
+4. **Selective Fields**: Only select required columns from database
+
+```php
+// Good - select specific columns
+$query = User::select(['id', 'name', 'email', 'created_at']);
+
+// Avoid - select all columns
+$query = User::all();
+```
+
+## Error Handling
+
+Service includes built-in error handling. Wrap calls in try-catch for custom error handling:
+
+```php
+try {
+    $export = new UsersPostsExport();
+    return $export->download();
+} catch (\Exception $e) {
+    return response()->json([
+        'error' => 'Export failed: ' . $e->getMessage()
+    ], 500);
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Memory Limit Exceeded**: Increase `EXPORT_MEMORY_LIMIT`
+2. **Execution Timeout**: Increase `EXPORT_MAX_EXECUTION_TIME`
+3. **File Not Found**: Check `EXPORT_TEMP_DIRECTORY` permissions
+4. **Style Not Applied**: Verify PhpSpreadsheet style array format
+
+### Debug Mode
+
+Enable debug logging:
+
+```php
+// In export class
+\Log::info('Export started', ['query_count' => $query->count()]);
+```

package/docs/EXPORT-DATA-PROVIDERS.md

@@ -0,0 +1,340 @@
+# Export Data Providers Documentation
+
+## Overview
+Data Providers adalah komponen yang memisahkan logika data (rawData, headers, dataMapper) dari controller. Ini membuat code lebih modular, testable, dan mudah di-maintain.
+
+## Structure
+```
+app/Exports/DataProviders/
+├── ExportDataProviderInterface.php (Interface)
+├── FlexibleTemplateDataProvider.php
+├── MultiSheetTemplateDataProvider.php
+├── MultiTableTemplateDataProvider.php
+├── UserExportDataProvider.php
+├── ExternalDataProvider.php
+└── ProductExportDataProvider.php
+```
+
+## Interface Contract
+Setiap Data Provider harus implement `ExportDataProviderInterface`:
+
+```php
+interface ExportDataProviderInterface
+{
+    public function getRawData($filters = null): array;
+    public function getHeaders(): array;
+    public function getDataMapper(): array;
+    public function getOptions(): array;
+}
+```
+
+## Usage in Controller
+
+### Before (Dirty Controller)
+```php
+public function exportFlexibleTemplate(Request $request)
+{
+    // 50+ lines of hard-coded data, headers, mappers
+    $rawData = [/* lots of data */];
+    $headers = [/* headers */];
+    $dataMapper = [/* mappers */];
+    // ...
+}
+```
+
+### After (Clean Controller)
+```php
+public function exportFlexibleTemplate(Request $request)
+{
+    $provider = new FlexibleTemplateDataProvider();
+    
+    $rawData = $provider->getRawData();
+    $headers = $provider->getHeaders();
+    $dataMapper = $provider->getDataMapper();
+    $options = $provider->getOptions();
+
+    $export = FlexibleExport::create($rawData, $headers, array_merge($options, [
+        'data_mapper' => $dataMapper
+    ]));
+
+    return $request->boolean('download', true) ? $export->download() : /* JSON response */;
+}
+```
+
+## Benefits
+
+### 1. Separation of Concerns
+- Controller hanya handle HTTP layer
+- Data Provider handle data preparation
+- Export Templates handle Excel generation
+
+### 2. Reusability
+Data providers bisa digunakan di berbagai controller atau command:
+```php
+// Di Controller
+$provider = new UserExportDataProvider($request);
+
+// Di Artisan Command  
+$provider = new UserExportDataProvider();
+
+// Di Job Queue
+$provider = new UserExportDataProvider();
+```
+
+### 3. Testability
+```php
+class UserExportDataProviderTest extends TestCase
+{
+    public function test_get_headers()
+    {
+        $provider = new UserExportDataProvider(new Request());
+        $headers = $provider->getHeaders();
+        
+        $this->assertEquals(['ID', 'Full Name', 'Email Address', ...], $headers);
+    }
+}
+```
+
+### 4. Maintainability
+Ubah data mapping tanpa touch controller:
+```php
+// UserExportDataProvider.php
+public function getDataMapper(): array
+{
+    return [
+        'id',
+        'name',
+        'email',
+        // Add new formatter without changing controller
+        function ($user) {
+            return $user['premium'] ? 'Premium ⭐' : 'Regular';
+        }
+    ];
+}
+```
+
+## Provider Types
+
+### 1. Simple Data Provider
+Untuk static/sample data:
+```php
+class FlexibleTemplateDataProvider implements ExportDataProviderInterface
+{
+    public function getRawData($filters = null): array
+    {
+        return [/* static sample data */];
+    }
+}
+```
+
+### 2. Model-based Data Provider
+Untuk data dari database:
+```php
+class UserExportDataProvider implements ExportDataProviderInterface
+{
+    private Request $request;
+
+    public function __construct(Request $request)
+    {
+        $this->request = $request;
+    }
+
+    public function getRawData($filters = null): array
+    {
+        $query = User::query();
+        // Apply request filters
+        return $query->get()->toArray();
+    }
+}
+```
+
+### 3. Complex Data Provider
+Untuk multi-sheet/multi-table:
+```php
+class MultiSheetTemplateDataProvider implements ExportDataProviderInterface
+{
+    // Implement helper methods
+    public function getFormattedSheets(): array
+    {
+        // Return ready-to-use sheets configuration
+    }
+}
+```
+
+### 4. External API Data Provider
+Untuk data dari API external:
+```php
+class ExternalDataProvider implements ExportDataProviderInterface
+{
+    public function getRawData($filters = null): array
+    {
+        // Fetch from external API
+        // Transform data
+        return $transformedData;
+    }
+}
+```
+
+## Creating New Data Provider
+
+### Step 1: Create Provider Class
+```php
+<?php
+namespace App\Exports\DataProviders;
+
+class NewExportDataProvider implements ExportDataProviderInterface
+{
+    public function getRawData($filters = null): array
+    {
+        // Your data logic here
+        return [];
+    }
+
+    public function getHeaders(): array
+    {
+        return ['Column 1', 'Column 2'];
+    }
+
+    public function getDataMapper(): array
+    {
+        return [
+            'field1',
+            function ($item) {
+                return formatValue($item['field2']);
+            }
+        ];
+    }
+
+    public function getOptions(): array
+    {
+        return [
+            'sheet_title' => 'My Export',
+            'report_title' => 'My Report',
+            'column_widths' => ['A' => 15, 'B' => 20],
+            'freeze_pane' => 'A2'
+        ];
+    }
+}
+```
+
+### Step 2: Use in Controller
+```php
+public function exportNewTemplate(Request $request)
+{
+    try {
+        $provider = new NewExportDataProvider();
+        
+        $rawData = $provider->getRawData();
+        $headers = $provider->getHeaders();
+        $dataMapper = $provider->getDataMapper();
+        $options = $provider->getOptions();
+
+        $export = FlexibleExport::create($rawData, $headers, array_merge($options, [
+            'data_mapper' => $dataMapper
+        ]));
+
+        return $request->boolean('download', true) ? $export->download() : /* JSON response */;
+
+    } catch (\Exception $e) {
+        return response()->json([
+            'success' => false,
+            'message' => 'Export failed: ' . $e->getMessage()
+        ], 500);
+    }
+}
+```
+
+## Advanced Features
+
+### Dynamic Filtering
+```php
+public function getRawData($filters = null): array
+{
+    $query = Model::query();
+    
+    if ($filters) {
+        foreach ($filters as $key => $value) {
+            $query->where($key, $value);
+        }
+    }
+    
+    return $query->get()->toArray();
+}
+```
+
+### Conditional Data Mapping
+```php
+public function getDataMapper(): array
+{
+    $mappers = ['id', 'name', 'email'];
+    
+    // Add conditional mappers
+    if (auth()->user()->hasPermission('view_sensitive_data')) {
+        $mappers[] = function ($item) {
+            return $item['social_security_number'];
+        };
+    }
+    
+    return $mappers;
+}
+```
+
+### Caching Support
+```php
+public function getRawData($filters = null): array
+{
+    $cacheKey = 'export_data_' . md5(serialize($filters));
+    
+    return Cache::remember($cacheKey, 300, function () use ($filters) {
+        return Model::query()->where($filters)->get()->toArray();
+    });
+}
+```
+
+## Testing Examples
+
+```php
+class UserExportDataProviderTest extends TestCase
+{
+    public function test_headers_contain_required_columns()
+    {
+        $provider = new UserExportDataProvider(new Request());
+        $headers = $provider->getHeaders();
+        
+        $this->assertContains('ID', $headers);
+        $this->assertContains('Full Name', $headers);
+        $this->assertContains('Email Address', $headers);
+    }
+
+    public function test_data_mapper_formats_correctly()
+    {
+        $provider = new UserExportDataProvider(new Request());
+        $mapper = $provider->getDataMapper();
+        
+        $testData = ['email_verified_at' => '2024-01-15'];
+        $result = $mapper[3]($testData); // Verification status mapper
+        
+        $this->assertEquals('Verified ✓', $result);
+    }
+}
+```
+
+## Best Practices
+
+1. **Single Responsibility**: Satu provider untuk satu jenis export
+2. **Consistent Naming**: `[Entity]ExportDataProvider` atau `[Purpose]DataProvider`
+3. **Documentation**: Comment complex data mappers
+4. **Error Handling**: Handle missing/invalid data gracefully
+5. **Performance**: Use eager loading, chunking untuk data besar
+6. **Security**: Validate permissions dalam getRawData()
+
+## Migration Path
+
+1. Identify hard-coded data in controllers
+2. Create corresponding data provider
+3. Move data logic to provider
+4. Update controller to use provider
+5. Test functionality
+6. Remove old hard-coded data
+
+Semua export functions telah berhasil di-refactor dan tested! 🎉