base-api-scramble-mcp 1.0.0

package/docs/EXPORT-TEMPLATES.md

@@ -0,0 +1,459 @@
+# Export Templates Documentation
+
+Template-template export Excel yang fleksibel dan tidak bergantung pada model Laravel. Semua data harus di-mapping terlebih dahulu sebelum export.
+
+## 🎯 Export Templates
+
+### 1. FlexibleExport Template
+
+Template untuk export single sheet dengan mapping data yang fleksibel.
+
+**Features:**
+- ✅ Support array data tanpa model
+- ✅ Custom data mapping dengan callback functions
+- ✅ Dot notation untuk nested data
+- ✅ Custom styling dan column widths
+- ✅ Auto-size columns
+
+**Usage:**
+```php
+use App\Exports\Templates\FlexibleExport;
+
+// Sample data
+$rawData = [
+    ['id' => 1, 'name' => 'John', 'email' => 'john@test.com', 'created_at' => '2024-01-15'],
+    ['id' => 2, 'name' => 'Jane', 'email' => 'jane@test.com', 'created_at' => '2024-01-16'],
+];
+
+$headers = ['ID', 'Full Name', 'Email', 'Join Date'];
+
+// Data mapper dengan callback
+$dataMapper = [
+    'id',
+    'name', 
+    'email',
+    function ($item) {
+        return date('d/m/Y', strtotime($item['created_at']));
+    }
+];
+
+$export = FlexibleExport::create($rawData, $headers, [
+    'sheet_title' => 'Users',
+    'report_title' => 'User Report',
+    'data_mapper' => $dataMapper,
+    'column_widths' => ['A' => 10, 'B' => 20, 'C' => 30, 'D' => 15]
+]);
+
+return $export->download();
+```
+
+### 2. MultiSheetExport Template
+
+Template untuk export multiple sheets dengan data mapping.
+
+**Usage:**
+```php
+use App\Exports\Templates\MultiSheetExport;
+
+$sheets = [
+    [
+        'title' => 'Users',
+        'headers' => ['ID', 'Name', 'Status'],
+        'data' => $usersData,
+        'data_mapper' => [
+            'id',
+            'name',
+            function ($item) {
+                return $item['active'] ? 'Active' : 'Inactive';
+            }
+        ]
+    ],
+    [
+        'title' => 'Posts', 
+        'headers' => ['ID', 'Title', 'Author'],
+        'data' => $postsData,
+        'data_mapper' => ['id', 'title', 'author_name']
+    ]
+];
+
+$export = MultiSheetExport::create($sheets, [
+    'report_title' => 'Complete Report',
+    'include_summary' => true
+]);
+
+return $export->download();
+```
+
+### 3. MultiTableExport Template
+
+Template untuk export multiple tables dalam satu sheet.
+
+**Usage:**
+```php
+use App\Exports\Templates\MultiTableExport;
+
+$tables = [
+    [
+        'title' => 'Summary Statistics',
+        'headers' => ['Metric', 'Value'],
+        'data' => $summaryData,
+        'data_mapper' => [
+            'metric',
+            function ($item) {
+                return number_format($item['value']);
+            }
+        ]
+    ],
+    [
+        'title' => 'Top Users',
+        'headers' => ['Name', 'Score'],
+        'data' => $topUsersData,
+        'data_mapper' => ['name', 'score']
+    ]
+];
+
+$export = MultiTableExport::create($tables, 'Dashboard');
+return $export->download();
+```
+
+## 📡 API Endpoints
+
+### Template Endpoints (Tanpa Model Dependency)
+
+```bash
+# Flexible single sheet template
+GET /api/v1/export/flexible-template
+
+# Multi-sheet template  
+GET /api/v1/export/multi-sheet-template
+
+# Multi-table template
+GET /api/v1/export/multi-table-template
+
+# External API data template
+GET /api/v1/export/external-data-template
+
+# Custom styling template
+GET /api/v1/export/custom-style-template
+```
+
+### Model-Based Endpoints (Dengan Mapping)
+
+```bash
+# Users export dengan mapping
+GET /api/v1/export/users-with-mapping?search=john&verified=true
+```
+
+## 🔧 Data Mapping Examples
+
+### 1. Simple Field Mapping
+
+```php
+$dataMapper = [
+    'id',           // ambil field 'id' langsung
+    'name',         // ambil field 'name' langsung  
+    'email'         // ambil field 'email' langsung
+];
+```
+
+### 2. Callback Function Mapping
+
+```php
+$dataMapper = [
+    'id',
+    function ($item) {
+        return strtoupper($item['name']);  // format nama jadi uppercase
+    },
+    function ($item) {
+        return $item['is_active'] ? 'Active ✓' : 'Inactive ✗';
+    },
+    function ($item) {
+        return date('d/m/Y H:i', strtotime($item['created_at']));
+    }
+];
+```
+
+### 3. Nested Data Mapping (Dot Notation)
+
+```php
+// Data structure:
+$data = [
+    'user_id' => 1,
+    'profile' => [
+        'first_name' => 'John',
+        'contact' => [
+            'email' => 'john@example.com'
+        ]
+    ]
+];
+
+$dataMapper = [
+    'user_id',
+    'profile.first_name',      // dot notation untuk nested
+    'profile.contact.email',   // nested level 2
+    function ($item) {
+        return $item['profile']['first_name'] . ' ' . $item['profile']['last_name'];
+    }
+];
+```
+
+### 4. Complex API Data Mapping
+
+```php
+// Data dari external API
+$apiData = [
+    'id' => 'ext_001',
+    'user_info' => [
+        'name' => 'John Doe',
+        'stats' => [
+            'orders' => 25,
+            'total_spent' => 1250.75
+        ]
+    ],
+    'created' => '2024-01-15T10:30:00Z'
+];
+
+$dataMapper = [
+    'id',
+    'user_info.name',
+    function ($item) {
+        return number_format($item['user_info']['stats']['orders']) . ' orders';
+    },
+    function ($item) {
+        return '$' . number_format($item['user_info']['stats']['total_spent'], 2);
+    },
+    function ($item) {
+        return date('d/m/Y', strtotime($item['created']));
+    }
+];
+```
+
+## 🎨 Custom Styling Examples
+
+### 1. Header Styling
+
+```php
+$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'],
+        ],
+    ],
+];
+```
+
+### 2. Body Styling
+
+```php
+$customBodyStyle = [
+    'font' => ['size' => 11, 'name' => 'Calibri'],
+    'borders' => [
+        'allBorders' => [
+            'borderStyle' => \PhpOffice\PhpSpreadsheet\Style\Border::BORDER_THIN,
+            'color' => ['rgb' => 'CCCCCC'],
+        ],
+    ],
+    'alignment' => [
+        'vertical' => \PhpOffice\PhpSpreadsheet\Style\Alignment::VERTICAL_CENTER,
+    ],
+];
+```
+
+## 🚀 Implementation Examples
+
+### 1. Export Data dari Database Query
+
+```php
+// Controller method
+public function exportCustomData(Request $request)
+{
+    // Query database
+    $users = DB::table('users')
+        ->join('profiles', 'users.id', '=', 'profiles.user_id')
+        ->select('users.*', 'profiles.phone', 'profiles.address')
+        ->where('users.active', true)
+        ->get()
+        ->toArray();
+
+    $headers = ['ID', 'Name', 'Email', 'Phone', 'Address', 'Status'];
+    
+    $dataMapper = [
+        'id',
+        'name',
+        'email', 
+        'phone',
+        'address',
+        function ($item) {
+            return 'Active ✓';
+        }
+    ];
+
+    $export = FlexibleExport::create($users, $headers, [
+        'sheet_title' => 'Active Users',
+        'data_mapper' => $dataMapper
+    ]);
+
+    return $export->download();
+}
+```
+
+### 2. Export Data dari External API
+
+```php
+public function exportExternalData(Request $request)
+{
+    // Fetch dari API
+    $response = Http::get('https://api.example.com/users');
+    $apiData = $response->json()['data'];
+
+    $headers = ['ID', 'Name', 'Email', 'Country', 'Total Orders'];
+    
+    $dataMapper = [
+        'user_id',
+        'profile.full_name',
+        'contact.email',
+        'location.country',
+        function ($item) {
+            return number_format($item['stats']['total_orders']);
+        }
+    ];
+
+    $export = FlexibleExport::create($apiData, $headers, [
+        'sheet_title' => 'API Users',
+        'report_title' => 'External Users Report',
+        'data_mapper' => $dataMapper
+    ]);
+
+    return $export->download();
+}
+```
+
+### 3. Export Multiple Data Sources
+
+```php
+public function exportCombinedData(Request $request)
+{
+    // Data dari berbagai sumber
+    $usersData = User::all()->toArray();
+    $ordersData = Order::with('user')->get()->toArray();
+    $statsData = [
+        ['metric' => 'Total Users', 'value' => count($usersData)],
+        ['metric' => 'Total Orders', 'value' => count($ordersData)],
+    ];
+
+    $sheets = [
+        [
+            'title' => 'Users',
+            'headers' => ['ID', 'Name', 'Email', 'Join Date'],
+            'data' => $usersData,
+            'data_mapper' => [
+                'id', 'name', 'email',
+                function ($item) {
+                    return date('d/m/Y', strtotime($item['created_at']));
+                }
+            ]
+        ],
+        [
+            'title' => 'Orders', 
+            'headers' => ['Order ID', 'Customer', 'Total', 'Date'],
+            'data' => $ordersData,
+            'data_mapper' => [
+                'id',
+                'user.name',
+                function ($item) {
+                    return '$' . number_format($item['total'], 2);
+                },
+                function ($item) {
+                    return date('d/m/Y', strtotime($item['created_at']));
+                }
+            ]
+        ]
+    ];
+
+    $export = MultiSheetExport::create($sheets, [
+        'report_title' => 'Business Report',
+        'include_summary' => true
+    ]);
+
+    return $export->download();
+}
+```
+
+## ⚡ Performance Tips
+
+1. **Use Chunking untuk Data Besar**
+   ```php
+   // Service akan otomatis chunk per 1000 records
+   // Bisa diatur di config/export_info.php
+   ```
+
+2. **Selective Field Selection**
+   ```php
+   // Hanya ambil field yang dibutuhkan
+   $data = User::select(['id', 'name', 'email'])->get()->toArray();
+   ```
+
+3. **Memory Management**
+   ```php
+   // Set di .env
+   EXPORT_MEMORY_LIMIT=1024M
+   EXPORT_MAX_EXECUTION_TIME=600
+   ```
+
+## 🔥 Advanced Usage
+
+### Custom Template Class
+
+```php
+<?php
+
+namespace App\Exports\Custom;
+
+use App\Exports\Templates\FlexibleExport;
+
+class SalesReportExport extends FlexibleExport
+{
+    public function __construct(array $salesData, string $period)
+    {
+        $headers = ['Date', 'Product', 'Quantity', 'Revenue', 'Profit Margin'];
+        
+        $dataMapper = [
+            function ($item) {
+                return date('d/m/Y', strtotime($item['sale_date']));
+            },
+            'product_name',
+            'quantity',
+            function ($item) {
+                return '$' . number_format($item['revenue'], 2);
+            },
+            function ($item) {
+                $margin = (($item['revenue'] - $item['cost']) / $item['revenue']) * 100;
+                return number_format($margin, 1) . '%';
+            }
+        ];
+
+        parent::__construct([
+            'data' => $salesData,
+            'headers' => $headers,
+            'sheet_title' => 'Sales Report',
+            'report_title' => "Sales Report - {$period}",
+            'data_mapper' => $dataMapper,
+            'column_widths' => ['A' => 12, 'B' => 25, 'C' => 10, 'D' => 15, 'E' => 15]
+        ]);
+    }
+}
+
+// Usage
+$export = new SalesReportExport($salesData, 'January 2024');
+return $export->download();
+```