Download the PHP package wiserwebsolutions/laravel-lobbyist without Composer

Laravel Lobbyist

Search, monitor, and summarize legislative activity — bills, votes, and elected representatives — across the United States, through a single driver-agnostic API.

This is the core package. It ships the contract, the driver manager, and the normalized data objects, but no data source of its own. You install one or more driver packages that plug in behind it:

Installation

Publish the config if you want to change the default driver:

Usage

Lobbyist::state($abbr) resolves the driver registered for that state, falling back to the default driver (legiscan) when no state-specific driver is installed. The returned object is scoped to that state.

Which operations a driver supports varies by source — check first (see below).

Chambers

Every driver also exposes its state's legislative chambers as a fluent, chamber-scoped entry point. Each chamber delegates back to the driver's bills()/votes()/legislators() and filters the result to that chamber — so you never have to call ->byChamber() yourself:

(A chamber's own representatives() always means "the legislators belonging to this chamber" — for the Senate ChamberContext that's the same members $pa->senators() returns; only the driver-level representatives() means "House members specifically".)

chambers() defaults to [House, Senate] for every driver (bicameral, which covers all currently shipped drivers). Calling a chamber-scoped method the driver doesn't back throws UnsupportedOperationException, exactly like calling it directly on the driver.

Each chamber also exposes its computed political lean(), based on the party affiliation of its representatives:

The label compares the two major parties' share of the two-party total (independents/others are excluded from the comparison, but included in detail()): a spread under 10 points is "Neutral", 10–30 points is "Slight {Party}", and over 30 points is "Strong {Party}". lean() throws UnsupportedOperationException under the same condition as this chamber's representatives(), since it's built from that same data.

Sessions

Every driver also exposes the most recent legislative session directly:

Throws UnsupportedOperationException if the driver doesn't implement SessionProvider, or a LobbyistException if it does but reports no sessions at all.

Capabilities

Not every data source supports every operation — an RSS feed can list current bills but cannot look up an arbitrary bill by id. Drivers therefore implement only the capabilities they can back, and you can check before calling:

Calling an unsupported lookup throws UnsupportedOperationException.

Bill text

billText($id) returns the bill's current (most recent) text version; billTextHistory($id) returns every version (introduced, amended, enrolled, etc.) as a BillTextCollection:

content is null whenever a driver only has a link to the document (e.g. a PDF) rather than its fetched bytes — fetch url yourself in that case. BillTextCollection::latest() picks the most recent entry by date, which is what billText() is typically built from.

Every Bill a driver returns also carries the same version data directly, no driver call required — a mapper embeds it while building the Bill in the first place:

Bill::text()/texts() are pure reads of whatever the mapper already attached — they never perform I/O themselves, so toString() throws unless a driver already populated content (which billText($id) does, fetching just the latest version's bytes). toHTML()/toPDF() throw only when that particular version doesn't have a link in that format at all.

Data objects

Drivers return normalized spatie/laravel-data objects — Session, Bill, Vote, Legislator — regardless of source. States are typed via the StateEnum, chambers via Chamber, parties via Party.

These objects are provider-agnostic: each derives its typed properties from a documented, normalized meta array (see the class docblocks for the recognized keys) and is unaware of any specific data source. It is a driver's job to map its raw payload into that shape — so adding a new provider never requires touching core. Drivers typically keep the raw payload under meta['raw'] so nothing is lost.

Writing a state driver

1. Create a package that requires wiserwebsolutions/laravel-lobbyist.
2. Write a driver extending WiserWebSolutions\Lobbyist\Support\AbstractDriver and implementing the provider/lookup interfaces you can actually back. AbstractDriver derives capabilities()/supports() from those interfaces automatically and throws UnsupportedOperationException for lookups you omit. It also gives you chambers() for free, defaulting to [House, Senate]; override the protected $chambers property if your state has a unicameral legislature. session() and each chamber's lean() are also free, built on top of sessions()/legislators() — implement SessionProvider/LegislatorProvider and both work automatically.
3. Map your source's raw payloads into the core DTOs' normalized meta shape — keep this in a mapper class in your package (see LegiscanMapper / PalegisMapper for reference). Core never learns about your source.

4. Register it from your service provider's boot(), order-independently:

5. Verify compliance with the shipped WiserWebSolutions\Lobbyist\Testing\AssertsDriverContract trait.

Testing

License

MIT © Daniel Wiser