Xmlvalid Symfony Laravel Package

Getting Started

• Install/update the Laravel package as usual, then verify the resolved SDK version:

  composer show xmlvalid/xmlvalid-php
  

  v1.2.0 of this package requires xmlvalid/xmlvalid-php 1.2+. If Composer still resolves 1.1.x, force the dependency update before testing:

  composer update xmlvalid/xmlvalid-php --with-dependencies
  

• Look first at the package service provider, published config, and the XmlvalidMockResponse test helper. The release is primarily about response shape parity: mock responses now include:
  • path on each error — where the business rule fired
  • sha256 on the result
  • engine on the result
• First practical use case: validate an XML document and assert the enriched result shape in a feature test. Use XmlvalidMockResponse so tests receive the same payload shape as the live API, then assert errors.*.path, sha256, and engine are present and readable through the SDK models.

Implementation Patterns

• Normalize validation results into an application DTO/action instead of passing SDK models around:

  final class XmlValidationResult
  {
      public function __construct(
          public bool $valid,
          public array $errors,   // each with path, message, etc.
          public ?string $sha256,
          public ?string $engine,
      ) {}
  }
  

  This keeps your app resilient if future SDK versions add more response metadata.
• Use path for diagnostics and user-facing messages. Since it identifies where a business rule fired, map it to your domain object/field when possible rather than showing raw paths to end users.
• Persist sha256 and engine when validation results matter for audit, caching, or deduplication. A useful cache key is often sha256 + engine + validation profile, assuming the contract confirms sha256 represents the validated document content.
• In tests, use XmlvalidMockResponse consistently for success and failure cases. Prefer partial assertions such as assertJsonPath('errors.0.path', ...) over full JSON snapshots, because response metadata is now richer and likely to evolve.
• Add CI coverage that explicitly checks the SDK version. A simple guard prevents accidentally testing against xmlvalid/xmlvalid-php 1.1, where the models will not read the new fields even if a mock returns them.
• If the package exposes config for HTTP client behavior, set timeouts/retries there rather than wrapping calls ad hoc. Keep external validation calls behind a small service or action so they are easy to fake and monitor.

Gotchas and Tips

• SDK 1.2 is required, not optional. XmlvalidMockResponse may now answer with path, sha256, and engine, but older xmlvalid/xmlvalid-php models will ignore those fields. If your app sees missing values, check composer show xmlvalid/xmlvalid-php first.
• Expect test breakage if you assert exact response arrays, field counts, or snapshots. New keys are additive, but strict equality assertions will fail. Use subset assertions and update snapshots deliberately.
• Treat path as nullable/optional in defensive code. It is present on each error where a business rule fired, but global/document-level failures may not have a meaningful path depending on the API contract.
• Do not hard-code engine as an enum unless the API contract guarantees the values. Log it, store it, and use it for traceability; avoid branching on exact strings without a documented set.
• sha256 is useful for audit and deduplication, but verify what content is hashed before relying on it for security-sensitive comparisons. Normalize XML consistently before hashing or caching.
• When debugging mismatches between tests and production, log the raw response body alongside the SDK model output. Missing fields can come from either the mock shape or the SDK model hydration layer.
• Prefer package extension points—published config, client binding, custom mock response subclasses—over editing vendor files. The release is additive, but the SDK version coupling makes dependency hygiene part of the integration.