Excel Import

The Excel Import functionality is a decoupled, modular system designed to centralize complex file parsing while delegating business logic (database operations) to individual modules. This architecture ensures high performance, full localization, and easy maintenance.

---

🚀 Overview

The system consists of three main layers:

1. Parser (magic addon): Handles file uploads and converts Excel rows into a standardized PHP array based on a provided mapping.
2. Orchestrator (direction addon): Authenticates requests and routes the parsed data to the correct module.
3. Handler (Specific Module): Receives the cleaned data and performs specific tasks like database insertion.

---

🛠️ Usage & Configuration

To enable Excel import for a module, you need to configure the $conf array in your module’s initialization method (e.g., at_cpv.module.php).

1. Enable the UI

Add the import_excel flag and define the column mapping.

PHP

$conf['import_excel'] = true;

// Define which Excel columns map to which database fields
$conf['import_mapping'] = [
    ['column' => 'cpv-code', 'required' => true],
    ['column' => 'cpv-description', 'required' => false],
    ['column' => 'cpv-unit', 'required' => false]
];

// (Optional) Define where to go after a successful import
$conf['redirect'] = $this->lib->url->url('direction', 'cpv');

JSON

{
  "import_excel": true,
  "import_mapping": [
    { "column": "cpv-code", "required": true },
    { "column": "cpv-description", "required": false },
    { "column": "cpv-unit", "required": false }
  ],
  "redirect": "direction/cpv"
}

---

📥 Backend Handler

Every module that supports Excel import MUST implement the following method:

import_excel_data(array $data): array

This method receives the parsed array from the Excel file. Each element in the array is a row mapped according to your $conf['import_mapping'].

📋 Example Implementation:

public function import_excel_data(array $data): array
{
    foreach ($data as $row) {
        $code = $row['cpv-code'];
        $desc = $row['cpv-description'];
        
        // Your database logic here...
        $this->model->save_item($code, $desc);
    }

    return ['success' => 1, 'message' => 'Successfully imported ' . count($data) . ' items.'];
}

---

📋 Technical Parameters

Parameter	Type	Description
import_excel	bool	Enables the "Import Excel" button in the Autotable UI.
import_mapping	array	A list of objects defining column (field name) and required (boolean).
redirect	string	The URL the browser will navigate to upon successful import.
additional_data	array	(Optional) Hidden key-value pairs passed from the UI to the handler.

---

🌍 Localization

All error messages (e.g., "Missing required field", "Empty file") are managed via the framework's language system (.ini files).

• Dynamic Variables: Use %s for dynamic values like row numbers or field names.
• Example Key: missing_required_field_on_row=%s տողի %s պարտադիր դաշտը բացակայում է

---

⚠️ Best Practices

Resource Limits

Large imports automatically increase the PHP memory_limit to 512M and max_execution_time to 600s (10 minutes) during the orchestration phase.

Validation

Always perform final security validation within your import_excel_data() method to ensure data integrity before database insertion.