包简介

Simple PHP View Renderer

README 文档

README

A small and easy-to-use PHP library designed for rendering native PHP views.

Highlights:

Convenient flat block system.
Setting global parameters for all views.
Support for using existing PHP functions.
Easy extensibility by adding custom functions.
Flexible layout functionality with unlimited nesting.

A guide with a detailed description in Russian language is available here.

Installation

This package requires PHP version 7.4 or later.

composer require devanych/view-renderer

Usage

The simplest example of rendering:

use Devanych\View\Renderer;

$renderer = new Renderer('/path/to/root/directory/of/views');

$content = $renderer->render('path/to/view/file', [
    'variableName' => 'the value of a variable of any type',
]);

echo $content;

The render() method takes as its first argument the path to the view file, which must be relative to the directory passed to the constructor when the object was created. The second argument passes an array of parameters (name => value) that will be converted to variables inside the view.

$renderer->render('post/show', [
    'post' => $posts->get($id),
]);

in the view:

<h1><?=$post->getName();?></h1>

The view file can be with or without an extension, if the file extension is not specified, .php will be substituted by default. The default extension can be changed by passing it to the constructor as the second argument.

$renderer = new Renderer('/path/to/root/directory/of/views', 'tpl');

Within layouts and views, a renderer instance is available at $this.

<title><?=$this->renderBlock('title');?></title>

Blocks

The block(), beginBlock(), and endBlock() methods allow you to create content blocks in your view. The content of blocks is saved for use anywhere in the view, as well as in any parent layout. The method renderBlock() renders the stored content of the block.

Layout code:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title><?=$this->renderBlock('title');?></title>
    <?=$this->renderBlock('meta');?>
</head>
<body class="app">
    <?=$this->renderBlock('content');?>
</body>
</html>

View code:

<?php

declare(strict_types=1);

/** @var Devanych\View\Renderer $this */

$this->layout('layouts/main');
$this->block('title', 'Page Title');
?>

<p>Page Content</p>

<?php $this->beginBlock('meta');?>
    <meta name="description" content="Page Description">
<?php $this->endBlock();?>

Rendering result:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Page Title</title>
    <meta name="description" content="Page Description">
</head>
<body class="app">
    <p>Page Content</p>
</body>
</html>

Blocks can't be nested, but you can render one block inside another.

<!-- Allowed -->
<?php $this->beginBlock('parent');?>
    <!--  ...  -->
    <?=$this->renderBlock('children');?>
    <!--  ...  -->
<?php $this->endBlock();?>

<!-- Disallowed -->
<?php $this->beginBlock('parent');?>
    <!--  ...  -->
    <?php $this->beginBlock('children');?>
        <!--  ...  -->
    <?php $this->endBlock();?>
    <!--  ...  -->
<?php $this->endBlock();?>

Note that content is a reserved block name. it renders the content of the view and child layouts. If you try to create a block named content, the \RuntimeExceptionexception is thrown.

When calling the renderBlock() method with the name of a nonexistent block, the renderBlock() method returns an empty string, so no additional methods are needed to check the existence of the block. The second argument in renderBlock() can pass the default value, which will be substituted if the block with the specified name does not exist.

<!-- Output the block content, if it exists  -->
<?php if ($name = $this->renderBlock('name')): ?>
    <h1><?=$name;?></h1>
<?php endif;?>

<!-- Output the default content if the block doesn't exist  -->
<?=$this->renderBlock('title', 'Default Title');?>
<!-- or using a different block  -->
<?=$this->renderBlock('title', $this->renderBlock('default-title'));?>

Layouts

Layouts are a special type of representations that are very convenient to use for rendering repetitive parts (header, footer, sidebar, etc.). This package allows you to build layout chains with unlimited nesting. Layout inheritance is set in the file of the view or child layout by the layout() method.

Parent layout code (layouts/main):

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title><?=$this->renderBlock('title');?></title>
</head>
<body class="app">
    <?=$this->renderBlock('content');?>
</body>
</html>

Child layout code (layouts/columns):

<?php

declare(strict_types=1);

/** @var Devanych\View\Renderer $this */

$this->layout('layouts/main');
?>
<main class="main">
    <?=$this->renderBlock('content');?>
</main>
<aside class="sidebar">
    <!-- Sidebar Code  -->
</aside>

View code (site/page):

<?php

declare(strict_types=1);

/** @var Devanych\View\Renderer $this */

$this->layout('layouts/columns');
$this->block('title', 'Page Title');
?>

<p>Page Content</p>

Rendering the view:

$renderer->render('site/page', [/* params */]);

Rendering result:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Page Title</title>
</head>
<body class="app">
    <main class="main">
        <p>Page Content</p>
    </main>
    <aside class="sidebar">
        <!-- Sidebar Code  -->
    </aside>
</body>
</html>

If you just need to render the child layout file from the parent layout, you can use the render() method.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title><?=$this->renderBlock('title');?></title>
</head>
<body class="app">
    <?=$this->render('layouts/_header.php')?>
		
    <?=$this->renderBlock('content');?>
		
    <?=$this->render('layouts/_footer.php', [
        'parameter' => 'value'
    ])?>
</body>
</html>

Rendering result:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Page Title</title>
</head>
<body class="app">
    <header>Header</header>
    <p>Page Content</p>
    <footer>Footer</footer>
</body>
</html>

Extensions

The extension functionality allows you to add your own functions and use them inside layouts and views. To add a function, you need to create your own class that implements the Devanych\View\Extension\ExtensionInterface interface. The interface contains only one method that returns an array whose keys are the names of added functions, and the values can be any possible variants of the callable type.

interface ExtensionInterface
{
    /**
     * Returns an array of functions as `function name` => `function callback`.
     *
     * @return array<string, callable>
     */
    public function getFunctions(): array;
}

This package contains a single extension Devanych\View\Extension\AssetExtension, which simplifies the connection of assets (scripts, styles, fonts, etc.) and adds a timestamp to the file. To add an extension, use the addExtension() method.

$extension = new AssetExtension('/path/to/assets', 'https://examle.com/assets', true);
$renderer->addExtension($extension);

// Result: 'https://examle.com/assets/css/style.css?v=1601742615'
$renderer->asset('css/style.css');

Global parameters

Using the addGlobal() method, you can add global parameters that will be available in all views and layouts.

// The `$variableName` variable will now be available inside files.
$renderer->addGlobal( 'variableName', 'the value of a variable of any type');

Adding a variable with the same name again will cause a \RuntimeException, but you can change the value of the global variable for a specific view by passing a parameter with the same name when rendering the view, or simply assigning it in the view itself.

// For all views and layouts, the value is `$author` will equal `Boby`
$renderer->addGlobal( 'author', 'Boby');

// Only for the `blog/page` view, the value is `$author` will be equal to `John`
$renderer->render('blog/page', [
    'author' => 'John',
]);
// or assign a value in the view
$author = 'John';

Escaping

To prevent the output of potentially dangerous HTML code, the renderer contains the esc() method, which escapes special characters, converts them to the corresponding HTML entities.

// Result: '&lt;script&gt;alert(123);&lt;/script&gt;'
$renderer->esc('<script>alert(123);</script>');
// Equivalently to: `htmlspecialchars($content, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8', true)`

This method is for convenience, but you can also use the original htmlspecialchars() function, as all existing PHP functions are available in views and layouts.

devanych/view-renderer 适用场景与选型建议

devanych/view-renderer 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 3.31k 次下载、GitHub Stars 达 15，最近一次更新时间为 2020 年 10 月 05 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「php」「templates」「views」「view-renderer」「native-php-templates」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 devanych/view-renderer 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 devanych/view-renderer 我们能提供哪些服务？

定制开发 / 二次开发

基于 devanych/view-renderer 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发