francerz/webapp-render-utils

Web App rendering utils.

Maintainers

Details

github.com/francerz/php-webapp-render-utils

Source

Issues

Installs: 143

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 1

Forks: 0

Open Issues: 0

v0.1.5 2022-11-14 21:57 UTC

Requires

Requires (Dev)

ISC 8a23ec2450d208f194618552bde2a1cca45aec7d

This package is auto-updated.

Last update: 2024-04-15 01:05:46 UTC

README

This library allows to create PSR-7 ResponseInterface objects for given content.

Supported renderers are:

  • Redirect
  • String
  • JSON
  • CSV
  • File
  • cURL response
  • View

Contents

View Renderer

The most complex and powerful renderer is View, which allows to catch outputs from a PHP file into a PSR-7 ResponseInterface object.

Catches any type of output like generated PDFs, Spreadsheets or HTML documents.

Rendering a view

$renderer->renderView('/home/index', [
    'title' => 'Hello World!',
    'paragraph' => 'Hello everyone.'
]);

View file /home/index.php:

<html>
    <head>
        <title><?=$title?></title>
    </head>
    <body>
        <h1><?=$title?></h1>
        <p><?=$paragraph?></p>
    </body>
</html>

Renderer result:

<html>
    <head>
        <title>Hello World!</title>
    </head>
    <body>
        <h1>Hello World!</h1>
        <p>Hello everyone.</p>
    </body>
</html>

Including subviews

Include file /includes/head.php.

<head>
    <title><?=$title?></title>
</head>

View file /home/index.php

<html>
    <?=$view->include('includes/head')=?>
    <body>
        <h1><?=$title?></h1>
        <p><?=$paragraph?></p>
    </body>
</html>

Using layouts

Layout file /layouts/main.php:

<html>
    <head>
        <title><?=$title?></title>
    </head>
    <body>
        <?=$layout->section('content')?>
    </body>
</html>

View file /home/index.php:

<?=$layout = $view->loadLayout('/layouts/main')?>
<?=$layout->startSection('content')?>
<h1><?=$title?></h1>
<p><?=$paragraph?</p>
<?=$layout->endSection()?>

NOTE
When using Layouts, everything outside a section will be ignored, therefore will not be renderered.

Library API

Class Renderer

class Renderer
{
    public function __construct(
        ResponseFactoryInterface $responseFactory,
        ?StreamFactoryInterface $streamFactory = null
    );

    public function renderRedirect(
        $location,
        int $code = StatusCodeInterface::STATUS_FOUND,
        ?ResponseInterface $response = null
    ): ResponseInterface;

    public function render(
        $content,
        $contentType = 'text/plain',
        ?ResponseInterface $response = null
    ): ResponseInterface;

    public function renderJson(
        $data,
        ?ResponseInterface $response = null
    ): ResponseInterface;

    public function renderCsv(
        array $data,
        $filename = 'file.csv',
        ?CsvOptions $options = null,
        ?ResponseInterface $response = null
    ): ResponseInterface;

    public function renderFile(
        string $filepath,
        ?string $filename = null,
        bool $attachment = false,
        ?ResponseInterface $response = null
    ): ResponseInterface;

    public function renderCurlResponse(
        CurlHandle $curl,
        string $responseBody,
        ?ResponseInterface $response = null
    ): ResponseInterface;

    public function setViewsBasePath(?string $basepath);

    public function renderView(
        string $viewpath,
        array $data = [],
        ?ResponseInterface $response = null
    ): ResponseInterface;
}

Class View

An instance of this class is automatically created when $renderer->renderView() method is invoked. Instance is passed into views with name $view.

class View
{
    /**
     * Renders a header directly into the view.
     * 
     * @param string $header Defines the header name or name and content.
     * @param string|string[] $content Defines the content of given header.
     */
    public function header(string $header, string|string[] $content = []);

    /**
     * Embeds another view inside the current view.
     * 
     * All `$view` variables are passed automatically into included view.
     * 
     * @param string $path Path to embed view.
     * @param mixed[] $vars Additional vars to send to embed view.
     */
    public function include(string $path, array $vars = []);

    /**
     * Loads a layout to current view.
     * 
     * By loading a layout only content inside a section will be renderer in
     * final output.
     * 
     * All `$view` variables are passsed automatically into layout.
     * 
     * @param string $path Path to layout view.
     * @param mixed[] $vars Additional vars to send to layout.
     * 
     * @return Layout
     */
    public function loadLayout(string $path, array $vars = []);
}

Class Layout

An object of this class is created when $view->loadLayout() method is invoked.

This class contains methods to allow main view file to define sections.

class Layout
{
    /**
     * This method starts a section block.
     */
    public function startSection(string $sectionName);

    /**
     * This method ends a section block.
     * 
     * This methods ends section by the last started.
     */
    public function endSection();
}

Class LayoutView

An object of this classe is passed into Layout Views as $layout.

class LayoutView
{
    /**
     * Embeds section into the layout.
     */
    public function section(string $sectionName);
}