PHPackages                             tiny-blocks/http-query - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. tiny-blocks/http-query

ActiveLibrary[API Development](/categories/api)

tiny-blocks/http-query
======================

Typed, framework-independent toolkit for HTTP collection queries (RSQL filtering, sorting, and offset and cursor pagination) that never touches a data store.

1.0.0(today)00MITPHPPHP ^8.5CI passing

Since Jun 26Pushed todayCompare

[ Source](https://github.com/tiny-blocks/http-query)[ Packagist](https://packagist.org/packages/tiny-blocks/http-query)[ Docs](https://github.com/tiny-blocks/http-query)[ RSS](/packages/tiny-blocks-http-query/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (8)Versions (2)Used By (0)

Http Query
==========

[](#http-query)

[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](https://github.com/tiny-blocks/http-query/blob/main/LICENSE)

- [Overview](#overview)
- [Installation](#installation)
- [How to use](#how-to-use)
    - [Declaring the query contract](#declaring-the-query-contract)
    - [Filtering with RSQL](#filtering-with-rsql)
    - [Sorting](#sorting)
    - [Offset pagination](#offset-pagination)
    - [Cursor pagination](#cursor-pagination)
    - [Building the store query](#building-the-store-query)
    - [Rendering navigation links](#rendering-navigation-links)
- [FAQ](#faq)
- [License](#license)
- [Contributing](#contributing)

Overview
--------

[](#overview)

A typed, framework-independent toolkit for querying an HTTP collection endpoint. The endpoint declares the query contract once on a `Schema`, the library parses an incoming request query string against it, and the consumer reads an already-validated result: a conjunction of comparisons for filtering, an effective sort, and a pagination view. The result renders as a JSON:API response carrying an RFC 8288 `Link` header and a body `links` object.

The library never touches a data store. It turns the query string into value objects the consumer applies to its own store, and it renders the response the consumer returns. Every computation is O(1) value-object math over the inputs the consumer supplies.

The pagination approach is a fixed decision of the endpoint, not a runtime property of a request. The public API splits into two contexts, `Cursor` and `Offset`, each complete and approach-only, with the building blocks common to both at the root. Each page renders a `self` link consistent with its own approach, so a cursor page renders a cursor `self`and an offset page renders an offset `self`.

Installation
------------

[](#installation)

```
composer require tiny-blocks/http-query
```

How to use
----------

[](#how-to-use)

There are two entry points, one per pagination approach. `TinyBlocks\HttpQuery\Offset\Criteria` reads an offset request (`page[number]`, `page[size]`) and builds offset pages, while `TinyBlocks\HttpQuery\Cursor\Criteria` reads a keyset request (`page[cursor]`, `page[size]`) and builds forward-only cursor pages. Both read the same `filter` and `sort`parameters, validate them against the schema, and expose the same `comparisons()` and `sort()` building blocks.

### Declaring the query contract

[](#declaring-the-query-contract)

`Schema` is the contract of the query an endpoint accepts. `filterable` declares a field with its permitted operators and, optionally, the permitted values and the `ValueKind` every value must match. `sortable` declares the fields the client may sort by. `defaultSort` declares the sort applied when the client sends none. `maxPerPage` and `defaultPerPage`bound the page size. The query parameter names follow JSON:API and are fixed: `filter`, `sort`, and the `page` family.

```