Oparl Client Laravel Package

Product Decisions This Supports

• Feature: civic transparency / open government data ingestion. This is a client for OParl, the German specification for open parliamentary information systems (councils, city districts, state parliaments). It lets a product surface agendas, motions, minutes, committees, persons, and papers from municipal/state RIS endpoints without writing a spec parser in-house.
• Build vs. buy: strong "buy/integrate" signal. The 1.0.0 notes describe the unglamorous but expensive parts of OParl consumption already handled: OParl object types, reference resolution between objects, list pagination with cycle detection, tolerant parsing of dates/URLs/properties, and recovery of objects from JSON. That is weeks of spec-reading and edge-case hardening we would otherwise own.
• Roadmap enabler for DACH public-sector deals. If the roadmap includes transparency portals, council-information aggregators, participatory budgeting, or "open data" commitments for German municipalities, this package is a low-cost path to a credible demo and a defensible integration story in tenders.
• Buy vs. build argument for procurement/RFP responses. We can point to a spec-conformant, mutation-tested client rather than describing a bespoke scraper — useful when a public-sector customer asks how we source and normalise their data.
• Not a differentiator by itself. This is infrastructure, not product surface. It should be scoped as an enabler behind an internal adapter layer, not as a roadmap line item.

When to Consider This Package

Consider adoption when:

• We must consume one or more OParl 1.1 endpoints (German municipal/state parliamentary systems) and the primary need is reading data, not publishing it.
• The stack is PHP 8.1+ (the release explicitly targets 8.1) and Composer-based. It is framework-agnostic, so it drops into a Laravel app cleanly — but note it is not a Laravel package: the release notes show no service provider, facade, config file, or Laravel-native HTTP/caching integration. Budget a thin wrapper (config, HTTP client injection, caching, retries, rate limiting).
• We expect messy real-world feeds: the tolerance work (byte-order marks, invalid UTF-8, loose dates/URLs, malformed property mapping, pagination cycles, rejecting list links as single objects) is exactly the hardening that matters with small municipal publishers.
• We want object-graph navigation — following references between papers, meetings, agendas, and persons — and paginated list traversal, and are willing to accept a small dependency surface to avoid building it.

Look elsewhere / defer when:

• The data source is not OParl (e.g. JSON-LD/Popolo, CKAN, or a vendor-proprietary RIS API). This package is spec-specific; it will not generalise.
• We need to serve OParl (publish our own endpoint). This is a client only.
• We need a guaranteed support contract, security-response SLA, or multiple maintainers. A 1.0.0 from a single organisational author is a real supply-chain consideration for public-sector procurement; plan for vendoring, version pinning, and a fork contingency.
• We need typed domain models we control or heavy custom mapping — expect to wrap the client's objects in our own DTOs at the boundary.
• Non-PHP services dominate the estate; don't stand up a PHP sidecar just for this.

Adoption checklist before committing: confirm OParl version coverage against the target endpoints, pin to ^1.0, wrap with our own HTTP client (timeouts, retries, caching, observability), and smoke-test against two or three live municipal endpoints rather than only fixtures.

How to Pitch It (Stakeholders)

For executives (one paragraph): German public-sector buyers increasingly expect us to ingest open parliamentary data — council agendas, motions, minutes — from their systems. This package is a mature-enough (1.0.0) PHP client for the national OParl standard that handles the awkward parts: linking records together, paging through long lists, and coping with poor-quality data from small publishers. Adopting it turns a bespoke, risky integration into a bounded, reusable component and gives us a credible answer in public-sector tenders. Cost is low; the main caveat is that it is a young, single-maintainer open-source dependency, so we should pin the version and keep an internal adapter layer so we are never locked in.

For engineering (talking points):

• Spec-level client, not a Laravel package — we add the service-provider/config/caching layer; the client stays a pure domain library and is easy to test.
• Strong on exactly the failure modes that bite in production: tolerant date/URL/property parsing, BOM and invalid-UTF-8 handling, pagination cycle detection, defensive reference handling.
• Quality signals worth citing: Psalm-precise types and mutation-testing-driven edge-case coverage — rare discipline for a package this size, and it lowers our regression risk.
• Version 1.0.0 under semver means a public API stability commitment; we can pin ^1.0 and expect breaking changes only on majors.
• Ask of the team: a thin anti-corruption layer, a spike against two live endpoints, and a documented fork/vendor plan in case upstream stalls.

Watch items to flag honestly: initial stable release with no prior assessment history, no evidence of a Laravel integration layer, and no stated deprecation or long-term support policy — so treat it as a well-built component to integrate behind our own boundary, not as a platform dependency to build directly against.