Oai Pmh Laravel Package

Product Decisions This Supports

• Interoperability roadmap: "get harvested, not just crawled." OAI-PMH is the mandatory exposure protocol for a long list of aggregators and catalogues — Europeana, DPLA, BASE, OpenAIRE, national libraries, union catalogues, and most university repository networks. This package turns "we should be harvestable by X" from a multi-sprint protocol project into a single-contract integration, which is the difference between putting aggregation on the roadmap and leaving it perpetually in the backlog.
• Build vs. buy, decided cheaply. The protocol layer is the part nobody on the team wants to own: six verbs, eight error codes, resumption-token pagination with cursor/completeListSize, set hierarchy with descendant inclusion, three deleted-record modes, and two date granularities. That is a well-specified, low-differentiation surface with a compliance test suite behind it. Buy it; spend the engineering budget on metadata quality, which is where the actual product differentiation lives.
• Feature scoping for metadata exposure. The single OaiRepositoryContract (get, getRecordForId, getEarliestDatestamp) is a clean product boundary: the package owns the protocol, your team owns what a record is. That makes "which metadata formats do we expose, and in what fidelity?" a product conversation (Dublin Core as the floor, EAD/MARC/MODS/qualified DC as differentiators) rather than an engineering archaeology exercise.
• Incremental harvesting as a supported product promise. getEarliestDatestamp plus second-level granularity plus deleted-record modes means downstream partners can do delta harvests and stay in sync. That is a retention and partnership argument, not just a technical checkbox — it is what lets you tell an aggregator "you can harvest us nightly and not re-pull 200k records."
• Archive/library/digital-collection verticals. The provenance matters for roadmap credibility: extracted from Anton, an archive-management system, built with the Gosteli Archive. If the product roadmap includes archives, special collections, institutional repositories, or museum catalogues, this is domain-validated rather than a generic protocol shim.
• Low-cost bet, reversible. composer require, publishable config, seven overridable Blade views. Worst case you spend days, not quarters, and the contract interface means your record-fetching logic stays yours if you ever swap the transport.

When to Consider This Package

Adopt when:

• You are the data provider, not the harvester. This is a server implementation only — if you need to pull from other OAI-PMH endpoints, look elsewhere (or pair it with a client library).
• You have (or are about to have) a Laravel app on PHP 8.2–8.4 and Laravel 10–12. Older Laravel or PHP 8.1 and below is out of the support matrix.
• You have a credible "records" concept that maps to the three-method contract — an Eloquent model, a search index, a document store. If your records are spread across five systems with no unifying accessor, budget for that adapter first; that is the real work.
• A named downstream consumer is asking for OAI-PMH (an aggregator, a partner institution, a funder mandate, a national portal). Protocol work is much easier to justify with a counterparty attached.
• You want standards conformance you can point at, rather than a bespoke JSON/XML feed you have to re-argue every time a partner onboards.

Look elsewhere or defer when:

• You need OAI-PMH as a client/harvester. Out of scope here.
• You need a full repository platform (persistence, admin UI, DOI minting, embargoes, preservation). This is the protocol edge, not the repository.
• Your metadata is already served by a mature repository product (DSpace, Fedora, Islandora, Omeka, Samvera). Adding a second OAI-PMH endpoint alongside an existing compliant one creates duplicate, divergent harvest surfaces — a genuine support and reconciliation cost.
• Your team runs polyglot services. This is Laravel-native; adopting it implies the data-provider endpoint lives in (or next to) the Laravel app. If your records live behind a non-PHP service, you will be building a thin Laravel shell purely to host the protocol — viable, but factor in that shell's operational cost.
• You need heavy custom protocol behaviour — non-standard verbs, authenticated/embargoed harvesting, per-consumer views with access control. OAI-PMH has no auth model; if your product requires gated harvesting, you need an extension design (and probably a conversation about whether OAI-PMH is the right protocol at all).
• v1.0.0 maturity risk is unacceptable. First stable release, single maintainer lineage. Fine for a public read-only endpoint; think harder if this is a contractual deliverable with an SLA. Mitigation: it is a small surface, and the XSD-conformance suite plus the contract interface mean the exit cost is low.

Questions worth resolving before commitment: whether resumption tokens are stateless or persisted (affects horizontal scaling), how set membership is computed (query-time vs. materialised), and whether custom metadata formats can be added without forking the Blade views.

How to Pitch It (Stakeholders)

To executives: This is a small, reversible dependency that makes our content discoverable through the channels our peers and funders already use. Aggregators like Europeana, DPLA, and national library portals require OAI-PMH — a standardised harvesting protocol — and we currently cannot be harvested. Rather than fund a protocol build, we adopt a Laravel-native implementation that is already extracted from a production archive system and validated against the official specification schema. The cost is measured in days, the interface we must implement is three methods, and the strategic payoff is presence in external catalogues we do not have to build or maintain ourselves.

To engineering: The package owns the protocol surface — all six verbs, all eight error codes, resumption-token pagination with cursor and completeListSize, set hierarchy with descendant inclusion, deleted-record modes, and day/second date granularity — and ships an XSD-conformance suite covering every verb and error response. You implement OaiRepositoryContract: get, getRecordForId, getEarliestDatestamp. That is the entire coupling point; your record-fetching logic, models, and indexes are untouched and remain swappable. Config and seven Blade views are publishable, so XML output is customisable without forking. Supported on PHP 8.2–8.4 and Laravel 10–12. It is a server only — harvesting stays out of scope. Provenance is production: extracted from Anton, built with the Gosteli Archive.

One-line framing: We implement three methods; the package implements a standard we would otherwise spend a quarter getting subtly wrong.