qiq/helper-sapien

Provides Qiq helpers for Sapien Request and Response objects.

2.0.0 2023-06-30 18:26 UTC

Requires

• php: ^8.1
• qiq/qiq: ^2.0
• sapien/sapien: ^1.0

Requires (Dev)

• pds/composer-script-names: ^1.0
• pds/skeleton: ^1.0
• phpstan/phpstan: ^1.0
• phpunit/phpunit: ^10.0

MIT

• Qiq Helper Sapien Contributors

• response
• request
• helper
• sapien
• qiq

README

This package provides Qiq helpers for Sapien Request and Response objects. These helpers allow you to read from a Request, and build a Response, from inside a Qiq Template.

Read more about:

• the request helper
• the response helper

Installation

This package is installable via Composer as qiq/helpers-sapien:

composer require qiq/helpers-sapien ^1.0

Request Helper

Registration

To make the request helper available inside your Template, you need to register it with the Qiq HelperLocator. You can register the helper semi-automatically ...

use Qiq\Helper\Sapien\Request;
use Qiq\Template;

/** @var Template $template */
Request::register('request', $template);

... or you can do so more manually:

use Qiq\Helper\Sapien\Request;
use Qiq\Template;

/** @var Template $template */
$template->getHelperLocator()->set('request', function () {
    return new Request();
});

By default, the helper will construct a new internal Sapien Request object of its own. If you want to pass an existing Request object, you may do so:

use Qiq\Helper\Sapien\Request;
use Qiq\Template;
use Sapien\Request as SapienRequest;

/** @var Template $template */
/** @var SapienRequest $sapienRequest */
Request::register('request', $template, $sapienRequest);

// or:
$template->getHelperLocator()->set('request', function () use ($sapienRequest) {
    return new Request($sapienRequest);
});

Usage

Once the helper is registered, you can call it using the method name you registered it under. You can use Qiq syntax ...

{{ request()->... }}

... or PHP syntax:

<?php $this->request()->... ?>

The request helper proxies to its internal Sapien Request object, making all of the Request properties available.

<p>The requested URL path is {{h request()->url->path }}</p>

To replace the proxied Request object, use the set() method:

{{ request()->set(new \Sapien\Request()) }}

To get the proxied Request object directly, use the get() method:

<?php $request = $this->request()->get(); ?>

Response Helper

Registration

To make the response helper available inside your Template, you need to register it with the Qiq HelperLocator. You can register the helper semi-automatically ...

use Qiq\Helper\Sapien\Response;
use Qiq\Template;

/** @var Template $template */
Response::register('response', $template);

... or you can do so more manually:

use Qiq\Helper\Sapien\Response;
use Qiq\Template;

/** @var Template $template */
$template->getHelperLocator()->set('response', function () {
    return new Response();
});

By default, the helper will construct a new internal Sapien Response object of its own. If you want to pass an existing Response object, you may do so:

use Qiq\Helper\Sapien\Response;
use Qiq\Template;
use Sapien\Response as SapienResponse;

/** @var Template $template */
/** @var SapienResponse $sapienResponse */
Response::register('response', $template, $sapienResponse);

// or:
$template->getHelperLocator()->set('response', function () use ($sapienResponse) {
    return new Response($sapienResponse);
});

Usage

Once the helper is registered, you can call it using the method name you registered it under. You can use Qiq syntax ...

{{ response()->... }}

... or PHP syntax:

<?php $this->response()->... ?>

The response helper proxies to its internal Sapien Repsonse object, making all of the Response methods available.

{{ response()->setVersion(...) }}
{{ response()->setCode(...) }}
{{ response()->setHeader(...) }}
{{ response()->setCookie(...) }}

To replace the proxied Response object, use the set() method:

{{ response()->set(new \Sapien\Response()) }}

To get the proxied Response object directly, use the get() method:

<?php $response = $this->response()->get(); ?>

Rendering

With typical Template usage, the code calling a Template will set the rendered template results into a Response body ...

/** @var \Qiq\Template $template */
$template->setData(...);
$template->setView(...);
$template->setLayout(...);
$content = $template();

/** @var \Sapien\Response $response */
$response->setContent($content);

... as well as setting version, status, headers, and cookies on the Response.

With this helper, you instead call render() on the helper itself, passing it the Template object to be used for content, and get back a Response object.

/** @var \Qiq\Template $template */
$template->setData(...);
$template->setView(...);
$template->setLayout(...);

/** @var \Sapien\Response $response */
$response = $template->response()->render($template);

The returned Response will be the one built up inside the template, complete with the version, status, headers, and cookies that were set in the template code.

Content Replacement

When you call response()->render(), the Response content will be whatever was rendered from a normal Template invocation.

However, you can override this behavior by calling response()->setContent(...) and setting the content directly from inside the template code. In the following example, the Response content will be "Hello, world!":

Goodbye, content!
{{ response()->setContent("Hello, world!") }}

Specialized Responses

While you can replace the internal Response using response()->set(...) and exert fine control over the replacement Response, the helper provides two convenience methods to replace the Response with specialized Sapien responses: one for FileResponse and one for JsonResponse.

To convert the Response to a FileResponse, call response()->setFile():

{{ response()->setFile('path/to/file.php') }}

The setFile() method mimics the identically-named method in FileResponse.

To convert the Response to a JsonResponse, call response()->setJson(). The following example puts all the current Template data into a JsonResponse:

{{ response()->setJson($this->getData()) }}

The setJson() method mimics the identically-named method in JsonResponse.

Note that these methods will override any output that would normally be rendered by the template code, replacing that output with the file output or JSON output, respectively.