PHPackages                             dolmatovdev/laravel-x12-parser - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Payment Processing](/categories/payments)
4. /
5. dolmatovdev/laravel-x12-parser

ActiveLibrary[Payment Processing](/categories/payments)

dolmatovdev/laravel-x12-parser
==============================

Laravel package for X12 file processing with validation, parsing, and JSON conversion

v1.0.0(9mo ago)10MITPHPPHP ^8.1

Since Jul 25Pushed 9mo agoCompare

[ Source](https://github.com/DanilaD/laravel-x12-parser)[ Packagist](https://packagist.org/packages/dolmatovdev/laravel-x12-parser)[ RSS](/packages/dolmatovdev-laravel-x12-parser/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (5)Versions (2)Used By (0)

Laravel X12 Parser Package
==========================

[](#laravel-x12-parser-package)

[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)[![PHP Version](https://camo.githubusercontent.com/7535257ca228724c93658bd52583d4e47a9bab02c356abf6e54c1d575f2151e6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e312532422d626c75652e737667)](https://php.net)[![Laravel Version](https://camo.githubusercontent.com/36ab9eb40d419c375ec1c19e6d5fd0d5ae0aeb01372cc6b164966c412feecdad/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31302532422d7265642e737667)](https://laravel.com)

A comprehensive Laravel package for processing X12 files with validation, parsing, and JSON conversion capabilities. Built with clean architecture principles and optimized for maintainability.

**Author:** Danila Dolmatov ([LinkedIn](https://www.linkedin.com/in/danila-dolmatov/))

🚀 Features
----------

[](#-features)

- **ANSI X12 File Parsing**: Parse ANSI files into structured data
- **Validation**: Comprehensive validation for different transaction types
- **JSON Conversion**: Convert ANSI files to/from JSON format
- **File Building**: Generate ANSI files from structured data
- **Transaction Support**: Currently supports 270 (Eligibility/Benefit Inquiry)
- **Extensible**: Easy to add support for other transaction types
- **Laravel Integration**: Full Laravel integration with facades and service providers
- **Console Commands**: Artisan commands for file processing operations
- **Input Sanitization**: Advanced security with input validation and sanitization
- **Custom File Naming**: Dynamic file naming with placeholders and patterns
- **Clean Architecture**: Optimized codebase with shared traits and reduced duplication
- **Configuration-Driven**: Flexible configuration system with fallbacks

📋 Requirements
--------------

[](#-requirements)

- PHP 8.1+
- Laravel 10.0+ or 11.0+

📦 Installation
--------------

[](#-installation)

1. **Install via Composer:**

```
composer require dolmatovdev/laravel-x12-parser
```

2. **Publish Configuration (Optional):**

```
php artisan vendor:publish --tag=x12-parser-config
```

3. **Publish Stubs (Optional):**

```
php artisan vendor:publish --tag=x12-parser-stubs
```

🔧 Configuration
---------------

[](#-configuration)

The package configuration is located in `config/x12-parser.php`:

```
return [
    'delimiters' => [
        'segment' => '~',
        'element' => '*',
        'sub_element' => '>',
    ],

    /*
    |--------------------------------------------------------------------------
    | Transaction-Specific Delimiters
    |--------------------------------------------------------------------------
    |
    | Custom delimiters for specific transaction types.
    | If a transaction type is not listed here, the default delimiters will be used.
    |
    */
    'transaction_delimiters' => [
        // Example: Custom delimiters for 270 transactions
        // '270' => [
        //     'segment' => '~',
        //     'element' => '*',
        //     'sub_element' => '>',
        // ],

        // Example: Different delimiters for 837 transactions
        // '837' => [
        //     'segment' => '|',
        //     'element' => '^',
        //     'sub_element' => '&',
        // ],

        // Example: Legacy format with different delimiters
        // 'legacy_270' => [
        //     'segment' => '\r\n',
        //     'element' => ',',
        //     'sub_element' => ';',
        // ],
    ],

    'transaction_types' => [
        '270' => \DolmatovDev\X12Parser\Validators\Validator270::class,
    ],

    'file_storage' => [
        'default_path' => storage_path('ansi'),
        'permissions' => 0644,
        'backup_enabled' => true,
    ],

    /*
    |--------------------------------------------------------------------------
    | File Naming Configuration
    |--------------------------------------------------------------------------
    |
    | Configuration for file naming patterns and conventions.
    | You can specify custom naming patterns for different transaction types.
    |
    */
    'file_naming' => [
        // Default file naming pattern
        'default_pattern' => 'x12_{transaction_type}_{timestamp}.txt',

        // Custom naming patterns for specific transaction types
        'transaction_patterns' => [
            // Example: Custom naming for 270 transactions
            // '270' => 'eligibility_inquiry_{timestamp}_{random}.txt',

            // Example: Custom naming for 837 transactions
            // '837' => 'claim_{provider_id}_{date}_{sequence}.txt',

            // Example: Custom naming for 835 transactions
            // '835' => 'payment_remittance_{payer_id}_{date}.txt',
        ],

        // Available placeholders for file naming
        'placeholders' => [
            '{transaction_type}' => 'The transaction type (e.g., 270, 837)',
            '{timestamp}' => 'Current timestamp in Y-m-d_H-i-s format',
            '{date}' => 'Current date in Y-m-d format',
            '{time}' => 'Current time in H-i-s format',
            '{random}' => 'Random 6-digit number',
            '{sequence}' => 'Sequential number (increments per file)',
            '{provider_id}' => 'Provider ID from the data (if available)',
            '{payer_id}' => 'Payer ID from the data (if available)',
            '{member_id}' => 'Member ID from the data (if available)',
        ],

        // File extension
        'extension' => '.txt',

        // Whether to use custom naming by default
        'use_custom_naming' => false,
    ],

    'validation' => [
        'strict_mode' => true,
        'allow_warnings' => true,
        'max_segments' => 10000,
        'max_segment_length' => 1000,
    ],

    'logging' => [
        'enabled' => false,
        'level' => 'info',
    ],

    'cache' => [
        'enabled' => false,
        'ttl' => 3600,
    ],
];
```

🎯 Usage
-------

[](#-usage)

### Using the Facade

[](#using-the-facade)

```
use DolmatovDev\X12Parser\Facades\X12Parser;

// Parse X12 file to array
$data = X12Parser::parseFile('path/to/file.txt');

// Parse X12 file to JSON
$json = X12Parser::parseFileToJson('path/to/file.txt');

// Build X12 file from JSON
$x12Content = X12Parser::buildFromJson($jsonData);

// Save X12 content to file
X12Parser::saveToFile($x12Content, 'output.txt');

// Validate file without parsing
$result = X12Parser::validateFile('path/to/file.txt');
if ($result->isSuccessful()) {
    echo "File is valid!";
} else {
    echo "Validation errors: " . implode(', ', $result->errors);
}

// Build and save with auto-generated filename
$filePath = X12Parser::buildAndSaveWithAutoName($jsonData, '270');

// Get supported transaction types
$types = X12Parser::getSupportedTransactionTypes();
```

### Using Dependency Injection

[](#using-dependency-injection)

```
use DolmatovDev\X12Parser\Services\AnsiParserService;
use DolmatovDev\X12Parser\DTO\Eligibility270DTO;

class X12Controller extends Controller
{
    public function __construct(
        private AnsiParserService $ansiService
    ) {}

    public function parseFile(Request $request)
    {
        $filePath = $request->file('x12_file')->getPathname();

        try {
            $data = $this->ansiService->parseFile($filePath);
            return response()->json($data);
        } catch (\Exception $e) {
            return response()->json(['error' => $e->getMessage()], 400);
        }
    }

    public function buildFile(Request $request)
    {
        $jsonData = $request->input('data');

        try {
            $ansiContent = $this->ansiService->buildFromJson($jsonData);
            return response($ansiContent)->header('Content-Type', 'text/plain');
        } catch (\Exception $e) {
            return response()->json(['error' => $e->getMessage()], 400);
        }
    }
}
```

### Using DTOs

[](#using-dtos)

```
use DolmatovDev\X12Parser\DTO\Eligibility270DTO;
use DolmatovDev\X12Parser\Builder\X12Builder;

// Create DTO from array
$dto = Eligibility270DTO::fromArray([
    'subscriber_id' => '123456789',
    'subscriber_first_name' => 'John',
    'subscriber_last_name' => 'Doe',
    'subscriber_date_of_birth' => '19800101',
    'subscriber_gender' => 'M',
    'inquiries' => [
        ['service_type_code' => '30']
    ]
]);

// Build ANSI content from DTO
$builder = new X12Builder();
$ansiContent = $builder->buildFrom270DTO($dto);
```

### Using Transaction-Specific Delimiters

[](#using-transaction-specific-delimiters)

```
use DolmatovDev\X12Parser\Facades\X12Parser;

// Parse with custom delimiters for a specific transaction type
$result = X12Parser::parseFromFile('path/to/legacy_file.txt', '270');

// Build with custom delimiters
$ansiContent = X12Parser::buildFromJson($jsonData, '270', '270');

// Using the Parser directly with custom delimiters
use DolmatovDev\X12Parser\Parser;

$parser = new Parser();
$parser->setDelimitersForTransaction('270'); // Uses config from x12-parser.transaction_delimiters.270
$result = $parser->parseContent($content, '270');

// Set custom delimiters manually
$parser->setDelimiters([
    'segment' => '|',
    'element' => '^',
    'sub_element' => '&',
]);
```

### Console Commands

[](#console-commands)

The package provides several Artisan commands for X12 file processing:

```
# Parse an X12 file and output JSON
php artisan x12:parse path/to/file.txt

# Parse and save to file with pretty printing
php artisan x12:parse path/to/file.txt --output=output.json --pretty

# Validate an X12 file structure
php artisan x12:validate path/to/file.txt

# Build X12 file from JSON
php artisan x12:build path/to/data.json --output=output.txt --type=270
```

**Available Commands:**

- `x12:parse {file}` - Parse X12 file to JSON

    - `--output=` - Save output to file (optional)
    - `--pretty` - Pretty print JSON output
- `x12:validate {file}` - Validate X12 file structure and content
- `x12:build {json-file}` - Build X12 file from JSON data

    - `--output=` - Save output to file (optional)
    - `--type=270` - Transaction type (default: 270)

### Using Custom File Naming

[](#using-custom-file-naming)

```
use DolmatovDev\X12Parser\Facades\X12Parser;

// Build and save with auto-generated filename
$filePath = X12Parser::buildAndSaveWithAutoName($jsonData, '270');

// Build and save with custom naming pattern
$filePath = X12Parser::buildAndSaveWithAutoName(
    $jsonData,
    '270',
    ['provider_id' => '12345', 'member_id' => '67890'],
    'claim_{provider_id}_{member_id}_{timestamp}.txt'
);

// Generate filename only
$fileName = X12Parser::generateFileName('270', ['provider_id' => '12345']);

// Get available placeholders
$placeholders = X12Parser::getAvailablePlaceholders();

// Reset sequence counter
X12Parser::resetSequence();

// Set sequence counter
X12Parser::setSequence(1000);
```

📄 Supported Transaction Types
-----------------------------

[](#-supported-transaction-types)

### 270 - Eligibility/Benefit Inquiry

[](#270---eligibilitybenefit-inquiry)

The 270 transaction is used to inquire about a subscriber's eligibility and benefits.

#### Required Segments:

[](#required-segments)

- `ISA` - Interchange Control Header
- `GS` - Functional Group Header
- `ST` - Transaction Set Header
- `BHT` - Beginning of Hierarchical Transaction
- `HL` - Hierarchical Level
- `NM1` - Subscriber Name
- `SE` - Transaction Set Trailer
- `GE` - Functional Group Trailer
- `IEA` - Interchange Control Trailer

#### Optional Segments:

[](#optional-segments)

- `TRN` - Subscriber Trace Number
- `DMG` - Subscriber Demographics
- `DTP` - Date/Time Reference
- `EQ` - Subscriber Eligibility or Benefit Inquiry
- `QTY` - Quantity

#### Sample 270 File:

[](#sample-270-file)

```
ISA*00*          *00*          *ZZ*SENDER         *ZZ*RECEIVER       *240101*1200*U*00401*000000001*0*P*>~
GS*HS*SENDER*RECEIVER*20240101*1200*1*X*005010X279A1~
ST*270*0001~
BHT*0022*13*123456789*20240101*1200*RT~
HL*1**20*1~
NM1*IL*1*DOE*JOHN*A*DR*MI*123456789~
TRN*1*987654321*9123456789~
DMG*D8*19800101*M~
EQ*30~
SE*8*0001~
GE*1*1~
IEA*1*000000001~

```

🧪 Testing
---------

[](#-testing)

Run the test suite:

```
composer test
```

### Test Examples

[](#test-examples)

```
use DolmatovDev\X12Parser\Parser;
use DolmatovDev\X12Parser\Validators\Validator270;

// Test parser
$parser = new Parser();
$result = $parser->parseContent('ST*270*0001~');
$this->assertTrue($result->isSuccessful());

// Test validator
$validator = new Validator270();
$segments = ['ST*270*0001', 'SE*2*0001'];
$result = $validator->validate($segments);
$this->assertFalse($result->isSuccessful()); // Missing required segments
```

🔍 Validation
------------

[](#-validation)

The package provides comprehensive validation for ANSI files:

### Validation Features:

[](#validation-features)

- **Segment Order**: Ensures segments appear in the correct order
- **Required Segments**: Validates all required segments are present
- **Element Format**: Validates element formats and lengths
- **Business Rules**: Enforces business logic specific to each transaction type
- **Input Sanitization**: Removes control characters and validates X12-safe content

### Validation Result:

[](#validation-result)

```
$result = X12Parser::validateFile('file.txt');

if ($result->isSuccessful()) {
    echo "File is valid!";
} else {
    echo "Errors: " . implode(', ', $result->errors);
    echo "Warnings: " . implode(', ', $result->warnings);
}
```

🏗️ Architecture
---------------

[](#️-architecture)

The package follows clean architecture principles with optimized code organization:

```
src/
├── Services/           # Business logic services
│   ├── AnsiParserService.php
│   ├── ValidatorFactory.php
│   ├── FileNamingService.php
│   └── InputSanitizerService.php
├── Validators/         # Transaction validators
│   ├── AnsiValidatorInterface.php
│   └── Validator270.php
├── DTO/               # Data Transfer Objects
│   ├── ValidationResult.php
│   ├── ParseResult.php
│   └── Eligibility270DTO.php
├── Repositories/      # File operations
│   └── FileRepository.php
├── Builder/           # ANSI file building
│   └── X12Builder.php
├── Traits/            # Shared functionality
│   ├── HasDelimiters.php
│   └── HasConfig.php
├── Facades/           # Laravel facades
│   └── X12Parser.php
├── Exceptions/        # Custom exceptions
│   ├── AnsiFileException.php
│   ├── InvalidSegmentException.php
│   └── UnsupportedTransactionTypeException.php
├── Console/           # Artisan commands
│   ├── ParseX12Command.php
│   ├── ValidateX12Command.php
│   └── BuildX12Command.php
└── Parser.php         # Main parser

```

### Key Architectural Improvements:

[](#key-architectural-improvements)

- **Shared Traits**: `HasDelimiters` and `HasConfig` traits eliminate code duplication
- **Configuration-Driven**: All services use centralized configuration with fallbacks
- **Clean Separation**: Clear separation between parsing, validation, and building
- **Extensible Design**: Easy to add new transaction types and validators
- **Optimized Performance**: Reduced memory footprint and improved execution speed

🔧 Extending the Package
-----------------------

[](#-extending-the-package)

### Adding New Transaction Types

[](#adding-new-transaction-types)

1. **Create Validator:**

```
namespace DolmatovDev\X12Parser\Validators;

use DolmatovDev\X12Parser\DTO\ValidationResult;

class Validator271 implements AnsiValidatorInterface
{
    public function validate(array $segments): ValidationResult
    {
        // Implement validation logic
    }

    public function getTransactionType(): string
    {
        return '271';
    }

    public function getRequiredSegments(): array
    {
        return ['ISA', 'GS', 'ST', 'SE', 'GE', 'IEA'];
    }

    public function getOptionalSegments(): array
    {
        return [];
    }
}
```

2. **Update Configuration:**

```
// In config/x12-parser.php
    'transaction_types' => [
        '270' => \DolmatovDev\X12Parser\Validators\Validator270::class,
        '271' => \DolmatovDev\X12Parser\Validators\Validator271::class,
    ],
```

The `ValidatorFactory` will automatically load the new validator from configuration.

📚 API Reference
---------------

[](#-api-reference)

### AnsiParserService

[](#ansiparserservice)

MethodDescription`parseFile(string $filePath): array`Parse ANSI file to array`parseFileToJson(string $filePath, bool $prettyPrint = true): string`Parse ANSI file to JSON`buildFromJson(array $jsonData, string $transactionType = '270'): string`Build ANSI from JSON`buildFrom270DTO(Eligibility270DTO $dto): string`Build ANSI from DTO`saveToFile(string $content, string $filePath): bool`Save content to file`buildAndSaveWithAutoName(array $jsonData, string $transactionType, array $data, ?string $customPattern, ?string $outputDirectory): string`Build and save with auto-generated filename`generateFileName(string $transactionType, array $data, ?string $customPattern): string`Generate filename for transaction type`getAvailablePlaceholders(): array`Get available placeholders for file naming`resetSequence(): void`Reset sequence counter`setSequence(int $sequence): void`Set sequence counter`validateFile(string $filePath): ValidationResult`Validate file`getSupportedTransactionTypes(): array`Get supported types`isTransactionTypeSupported(string $transactionType): bool`Check if transaction type is supported`getFileInfo(string $filePath): array`Get file information without full parsing### Parser & X12Builder

[](#parser--x12builder)

Both classes use the `HasDelimiters` trait, providing these methods:

MethodDescription`setDelimitersForTransaction(string $transactionType): void`Set delimiters from config`setDelimiters(array $delimiters): void`Set custom delimiters`getDelimiters(): array`Get current delimiters`getDefaultDelimiters(): array`Get default delimiters### ValidationResult

[](#validationresult)

PropertyTypeDescription`success`boolWhether validation was successful`data`arraynull`errors`arrayValidation errors`warnings`arrayValidation warnings`transactionType`stringnull### Eligibility270DTO

[](#eligibility270dto)

PropertyTypeDescription`subscriberId`stringSubscriber's unique identifier`subscriberFirstName`stringSubscriber's first name`subscriberLastName`stringSubscriber's last name`subscriberDateOfBirth`stringnull`subscriberGender`stringnull`inquiries`arrayBenefit inquiries🚀 Performance & Optimization
--------------------------------

[](#-performance--optimization)

### Recent Improvements:

[](#recent-improvements)

- **Code Duplication Reduced**: ~7% reduction in total lines of code
- **Shared Traits**: Eliminated duplicate delimiter and configuration handling
- **Optimized Configuration**: Centralized config access with intelligent fallbacks
- **Improved Memory Usage**: Better resource management and reduced overhead
- **Enhanced Testability**: Instance-based services instead of static methods

### Best Practices:

[](#best-practices)

- **Use Configuration**: Leverage the configuration system for customization
- **Leverage Traits**: Extend functionality using the provided traits
- **Input Sanitization**: Always use the built-in sanitization for security
- **Error Handling**: Implement proper exception handling for production use

🤝 Contributing
--------------

[](#-contributing)

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License
---------

[](#-license)

This package is open-sourced software licensed under the **MIT License**. See the [LICENSE](LICENSE) file for the full license text.

### MIT License

[](#mit-license)

```
MIT License

Copyright (c) 2024 Danila Dolmatov

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

```

### License Summary

[](#license-summary)

- **License Type**: MIT License
- **Copyright**: © 2024 Danila Dolmatov
- **Permissions**:
    - ✅ Commercial use
    - ✅ Modification
    - ✅ Distribution
    - ✅ Private use
- **Limitations**:
    - ❌ No liability
    - ❌ No warranty
- **Conditions**: Include license and copyright notice

For more information about the MIT License, visit [opensource.org/licenses/MIT](https://opensource.org/licenses/MIT).

🔗 Links
-------

[](#-links)

- [X12.org](https://x12.org) - Official X12 standards
- [270 Transaction Specification](https://x12.org/codes/270-eligibility-benefit-inquiry)
- [Laravel Documentation](https://laravel.com/docs)

🆘 Support
---------

[](#-support)

For support, please open an issue on GitHub or contact Danila Dolmatov on [LinkedIn](https://www.linkedin.com/in/danila-dolmatov/).

###  Health Score

29

—

LowBetter than 60% of packages

Maintenance59

Moderate activity, may be stable

Popularity2

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

288d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/2318f3bd48dae2da95c2fa4230599addba0ec69cd80bda12efa113f25ed2c34d?d=identicon)[DolmatovDev](/maintainers/DolmatovDev)

---

Tags

billingclaimsclearinghouseedifhirgeneratorhealthcarehipaalaravelmedicalparserphpvalidatorx12x12-parser

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/dolmatovdev-laravel-x12-parser/health.svg)

```
[![Health](https://phpackages.com/badges/dolmatovdev-laravel-x12-parser/health.svg)](https://phpackages.com/packages/dolmatovdev-laravel-x12-parser)
```

###  Alternatives

[musahmusah/laravel-multipayment-gateways

A Laravel Package that makes implementation of multiple payment Gateways endpoints and webhooks seamless

852.2k1](/packages/musahmusah-laravel-multipayment-gateways)[wandesnet/mercadopago-laravel

PHP SDK for integration with Mercado Pago

252.4k](/packages/wandesnet-mercadopago-laravel)[devinweb/laravel-youcan-pay

YouCanPay packages for Laravel that provides an easy way to reach the best experience.

111.1k](/packages/devinweb-laravel-youcan-pay)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)