Xml Lint Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer (ensure PHP 8.1+ for compatibility):

   composer require sclable/xml-lint
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Sclable\XmlLint\XmlLintServiceProvider" --tag="config"
   

2. First Command Run a basic XML lint check on a file:

   php artisan xml:lint path/to/your/file.xml
   

   For a directory of XML files:

   php artisan xml:lint path/to/xml/directory --recursive
   

3. Quick Validation Validate against a custom XSD schema:

   php artisan xml:lint path/to/file.xml --schema=path/to/schema.xsd
   

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline Add to phpunit.xml or .github/workflows/ for pre-commit/pre-push checks:

   <php>
       <env name="XML_LINT" value="1"/>
   </php>
   

   Trigger via:

   php artisan xml:lint storage/xml --recursive --fail-on-error
   

2. Laravel Artisan Command Extend the base command for custom logic (PHP 8.4+ compatible):

   use Sclable\XmlLint\Commands\LintXmlCommand;
   
   class CustomXmlLintCommand extends LintXmlCommand {
       protected $signature = 'xml:custom-lint {path} {--schema=} {--recursive}';
   
       public function handle(): void {
           $this->lint($this->argument('path'), [
               'schema' => $this->option('schema'),
               'recursive' => $this->option('recursive'),
               'fail_on_error' => true,
           ]);
       }
   }
   

3. Event-Driven Validation Hook into file uploads (e.g., file.uploaded event) to validate XML attachments:

   use Sclable\XmlLint\Facades\XmlLint;
   
   Event::listen('file.uploaded', function ($file) {
       if ($file->getClientOriginalExtension() === 'xml') {
           XmlLint::lint($file->getRealPath())->validate();
       }
   });
   

4. API Response Validation Validate XML payloads in API routes (PHP 8.4+ features like named arguments supported):

   use Sclable\XmlLint\Facades\XmlLint;
   
   Route::post('/api/validate', function (Request $request) {
       $xml = $request->xmlPayload; // Assume XML payload
       $result = XmlLint::lint($xml)->validate();
       return response()->json($result->toArray());
   });
   

Gotchas and Tips

Common Pitfalls

1. PHP Version Compatibility

   • Issue: Package now requires PHP 8.1+ (dropped PHP 8.0 support).
   • Fix: Update your environment:

     composer require php:^8.1
     

2. Schema Validation Failures

   • Issue: Schema validation may silently fail if the XSD is malformed.
   • Fix: Always test schemas separately:

     php artisan xml:lint --schema-only path/to/schema.xsd
     

3. Recursive Directory Traversal

   • Issue: Deeply nested directories may cause performance lag.
   • Fix: Limit depth with --max-depth or exclude directories via .xml-lintignore.

4. Memory Limits

   • Issue: Large XML files may hit PHP’s memory_limit.
   • Fix: Increase limit in .env or process files in chunks:

     php artisan xml:lint --chunk-size=500 path/to/large.xml
     

Debugging Tips

• Verbose Output: Enable debug mode for detailed errors:

  php artisan xml:lint --verbose path/to/file.xml
  

• Custom Error Handling: Override the default error handler (PHP 8.4+ named args):

  XmlLint::setErrorHandler(fn ($error) => {
      Log::error("XML Lint Error: " . $error->getMessage());
      throw new \RuntimeException($error->getMessage());
  });
  

Extension Points

1. Custom Rules Extend the validator to add domain-specific rules (PHP 8.4+ compatible):

   use Sclable\XmlLint\Contracts\XmlValidator;
   
   class CustomXmlValidator implements XmlValidator {
       public function validate(string $xml, ?string $schema = null): array {
           // Add custom logic (e.g., check for required tags)
           return parent::validate($xml, $schema);
       }
   }
   

   Register in config/xml-lint.php:

   'validators' => [
       'custom' => \App\Validators\CustomXmlValidator::class,
   ],
   

2. Pre/Post-Processing Use hooks to transform XML before/after linting (PHP 8.4+ arrow functions):

   XmlLint::preProcess(fn ($xml) => str_replace('<root>', '<custom-root>', $xml));
   

3. Integration with Laravel Filesystem Use Storage::disk('xml')->lint() for cloud storage validation:

   use Sclable\XmlLint\Facades\XmlLint;
   
   $result = XmlLint::lint(storage_path('app/xml/file.xml'));