Download the PHP package azaharizaman/nexus-import without Composer

Nexus\Import

[]() []()

Framework-agnostic data import engine with transformation, validation, and transaction management.

The Nexus\Import package provides a high-integrity, modular import system for processing CSV, JSON, XML, and Excel files with configurable field mappings, data transformations, validation rules, duplicate detection, and flexible transaction strategies.

📚 Table of Contents

• Features
• Installation
• Quick Start
• Core Concepts
  • Value Objects
  • Built-in Transformation Rules
  • Validation Rules
  • Import Handler
  • Transaction Manager
• Transaction Strategies
• Error Handling
• Advanced Usage
• Available Interfaces
• Integration Examples
• Architecture
• Testing
• Documentation
• License

Features

• 🔄 Multiple Import Formats: CSV, JSON, XML, Excel (via Atomy integration)
• 🎯 Field Mapping: Map source fields to target fields with transformations
• ✨ Data Transformations: 13 built-in transformation rules (trim, upper, lower, date formatting, type casting, etc.)
• ✅ Validation Engine: Required fields, email, numeric, min/max, length, date validation
• 🔍 Duplicate Detection: Internal (within import file) and external (against existing data)
• 💾 Transaction Strategies: TRANSACTIONAL (single transaction), BATCH (transaction per batch), STREAM (no transaction)
• 🎭 Import Modes: CREATE, UPDATE, UPSERT, DELETE, SYNC
• 📊 Comprehensive Error Reporting: Row-level errors with severity (WARNING, ERROR, CRITICAL)
• 🚀 Memory Efficient: Streaming support for large datasets

Installation

Quick Start

Core Components

1. Value Objects

ImportFormat

ImportMode

ImportStrategy

FieldMapping

2. Built-in Transformation Rules

3. Validation Rules

4. Import Handler

Implement ImportHandlerInterface to define domain-specific persistence logic:

5. Transaction Manager

Implement TransactionManagerInterface for database transaction management:

Transaction Strategies

TRANSACTIONAL Strategy

• Use Case: Critical imports where all-or-nothing is required (e.g., financial data)
• Behavior: Single transaction wrapping entire import, rollback on any critical error
• Memory: Holds all changes in memory until commit
• Error Handling: One critical error fails entire import

BATCH Strategy

• Use Case: Large imports where partial success is acceptable
• Behavior: Transaction per batch (500 rows default), continue on batch failure
• Memory: Moderate - processes in chunks
• Error Handling: Failed batches are skipped, others continue

STREAM Strategy

• Use Case: Very large files with minimal memory footprint
• Behavior: Row-by-row processing, no transaction wrapper
• Memory: Minimal - processes one row at a time
• Error Handling: Row failures don't affect other rows

Error Handling

Error Severity Levels

• WARNING: Non-critical issue, row processed successfully
• ERROR: Critical issue, row skipped
• CRITICAL: System failure, entire import may fail (TRANSACTIONAL mode)

Accessing Errors

Available Interfaces

The package defines 10 core interfaces for dependency injection:

Primary Interfaces

Engine Interfaces

Optional Interfaces

See full API documentation: docs/api-reference.md

Integration Examples

Laravel Integration

See complete integration guide: docs/integration-guide.md

See working examples: docs/examples/

Advanced Usage

Custom Transformations

Auto-Mapping

Duplicate Detection

Integration with Atomy (Laravel)

1. Create ExcelParser

2. Register in Service Provider

Architecture

The Nexus\Import package follows strict framework-agnostic principles:

• Pure PHP: No Laravel dependencies in package code
• Contract-Driven: All external dependencies via interfaces
• Immutable VOs: Value objects are readonly and validated
• Error Collection: Transformations/validations collect errors (don't throw) for batch completion
• Separation of Concerns: Processor enforces strategies, Handler handles persistence

Package Structure

Testing

Running Package Tests

Current Test Status

Coverage: 0% (Tests pending implementation)
Planned Tests: ~65 tests (50 unit, 15 integration)
Target Coverage: 90%+

See test documentation: TEST_SUITE_SUMMARY.md

Writing Custom Tests

Documentation

Package Documentation

• Getting Started Guide - Quick start with Laravel integration
• API Reference - Complete interface and class documentation
• Integration Guide - Laravel, Symfony, and vanilla PHP integration
• Basic Usage Example - Simple customer CSV import
• Advanced Usage Example - Complex scenarios with validation

Project Documentation

• Implementation Summary - Development metrics and progress
• Requirements - 78 documented requirements with traceability
• Test Suite Summary - Test coverage and planned tests
• Valuation Matrix - Package valuation ($160K estimated value)

License

MIT License. See LICENSE file for details.

Contributing

This package is part of the Nexus ERP monorepo. See main repository for contribution guidelines.

Version: 1.0.0
Status: Production Ready
Maintained By: Nexus Development Team
Last Updated: November 25, 2024