Add per-directory schema domains, cache the Opis loader, and expand examples

- Add schemas (path/domain pairs) config option, deprecating the single
  schemas_path/schema_domain pair; SchemaValidator::registerSchemaDir()
  lets the bundle register its own Examples/Schemas without colliding
  with the app's schemas_path on the shared resolver
- Reuse one SchemaLoader/SchemaResolver per SchemaValidator instance
  instead of rebuilding it on every validate() call, so long-lived
  processes (Swoole/RoadRunner) don't re-parse the same schema on every
  request; filters are still re-registered fresh per call
- Split ValidationException (domain) from HttpValidationException (HTTP
  transport); extract SchemaFilterResolver and Arrays::toObjectGraph()
- Add a multi-level nested example (order-create -> customer -> name/
  email/shippingAddress, with both relative and absolute $ref) and a
  custom $error message on the promo code filter
- Add Mermaid diagrams (request flow, schema $ref graph) and a GitHub
  Sponsors button to the docs
- Fix numerous documentation inaccuracies against the real API

Author: outcomer

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [outcomer]

CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.0.0] - 2026-09-02
+
+### Added
+- `schemas` configuration option - an array of `{path, domain}` pairs, replacing the single `schemas_path`/`schema_domain` pair so multiple schema directories (each under their own domain) can be registered at once
+- `SchemaValidator::registerSchemaDir(domain, path)` - public API to register an additional schema directory on the shared resolver after construction; used internally to register the bundle's own `Examples/Schemas/` (and its `common/` subdirectory) without colliding with the app's own `schemas_path`
+- `auto_cast_query` and `auto_cast_path` configuration options (default `true`) to control automatic numeric/boolean casting for query and path parameters independently
+- `HttpValidationException` - HTTP-transport wrapper around the domain `ValidationException`, thrown by `MapRequestResolver` when `#[MapRequest]`'s `triggerResponse` is `true`
+- `SchemaFilterResolver` - extracted service that recursively discovers `$func` filter names declared in a schema's `$filters`
+- `Helpers\Arrays::toObjectGraph()` - the array-to-stdClass-graph conversion previously inlined in `SchemaValidator`
+- Opis `$filters` example (`PromoCodeFilter`) wired into the bundled `/_examples/validation/user` route, including a custom `$error` message
+- Reusable schema `$ref` examples: `name.json`, `email.json`, `age.json` extracted from `user-create.json`
+- New `/_examples/validation/order` example route and schema set (`order-create.json`, `customer.json`, `order-item.json`, `common/address.json`, `common/country.json`) demonstrating multi-level nesting with both relative and absolute `$ref`
+- Application-level end-to-end tests exercising the bundle's example routes through a real host application kernel and router (replacing the previous bundle-only synthetic kernel tests)
+- Mermaid diagrams in the documentation: a sequence diagram of the `#[MapRequest]` request/validation/DTO flow, and a dependency graph of the example schemas' `$ref` relationships
+- `.github/FUNDING.yml` and a GitHub Sponsors button in the documentation nav bar
+
+### Changed
+- **`ValidationException` is now a plain domain exception** (`extends RuntimeException`, no longer `extends HttpException`) - HTTP concerns are handled exclusively by the new `HttpValidationException`
+- `SchemaValidator` now builds one `SchemaLoader`/`SchemaResolver` per instance and reuses it across calls, instead of a fresh `Validator` (and its underlying schema cache) on every single validation - Opis parses each schema file only once per loader, so long-lived processes (e.g. Swoole/RoadRunner workers) no longer pay the full parse cost on every request. Filters are still re-registered fresh on every call, since a filter's resolved service may not be shared
+- Headers are never auto-cast (previously could be affected by global type casting)
+
+### Deprecated
+- `schemas_path` and `schema_domain` configuration options - use `schemas` instead. They still work but emit a deprecation notice
+
+### Removed
+- Dead code in `Helpers\Arrays`: `insertInArray`, `toObject`, `groupBy`, `arrayReplaceKeys` (only `sortArrayByKeys` remains, in use)
+- Synthetic bundle-only `TestKernel` and its E2E test suite - replaced by application-level E2E tests (see Added)
+
+### Fixed
+- Multiple documentation inaccuracies found to not match the actual implementation: fabricated `ValidatedRequest`/`ValidatedPayload` API in api.md (real `ValidatedRequest` only exposes `getPayload(): Payload`, plus `getViolations()`/`hasViolations()`/`isValid()`/`getStatus()`; `ValidatedPayload` does not exist - the real class is `Payload`), `ValidatedDtoInterface` incorrectly shown as an empty marker interface, fabricated `TrimFilter`/`LowercaseFilter` classes, wrong PHP/Symfony version requirements (was showing PHP 8.4+/Symfony 8.0+; real requirement is PHP >=8.2, Symfony ^7.4|^8.0), wrong `schema_domain` default (was documented as `null`, actually `https://outcomer.dev`), a reproducible bug in a dto-injection.md example (`$query['query']`/`$headers['authorization']` array access on what are actually `object` return types from `Payload::getQuery()`/`getHeaders()`), incorrect error response `message` text (`"Validation failed"` vs actual `"Request data is invalid"`), incorrect `Examples/Model/` path (actual: `Examples/Dto/`), incomplete example routes list (missing `/api-user`, `/order` and `/info`), and incorrect namespace in README.md's quick usage snippet
+- A schema file loaded outside `schemas_path` (e.g. one of the bundle's own examples) with the same filename as a schema inside `schemas_path` would overwrite that directory's registration on the shared resolver, breaking any concurrently-used schema in `schemas_path` for the rest of the process's lifetime - fixed by giving each registered directory its own domain instead of reusing `schema_domain` for both
+- Clarified that the bundle's `/_examples/*` routes ship with their own exception listener and don't require the manual listener setup described in quick-start.md
+- Clarified that importing the bundle's `config/routes.yaml` is only needed when the host app doesn't already auto-discover attribute-routed controllers via `routing.controllers`
+
 ## [3.0.0] - 2026-03-02
 
 ### Changed

README.md

@@ -69,7 +69,7 @@ composer require outcomer/symfony-json-schema-validation
 ### Basic Usage
 
 ```php
-use Outcomer\Bundle\SymfonyJsonSchemaValidation\Attribute\MapRequest;
+use Outcomer\ValidationBundle\Attribute\MapRequest;
 
 class UserController
 {

composer.json

@@ -33,6 +33,7 @@
         "opis/json-schema": "^2.6",
         "phpunit/phpunit": "^11.0|^12.0",
         "squizlabs/php_codesniffer": "^3.13",
+        "symfony/browser-kit": "^8.1",
         "symfony/phpunit-bridge": "^7.4|^8.0",
         "symfony/var-dumper": "^7.4|^8.0"
     },

composer.lock

@@ -20,5 +20,7 @@ services:
     Outcomer\ValidationBundle\ArgumentResolver\MapRequestResolver:
         arguments:
             $schemasPath: '%outcomer_validation.schemas_path%'
+            $autoCastQuery: '%outcomer_validation.auto_cast_query%'
+            $autoCastPath: '%outcomer_validation.auto_cast_path%'
         tags:
             - { name: controller.argument_value_resolver, priority: 50 }

config/services.yaml

@@ -1,8 +1,8 @@
-import { defineConfig } from 'vitepress'
+import { withMermaid } from 'vitepress-plugin-mermaid'
 
 const REPO_NAME = 'symfony-json-schema-validation'
 
-export default defineConfig({
+export default withMermaid({
   title: 'JSON Schema Validation',
   description: 'Single Source of Truth for Symfony API contracts with JSON Schema validation and automatic OpenAPI documentation',
   base: `/${REPO_NAME}/`,
@@ -14,14 +14,19 @@ export default defineConfig({
   ignoreDeadLinks: false,
   lastUpdated: true,
 
+  vite: {
+    optimizeDeps: {
+      include: ['mermaid']
+    }
+  },
+
   themeConfig: {
     logo: { src: '/logo.svg', alt: 'Symfony JSON Schema Validation' },
 
     nav: [
       { text: 'Guide', link: '/guide/how-it-works' },
       { text: 'Examples', link: '/guide/examples' },
-      { text: 'API', link: '/guide/api' },
-      { text: 'GitHub', link: `https://github.com/outcomer/${REPO_NAME}` }
+      { text: 'API', link: '/guide/api' }
     ],
 
     sidebar: [

docs/.vitepress/config.js

@@ -17,3 +17,25 @@
 .main img:hover {
   transform: scale(1.02);
 }
+
+/* Mermaid diagram zoom */
+.mermaid-zoom-dialog {
+  width: 90vw;
+  height: 90vh;
+  max-width: none;
+  max-height: none;
+  border: none;
+  border-radius: 8px;
+  padding: 24px;
+  background: var(--vp-c-bg);
+}
+
+.mermaid-zoom-dialog::backdrop {
+  background: rgba(0, 0, 0, 0.6);
+}
+
+.mermaid-zoom-dialog svg {
+  width: 100% !important;
+  height: 100% !important;
+  cursor: zoom-out;
+}

docs/.vitepress/theme/custom.css

@@ -1,21 +1,60 @@
 import DefaultTheme from 'vitepress/theme'
 import mediumZoom from 'medium-zoom'
-import { onMounted, watch, nextTick } from 'vue'
+import { h, onMounted, watch, nextTick } from 'vue'
 import { useRoute } from 'vitepress'
 import './custom.css'
 
+function initImageZoom() {
+  mediumZoom('.main img', {
+    background: 'var(--vp-c-bg)',
+    margin: 24
+  })
+}
+
+function initMermaidZoom() {
+  document.querySelectorAll('.main .mermaid svg:not([data-zoom-bound])').forEach((svg) => {
+    svg.setAttribute('data-zoom-bound', '')
+    svg.style.cursor = 'zoom-in'
+    svg.addEventListener('click', () => openMermaidDialog(svg))
+  })
+}
+
+function openMermaidDialog(svg) {
+  const dialog = document.createElement('dialog')
+  dialog.className = 'mermaid-zoom-dialog'
+  dialog.innerHTML = svg.outerHTML
+  dialog.addEventListener('click', () => dialog.close())
+  dialog.addEventListener('close', () => dialog.remove())
+  document.body.appendChild(dialog)
+  dialog.showModal()
+}
+
 export default {
   extends: DefaultTheme,
+  Layout() {
+    return h(DefaultTheme.Layout, null, {
+      'nav-bar-content-after': () =>
+        h('iframe', {
+          src: 'https://github.com/sponsors/outcomer/button',
+          title: 'Sponsor outcomer',
+          height: '32',
+          width: '114',
+          style: 'border: 0; border-radius: 6px; margin-left: 12px;'
+        })
+    })
+  },
   setup() {
     const route = useRoute()
     const initZoom = () => {
-      mediumZoom('.main img', {
-        background: 'var(--vp-c-bg)',
-        margin: 24
-      })
+      initImageZoom()
+      initMermaidZoom()
     }
     onMounted(() => {
       initZoom()
+      new MutationObserver(() => initMermaidZoom()).observe(document.querySelector('.main') ?? document.body, {
+        childList: true,
+        subtree: true
+      })
     })
     watch(
       () => route.path,