Oparl Client Laravel Package

Technical Evaluation

Architecture fit. sitepark/oparl-php-client is a domain-specific API client for OParl, the German standard for open parliamentary information systems (councils, committees, papers, meetings). It is not a Laravel package in the strict sense — no service provider, no facade, no config publishing — so it sits in the "framework-agnostic PHP library" tier of our dependency graph. That is acceptable but means we own the wiring (container binding, config, caching, HTTP transport) ourselves rather than inheriting Laravel conventions.

The 1.0.0 surface is coherent for a first stable cut: an OParl client, typed object models for OParl object types, list pagination, references, query parameters, and JSON round-tripping (serialize/restore with serializable references). For a TPM this is the correct shape — a read-oriented client that maps a remote standard into typed PHP objects with a serialization boundary suitable for caching or queue payloads.

Integration feasibility. Feasible. It is a plain Composer dependency requiring PHP 8.1, which aligns with modern Laravel baselines. The hard prerequisite is not technical but organisational: a reachable OParl endpoint (typically a municipal or state parliament system) and a business reason to ingest that data. If no such endpoint is in scope, this package has no home in our stack.

Notable integration friction points to plan for:

• Transport is ours. The package parses and models, but HTTP concerns (timeouts, retries, TLS, proxies, rate limits, auth if the endpoint requires it) likely need a configured PSR-18/PSR-7 client rather than Laravel's Http facade. We must confirm and, if needed, build an adapter so we do not end up with two HTTP stacks.
• Serialization boundary. The "restore objects from JSON and make references serializable" feature is the one we should lean on hardest — it lets us cache OParl payloads and hydrate models later without re-fetching. Worth designing around from day one.
• No Laravel-level ergonomics. Expect to write a small service provider, a config file for base URLs, and a cache strategy. Budget roughly a day, not a sprint.

Technical risk. Moderate and mostly bounded:

• Tolerant parsing is a double-edged sword. "Parse dates and URLs tolerantly", "map properties tolerantly", and "tolerate byte order mark and invalid UTF-8" all increase the chance we silently accept malformed upstream data. Good for resilience against real-world OParl deployments; risky for data quality. We need validation at our boundary — do not treat "the client accepted it" as "the data is correct". The BOM/UTF-8 fix in particular hints upstream feeds are messy.
• Pagination. A dedicated pagination-cycle detection fix ("detect pagination cycles by requested URLs only") tells us OParl list traversal is genuinely tricky: large result sets, possibly looping links. This is a correctness and liveness risk — an unbounded traversal can hang a worker. We must impose our own page cap and time budget regardless of what the client does.
• Reference resolution. References are lazy and serializable. The unknown is whether dereferencing a reference triggers a network call, and whether that is depth-limited. A reference graph walk over a large parliament dataset can explode into hundreds of requests. This is the single biggest architectural unknown and must be resolved before design sign-off.
• Error semantics. Tolerant parsing plus a 1.0.0 with no long track record means the exception taxonomy is unproven. We need to know what is thrown on transport failure, schema violation, and unresolvable reference — "tolerant" should not mean "swallows errors".
• Maturity. 1.0.0 with a single maintainer (sitepark-becker) and a first stable release. The engineering signals are genuinely good — Psalm-precise types, mutation testing, infection tooling, commit hooks, changelog — which suggests a disciplined maintainer. But bus factor is 1 and production battle-testing is unknown.

Key questions. Before committing:

1. Does reference dereferencing perform network I/O implicitly, and is there a depth or count limit we can configure?
2. What is the exception contract — which failures throw, which are logged/swallowed, and can we hook into them?
3. Is pagination bounded, or must the caller enforce a page ceiling?
4. What HTTP client abstraction does it require, and can it be bound to a Laravel-idiomatic adapter?
5. Is there a documented OParl schema version target (1.0 vs 1.1), and how strict is conformance?
6. What is the maintainer's support commitment and release cadence post-1.0.0?
7. Are the "tolerant" behaviours configurable — can we opt into strict mode for our own data-quality guarantees?

Integration Approach

Stack fit. Compatible with our PHP 8.1+ / Laravel baseline. Composer-installable, PSR-friendly, framework-agnostic — which is a mild negative for Laravel ergonomics but a positive for lock-in and testability. It occupies a narrow niche: it is the right tool if and only if we are consuming OParl data. It is not a general HTTP or RPC client and should not be evaluated as one.

Recommended placement: a dedicated Opal/Parliament integration module behind a thin internal interface (e.g. ParliamentDataSource) so the rest of the app never imports the package's types directly. This keeps the vendor surface to one adapter layer and makes the "what if we swap clients" question cheap.

Migration path. There is no prior state — this is a greenfield adoption at 1.0.0, not an upgrade. Two realistic paths:

• Pilot (recommended). Wrap one OParl endpoint — ideally a mid-sized municipality with a well-behaved feed — behind the adapter, ingest into a local schema, and run for 4–6 weeks to observe real-world parsing failures, latency, and pagination behaviour. No production dependency until the pilot clears.
• Direct adoption. Only justified if an OParl integration is already on the committed roadmap with a hard deadline. Even then, the reference-dereferencing question must be answered first.

Because this is 1.0.0, we should pin an exact version in composer.json (e.g. 1.0.0 rather than ^1.0) for the pilot, and only widen to a caret constraint after the first minor release proves the API is stable.

Compatibility. PHP 8.1 is explicitly supported, matching current Laravel LTS requirements. Watch two things: (a) whether the package declares a Laravel version constraint at all — it almost certainly does not, so composer will not warn us on a Laravel major upgrade; (b) the HTTP client dependency, which is the most likely source of version conflicts with our existing stack. Resolve the dependency graph in a throwaway branch before committing.

Sequencing. A pragmatic order:

1. Spike (2–3 days): install, point at a real OParl endpoint, exercise object fetch, list pagination, and reference resolution. Answer the seven key questions above.
2. Prove the serialization boundary: fetch → serialize → cache → restore, and confirm round-tripping is lossless enough for our needs.
3. Build the adapter layer and container bindings; add a config file for base URLs, page caps, and timeouts.
4. Instrument pagination and reference resolution with explicit budgets; wire failures into our existing logging/alerting.
5. Run the pilot; publish findings; then decide on widening the version constraint and promoting to production.

Operational Impact

Maintenance. Low-to-moderate and mostly ours, not theirs. The package itself should be stable post-1.0.0; the maintenance burden is the adapter, the cache strategy, and the retry/budget logic we layer on top. The upstream project shows healthy hygiene — Psalm types, mutation testing, changelog, commit hooks, dev files excluded from the package — which reduces the odds of nasty surprises. Counterweight: a single maintainer, so we should be prepared to fork or vendor the package if it goes quiet. Given the small surface, forking is realistic rather than catastrophic.

Support. Community/open-source with no commercial backing identified. That is acceptable for a read-only data client in a non-critical path, but it means we are our own first line of support. Any OParl-consuming feature we build on this becomes an internal capability we must staff, document, and own — do not frame this as "buy a library, get support".

Scaling. The scaling dimension that matters is not throughput but request amplification. Every list traversal is N pages, and every reference dereference is potentially another request. A naive "load the meeting, load its papers, load each paper" pattern is quadratic-ish over HTTP and will hit municipal endpoints that are not sized for it. Mitigations to build in from the start:

• Local persistence of fetched OParl objects keyed by their OParl URL, so references resolve from cache by default.
• Explicit page ceiling and wall-clock budget per traversal.
• Batch/queued ingestion (Laravel jobs) rather than synchronous traversal in a web request — OParl endpoints are frequently slow and occasionally rate-limited.
• Off-peak scheduled sync rather than on-demand fetch for anything user-facing.

With those in place, scale is bounded by the upstream endpoint, which is the real constraint, not by the client.

Failure modes. Enumerated for the runbook:

• Silent data corruption — tolerant date/URL/property parsing accepts malformed upstream values. Most insidious failure mode; mitigate with validation and a periodic data-quality report rather than trusting the client's tolerance.
• Encoding noise — BOMs and invalid UTF-8 are tolerated, but downstream consumers (search indexes, exports) may not be. Normalise on ingest.
• Unbounded traversal — pagination cycles are detected by requested URLs only, which is narrower than general cycle detection. Enforce our own cap.
• Reference explosion — implicit dereferencing causing request storms or recursion. Must be depth- and count-limited.
• Endpoint unavailability — municipal systems go down and are slow. Serve from cache; degrade gracefully.
• Schema drift — an upstream OParl deployment changes or upgrades its schema version. Tolerant parsing may mask this until a field is silently absent. Alert on unexpected parse outcomes.
• Abandonment — single maintainer stops responding. Fork-and-maintain, which is cheap here.

Ramp-up. For a Laravel-fluent engineer: 1–2 days to be productive, since the package is small and the model is a straightforward object graph. The real ramp-up cost is OParl domain literacy — understanding Body, Meeting, Paper, AgendaItem, reference semantics, and list pagination — which is 3–5 days of reading the spec and poking a real endpoint. Budget a week for the first engineer to reach confident productivity, and capture that learning in the adapter layer's documentation so the second engineer does not repeat it. The absence of Laravel idioms (no facade, no published config) means onboarding material has to be written by us, not inherited from the package.

Recommendation. Green-light a bounded pilot, not a committed integration. The engineering quality signals are good, the scope is narrow and honest, and the 1.0.0 feature set covers the OParl essentials with evidence of real-world hardening (BOM handling, pagination cycles, mutation-tested edge cases). The blockers to a full commitment are the unanswered questions around reference dereferencing, error semantics, and pagination bounds — all resolvable in a short spike. Pin the version, isolate behind an adapter, enforce our own request and page budgets, and treat parsing tolerance as a resilience feature to be paired with our own validation, not a substitute for it.