qiq / helper-sapien
Provides Qiq helpers for Sapien Request and Response objects.
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
This package is auto-updated.
Last update: 2024-09-30 01:52:15 UTC
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:
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.