Download the PHP package ray/media-query without Composer

Ray.MediaQuery

Media access mapping framework

日本語 (Japanese)

Overview

Ray.QueryModule makes a query to an external media such as a database or Web API with a function object to be injected.

Motivation

• You can have a clear boundary between domain layer (usage code) and infrastructure layer (injected function) in code.
• Execution objects are generated automatically so you do not need to write procedural code for execution.
• Since usage codes are indifferent to the actual state of external media, storage can be changed later. Easy parallel development and stabbing.

Composer install

$ composer require ray/media-query

Getting Started

Define the interface for media access.

DB

Specify the SQL ID with the attribute DbQuery.

Web API

Specify the Web request ID with the attribute WebQuery.

Create the web api path list file as web_query.json.

Module

MediaQueryModule binds the execution of SQL and Web API requests to an interface by setting DbQueryConfig or WebQueryConfig or both.

Note: MediaQueryModule requires AuraSqlModule to be installed.

Request object injection

You do not need to prepare an implementation class. It is generated and injected from the interface.

DbQuery

When the method is called, the SQL specified by the ID is bound with the method argument and executed. For example, if the ID is todo_item, the todo_item.sql SQL statement is bound with ['id => $id] and executed.

• If the result is a row(array<string, scalar>), specify type:'row'. The type is not necessary for row_list(array<int, array<string, scalar>>).
• SQL files can contain multiple SQL statements. In that case, the return value is the last line of the SELECT.

Entity

When the return value of a method is an entity class, the result of the SQL execution is hydrated.

Use CameCaseTrait to convert a property to camelCase.

If the entity has a constructor, the constructor will be called with the fetched data.

Entity factory

To create an entity with a factory class, specify the factory class in the factory attribute.

The factory method of the factory class is called with the fetched data. You can also change the entity depending on the data.

If the factory method is not static, the factory class dependency resolution is performed.

Web API

• Customization such as header for authentication is done by binding Guzzle's ClinetInterface.

Parameters

DateTime

You can pass a value object as a parameter. For example, you can specify a DateTimeInterface object like this.

The value will be converted to a date formatted string at SQL execution time or Web API request time.

If no value is passed, the bound current time will be injected. This eliminates the need to hard-code NOW() inside SQL and pass the current time every time.

Test clock

When testing, you can also use a single time binding for the DateTimeInterface, as shown below.

VO

If a value object other than DateTime is passed, the return value of the toScalar() method that implements the ToScalar interface or the __toString() method will be the argument.

Parameter Injection

Note that the default value of null for the value object argument is never used in SQL. If no value is passed, the scalar value of the value object injected with the parameter type will be used instead of null.

`

Pagenation

The #[Pager] annotation allows paging of SELECT queries.

You can get the number of pages with count(), and you can get the page object with array access by page number. Pages is a SQL lazy execution object.

The number of items per page is specified by perPage, but for dynamic values, specify a string with the name of the argument representing the number of pages as follows

Use @return to specify hydration to the entity class.

SqlQuery

SqlQuery executes SQL by specifying the ID of the SQL file. It is used when detailed implementations with an implementation class.

Get* Method

To get the SELECT result, use get* method depending on the result you want to get.

Ray.MediaQuery contains the Ray.AuraSqlModule. If you need more lower layer operations, you can use Aura.Sql's Query Builder or Aura.Sql which extends PDO. doctrine/dbal is also available.

Profiler

Media accesses are logged by a logger. By default, a memory logger is bound to be used for testing.

Implement your own MediaQueryLoggerInterface and run You can also implement your own MediaQueryLoggerInterface to benchmark each media query and log it with the injected PSR logger.

Annotations / Attributes

You can use either doctrine annotations or PHP8 attributes can both be used. The next two are the same.

Testing Ray.MediaQuery

Here's how to install Ray.MediaQuery from the source and run the unit tests and demos.