Introduction
An immutable, fluent URL builder/parser for the apiable request-query grammar, available as a TypeScript package and a mirrored PHP package.
Flex Url is a zero-dependency URL builder/parser for the Laravel Apiable request-query grammar — filter, sort, include, fields, appends, page and q. It ships as two mirrored packages from a single monorepo:
flex-urlon npm — the TypeScript core, ESM + CJS, full type declarations.open-southeners/flex-urlon Packagist — the PHP mirror, framework-free.
Method names and wire semantics are kept identical between the two on purpose, so a Vue/Inertia frontend and a Laravel backend (or a server-rendered Livewire table) speak the exact same URL grammar without translating between two different mental models.
import {url} from 'flex-url';
url('https://api.example.com/posts')
.filter('status', 'published')
.sort('-created_at')
.include('tags', 'author')
.page(1)
.toString();
// => "https://api.example.com/posts?filter[status]=published&sort=-created_at&include=tags,author&page[number]=1"use function flex_url;
flex_url('https://api.example.com/posts')
->filter('status', 'published')
->sort('-created_at')
->include('tags', 'author')
->page(1)
->toString();
// => "https://api.example.com/posts?filter[status]=published&sort=-created_at&include=tags,author&page[number]=1"Features
Immutable — every builder call returns a new instance; nothing is ever mutated in place.
Parse = build — constructing from a URL hydrates the exact same state a builder produces, so a URL can be round-tripped through the builder and read back with
getFilter(),getSorts(),getPage(), and friends.Full URL fidelity — pathname, port, hash, and any existing query params are preserved.
Matches apiable's own encoding idiom — brackets and commas are raw on the wire, individual values are percent-encoded. See Encoding Contract.
Typed schemas (TypeScript) — narrow
filter()/sort()/include()/fields()/append()to a specific endpoint's allowed vocabulary at compile time, generated straight from apiable'sapiable:typesexporter.Framework-free (PHP) — no Laravel/Illuminate runtime dependency.
toQuery()/toRequestUri()give you what you need to dispatch an in-kernel sub-request yourself.Cross-language test parity — both implementations are tested against the same shared JSON fixtures, so they can't silently drift apart.
Requirements
TypeScript (flex-url)
PHP (open-southeners/flex-url)
Runtime
Node.js 24.x or 26.x
PHP 8.2+
Dependencies
None
None
Quick start
Then head to the Installation guide, or straight to Quick Start for a tour of the builder API.
Last updated