Download the PHP package ray/web-query without Composer

Ray.WebQuery

Web API access mapping framework for Ray.MediaQuery.

Installation

Note: This package builds on ray/media-query, which provides the core query infrastructure (parameter injection, logging, etc.).

Usage

Define an interface

Annotate the methods with #[WebQuery], giving each one a query ID:

Create a web query configuration file

web_query.json maps each query ID to an HTTP method and a URI template:

Install the module

MediaQueryWebModule is installed into MediaQueryBaseModule. The interfaces are registered with Queries::fromClasses():

URI template variables are filled from the method arguments and the bindings passed to WebQueryConfig (here {domain} comes from the bindings and {id} from the get() argument).

Response types

The return type of the interface method selects how the HTTP response is handled:

Mapping responses to a domain object

Instead of a raw array, a method can return typed, immutable domain objects. Give #[WebQuery] a factory (and a type) — this is the same factory mechanism ray/media-query provides for #[DbQuery], applied to HTTP responses.

The factory is resolved through the DI injector, so it can depend on domain services and apply business logic while building the object:

The decoded JSON is passed to the factory method as named arguments: each JSON key is matched to a parameter by name, unknown keys are ignored, and a missing required argument throws InvalidWebFactoryKeyException. (This is the web counterpart of media-query's positional PDO::FETCH_FUNC binding.)

type selects single object vs. list:

type defaults to 'row_list'. A 'row' method whose response is a list takes the first element; a 'row_list' method whose response is a single object wraps it into a one-element list.

You can also map straight to an entity without a factory: when the return type (or the @return array<Entity> docblock) is a class, each response is hydrated through the entity constructor.

Composing results with PostFetch

To wrap or aggregate the fetched objects into another type (totals, metadata, …), let the return type implement PostFetchInterface. Its static fromContext() receives the fetch result and returns the final object. It runs after the factory, carries no dependencies by design, and is the web analogue of media-query's PostQueryInterface (named PostFetch because a web call is a single fetch, with no multi-statement query context to span).

PostFetchContext exposes the fetch result, the original method arguments (query), and the #[WebQuery] annotation (webQuery).

Features

• Web API Queries: Execute HTTP requests via interface methods
• URI Template Support: Dynamic URL parameter binding with {param} syntax
• Multiple Response Types: JSON array, string, or PSR-7 message
• Domain Object Mapping (BDR): Map responses to typed domain objects via an injectable factory, with optional PostFetch composition
• Parameter Injection: Automatic parameter conversion and injection
• HTTP Client Integration: Built on the Guzzle HTTP client

Requirements

• PHP 8.2+
• ray/media-query ^1.0