Import Data Validator Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require basilicom/import-data-validator-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Basilicom\ImportDataValidatorBundle\BasilicomImportDataValidatorBundle::class => ['all' => true],
   ];
   

2. First Use Case: Validate a CSV file with basic rules:

   # config/services.yaml
   csv.validator:
       class: Basilicom\ImportDataValidator\Validator\DefaultCsvValidator
       arguments:
           $separator: ','
   

   // In a controller or service
   use Basilicom\ImportDataValidatorBundle\Validator\ValidatorInterface;
   
   public function validateUpload(Request $request, ValidatorInterface $validator)
   {
       $file = $request->file('csv');
       $result = $validator->validate($file->getPathname());
   
       if ($result->isValid()) {
           // Process valid data
       } else {
           // Handle errors
       }
   }
   

Implementation Patterns

Core Workflow

1. Define Validators: Configure default validators (DefaultCsvValidator, DefaultXlsxValidator) in services.yaml with file-specific settings (e.g., separators, sheet names).

2. Create Rulesets: Group rules by purpose (e.g., product_import_rules) and bind them in services.yaml:

   rules.product_import:
       class: Basilicom\ImportDataValidatorBundle\Ruleset\Ruleset
       arguments:
           $rules:
               - '@rules.dataset-count'
               - '@rules.existing-columns'
               - '@rules.regex.sizes'
   

3. Validate Files: Inject the validator and ruleset into a service/controller:

   public function validate(Request $request, ValidatorInterface $validator, RulesetInterface $ruleset)
   {
       $filePath = $request->file('upload')->getPathname();
       $result = $validator->validate($filePath, $ruleset);
       return response()->json($result->getErrors());
   }
   

Integration Tips

• Laravel Filesystem: Use Storage::disk('local')->path('uploads/file.csv') to validate files stored outside the request.
• Form Requests: Extend FormRequest to validate uploads before processing:

   public function rules()
   {
       return [
           'csv' => ['required', 'file', function ($attribute, $value, $fail) {
               $validator = app()->make(ValidatorInterface::class);
               $result = $validator->validate($value->getPathname());
               if (!$result->isValid()) {
                   $fail('Validation failed: ' . implode(', ', $result->getErrors()));
               }
           }],
       ];
   }
  

• Batch Processing: Validate chunks of large files by extending DefaultCsvValidator to support streaming:

   class ChunkedCsvValidator extends DefaultCsvValidator
   {
       public function validateChunk($chunk, RulesetInterface $ruleset)
       {
           // Custom chunk validation logic
       }
   }
  

Gotchas and Tips

Pitfalls

1. Memory Limits: Large XLSX files may exceed PHP’s memory limit. Use DefaultXlsxValidator with PhpSpreadsheet’s setReadDataOnly(true) to reduce memory usage:

   xlsx.validator.service:
       class: Basilicom\ImportDataValidator\Validator\DefaultXlsxValidator
       arguments:
           $csvValidator: '@csv.validator.service'
           $datasheetName: 'Sheet 1'
           $readDataOnly: true
   

2. Rule Order Matters: Rules are evaluated in the order defined in the Ruleset. Place more critical rules (e.g., ExistingColumnsRule) earlier to fail fast.

3. Case Sensitivity: Column names in ExistingColumnsRule are case-sensitive by default. Normalize case in the rule or preprocess data:

   rules.existing-columns:
       class: Basilicom\ImportDataValidator\Rules\ExistingColumnsRule
       arguments:
           $columnNames:
               - 'sku'  # Ensure case matches input
               - 'title'
   

4. File Locking: Validate files in a temporary location to avoid conflicts during concurrent uploads:

   $tempPath = tempnam(sys_get_temp_dir(), 'import_');
   $file->moveTo($tempPath);
   $validator->validate($tempPath);
   unlink($tempPath);
   

Debugging

• Detailed Errors: Enable verbose error messages by extending AbstractRule:

   public function validate($value, $columnName, $rowNumber)
   {
       if (!$this->regex->matches($value)) {
           $this->addError(
               "Invalid format for '{$columnName}' in row {$rowNumber}. Expected: {$this->regex->pattern}. Got: {$value}"
           );
       }
   }
  

• Logging: Log validation results to storage/logs/import_validation.log:

   \Log::info('Validation errors', ['errors' => $result->getErrors()]);
  

Extension Points

1. Custom Validators: Implement ValidatorInterface for unsupported formats (e.g., JSON):

   class JsonValidator implements ValidatorInterface
   {
       public function validate($filePath, RulesetInterface $ruleset)
       {
           $data = json_decode(file_get_contents($filePath), true);
           // Custom validation logic
       }
   }
   

2. Dynamic Rules: Bind rules dynamically based on request data:

   # services.yaml
   rules.dynamic:
       class: Basilicom\ImportDataValidatorBundle\Rules\DynamicRuleFactory
       arguments:
           $columnMapping: '%env(VALIDATION_COLUMNS)%'
   

3. Event Listeners: Trigger events for validation results (e.g., send notifications):

   // src/EventListener/ValidationListener.php
   public function onKernelEvent(GetResponseForExceptionEvent $event)
   {
       if ($event->getThrowable() instanceof \Basilicom\ImportDataValidator\Exception\ValidationException) {
           // Handle validation failure
       }
   }