# Report Export Dependency Failure Roadmap

## Problem

The admin general-information export endpoints fail under Laravel `12.58.0` and PHP `8.2.12`:

- Excel: `Interface "Maatwebsite\\Excel\\Concerns\\FromCollection" not found`
- PDF: the PDF export also reports a failure and needs a separate runtime verification

The failing Excel request is:

```text
GET /admin/reports/loans/export/excel?due_date=2026-08-19
```

This roadmap documents the diagnosis and the safe repair sequence before application code is changed.

## Confirmed Excel Root Cause

The application code uses the Laravel Excel 3.x concern API:

```php
use Maatwebsite\Excel\Concerns\FromCollection;
use Maatwebsite\Excel\Concerns\WithHeadings;
use Maatwebsite\Excel\Concerns\ShouldAutoSize;
```

`app/Exports/ArrayExport.php` implements those interfaces.

However, `composer.json` currently requires:

```json
"maatwebsite/excel": "^1.1"
```

The installed package is:

```text
maatwebsite/excel v1.1.5
```

That package is from 2014 and uses the old Laravel Excel API. It does not provide the `Maatwebsite\Excel\Concerns\FromCollection` namespace, which is why PHP fails while loading `ArrayExport`.

The installed package also depends on the old `phpoffice/phpexcel` engine. The current vendor state does not provide the modern `PhpSpreadsheet` package/class expected by the current export implementation. Existing logs also show missing PHPExcel/PhpSpreadsheet files during export loading.

### Correct compatibility target

Laravel 12 and PHP 8.2 require a current Laravel Excel release compatible with the Laravel 12 container. The selected release must be confirmed against the package's compatibility matrix before installation. The implementation should remain on the current concern-based API after upgrading.

## PDF Dependency Findings

The PDF imports are:

```php
use Barryvdh\DomPDF\Facade\Pdf;
```

The installed PDF packages are present and autoload successfully:

- `barryvdh/laravel-dompdf v3.1.2`
- `dompdf/dompdf v3.1.5`
- `Barryvdh\DomPDF\Facade\Pdf` resolves successfully
- `Dompdf\Dompdf` resolves successfully

Therefore, the PDF issue is not currently proven to be a missing PDF package. It must be reproduced after the dependency state is stabilized and captured from the current `storage/logs/laravel.log`.

The PDF endpoint uses the same `buildLoanGeneralInfoQuery()` data path as Excel and renders:

```text
resources/views/admin/reports/loan_general_info_pdf.blade.php
```

The PDF investigation must separately check:

- whether the PDF route reaches the controller
- whether the filtered loan query succeeds
- whether all eager-loaded relationships used by the Blade view exist
- whether the PDF view compiles with the current loan data
- whether the selected due-date filter is applied to the export query
- whether the PHP `ext-dom` and `ext-mbstring` extensions are enabled
- whether the generated response fails during rendering or download streaming

Do not assume the PDF failure is caused by Excel. They are separate exporters with separate dependencies.

## Current Export Data Path

Both admin general-information export methods call:

```text
AdminReportingController::buildLoanGeneralInfoQuery()
```

The query currently supports:

- `status`
- `tier_id`
- `search`
- `due_date`

The `due_date` filter matches loans having at least one repayment with the selected date:

```php
$query->whereHas('repayments', function ($query) use ($dueDate) {
    $query->whereDate('due_date', $dueDate);
});
```

The due-date filter must remain identical for the browser list, Excel export, and PDF export.

## Safe Repair Plan

### Phase 1: Capture the failure

1. Record the exact Excel exception and stack trace.
2. Request the PDF endpoint independently and record its exact exception.
3. Confirm the application environment uses the intended `.env` and MySQL connection.
4. Confirm the due-date filter returns the expected loan set before export rendering.

### Phase 2: Repair the Excel dependency

1. Update the direct `maatwebsite/excel` requirement to a Laravel 12-compatible 3.x release.
2. Remove the obsolete Laravel Excel 1.x/PHPExcel dependency path through Composer resolution.
3. Run Composer dependency resolution and regenerate `composer.lock`.
4. Run `composer dump-autoload`.
5. Confirm these classes resolve:
   - `Maatwebsite\Excel\Concerns\FromCollection`
   - `Maatwebsite\Excel\Concerns\WithHeadings`
   - `Maatwebsite\Excel\Concerns\ShouldAutoSize`
   - `Maatwebsite\Excel\Facades\Excel`
6. Keep `app/Exports/ArrayExport.php` on the concern-based API unless the selected package version requires a documented API adjustment.

Do not manually copy vendor files or add compatibility shims for the missing interface. The dependency graph and lock file must be corrected through Composer.

### Phase 3: Verify the PDF path

1. Confirm `Barryvdh\DomPDF\Facade\Pdf` and `Dompdf\Dompdf` resolve.
2. Render the PDF Blade view with a small known loan collection in a focused test or controlled command.
3. Request the real PDF endpoint with `due_date=2026-08-19`.
4. Check that the response has a PDF content type and non-empty body.
5. Capture and fix any view, relationship, encoding, memory, or extension error separately.
6. Do not change the PDF dependency unless the reproduced exception identifies a dependency incompatibility.

### Phase 4: Export behavior checks

Verify both export formats with and without a due-date filter:

- no filter returns the normal complete loan set
- `due_date=2026-08-19` returns only loans with an installment due that day
- invalid dates are rejected by validation
- Excel includes headings and rows
- PDF includes the same fields and rows
- export links preserve the active list query parameters

### Phase 5: Regression validation

Run:

```text
php -l app/Exports/ArrayExport.php
php -l app/Http/Controllers/Admin/AdminReportingController.php
php artisan route:list
php artisan view:cache
composer dump-autoload
php artisan test tests/Feature/AdminLoanGeneralInfoTest.php
```

The existing test environment may fail before assertions because some migrations use MySQL-specific syntax against SQLite. That infrastructure failure should be reported separately from export failures.

## Files Expected To Change During Implementation

The roadmap expects the eventual implementation to touch only the files required by the confirmed failure:

- `composer.json`
- `composer.lock`
- possibly `app/Exports/ArrayExport.php` if the selected compatible package requires an API adjustment
- possibly `app/Http/Controllers/Admin/AdminReportingController.php` if PDF runtime diagnostics identify a controller-specific issue
- possibly `resources/views/admin/reports/loan_general_info_pdf.blade.php` if PDF rendering identifies a view issue
- focused export tests or documentation as needed

No database migration is required for the dependency repair.

## Acceptance Criteria

- `Maatwebsite\Excel\Concerns\FromCollection` resolves under Laravel 12/PHP 8.2.
- The admin Excel export downloads successfully.
- The admin PDF export downloads successfully.
- Both formats honor the installment `due_date` filter.
- Excel and PDF contain the same filtered loan population.
- No vendor files are manually edited.
- Normal admin loan-list filtering remains unchanged.
- Any PDF-specific failure is diagnosed and fixed independently from the Excel dependency failure.

## Implementation Status

The roadmap solution has been implemented.

### Dependency repair completed

- `maatwebsite/excel` was changed from the obsolete `^1.1` requirement to `3.1.70` in `composer.json`.
- `composer.lock` now locks Laravel Excel `3.1.70`.
- The obsolete `phpoffice/phpexcel 1.8.1` dependency was removed.
- `phpoffice/phpspreadsheet 1.30.6` was installed.
- Composer autoload mappings and Laravel package discovery were regenerated.
- The XAMPP PHP CLI configuration enabled `ext-gd` and `ext-zip`, which are required by PhpSpreadsheet.

### Runtime verification completed

- `Maatwebsite\\Excel\\Concerns\\FromCollection` resolves successfully.
- `Maatwebsite\\Excel\\Concerns\\WithHeadings` and `ShouldAutoSize` resolve successfully.
- `Maatwebsite\\Excel\\Facades\\Excel` resolves successfully.
- A controlled XLSX export generated a non-empty `6,268` byte payload.
- `Barryvdh\\DomPDF\\Facade\\Pdf` and `Dompdf\\Dompdf` resolve successfully.
- The existing PDF report view rendered a non-empty `878,651` byte payload with no loans.
- The real `due_date=2026-08-19` query matched `16` loans.
- The filtered PDF rendered an `886,708` byte payload.
- The filtered XLSX rendered a `6,416` byte payload.

The PDF and Excel exporters now use the same filtered loan population. No database migration was required for this dependency repair.
