Afterbuy Sdk Symfony Bundle Laravel Package

Getting Started

• Install with composer require <vendor>/<package> and publish the config (php artisan vendor:publish --tag=<package>-config) if you need to point at custom schema locations. The package's value is validating XML against XSD, so the first thing to locate is the directory of .xsd files it ships and the config key that maps a document type to a schema path.
• Read the schema directory before reading the source. The public API is thin; the behavioural contract lives in the XSDs. Anything the schema accepts or rejects is effectively your app's validation rule, and schema changes ship as package changes.
• First use case: validate an inbound XML payload (webhook, upload, partner feed) before you persist or dispatch it. Wrap it in a FormRequest or a dedicated Rule object so validation failures surface as normal 422s rather than exceptions bubbling out of a job.
• If you only need well-formedness (parseable XML), plain DOMDocument::loadXML is enough — reach for this package when you actually need structural/type conformance to a schema.

Implementation Patterns

• Validate at the boundary, then trust internally. Run schema validation once at ingestion, persist the raw XML alongside the parsed model, and skip re-validating on every read. Re-validating in a loop is the most common performance complaint.
• Rule objects over inline calls. Implement Illuminate\Contracts\Validation\ValidationRule and delegate to the package, so validation composes with required, file, max: and the rest of the validator. Map library errors into $fail() messages with line numbers retained.
• Separate "well-formed" from "schema-valid". Two-stage checks give far better operator feedback: malformed XML is a client error, schema-invalid XML is a business error with a specific field path. Don't collapse them into one message.
• Queue heavy validation. Large documents plus remote schema resolution can take seconds. Validate in a job with a failed() handler that quarantines the payload and notifies, rather than blocking a request cycle.
• Fixture-driven tests. Keep a tests/fixtures/xml/ directory with one valid document and one deliberately broken document per supported document type. These are also your regression harness for package upgrades — see the notes below on 1.0.2.
• Version your schemas. If you accept several document versions, put the version in config as a map ('invoice.v2' => storage_path('schemas/invoice-v2.xsd')) rather than branching in code. Adding a version becomes a config change.

Gotchas and Tips

• Namespaces are the sharp edge, and 1.0.2 moves it. That release removed targetNamespace from the shipped XSD. Consequence: documents that are namespace-qualified (i.e. most real-world documents — <inv:Invoice xmlns:inv="...">) may no longer validate against the shipped schema, while previously rejected unqualified documents now pass. This is a behavioural change in a patch release, which is unfortunate. If you upgraded, re-run your fixture suite immediately and pin the version in composer.json until you've confirmed which of the two shapes your upstream partners actually send.
• If you need namespace-strict validation, supply your own XSD. Point the config at your own schema with an explicit targetNamespace and elementFormDefault="qualified". That is also the cleaner long-term fix: don't depend on the package's bundled schema for a contract you care about.
• Schema imports and includes resolve relative to the XSD's own location. Moving or publishing schemas breaks xs:import silently-ish — you get a validation failure on a valid document, not an obvious "schema not found". Test with a schema that has an import if you customise paths.
• Guard against XXE. Ensure LIBXML_NONET is set and external entity loading is disabled when parsing untrusted input. If the package wraps DOMDocument, check that it isn't calling loadXML on user input without those flags.
• Error noise. libxml emits cascading errors from one root cause; deduplicate by line/schema path before surfacing to users or you'll get twenty-line error blobs. Capture libxml_use_internal_errors(true) and clear the buffer — leaked libxml error state between validations in the same request is a classic phantom-bug source.
• Watch the PHP/libxml version matrix in CI. XSD 1.1 features are not supported by libxml at all; if a schema uses assertions or xs:alternative, validation will fail for reasons that have nothing to do with your document.