https://github.com/rotexsoft/file-renderer
A tool for rendering PHP files that are meant to generate output.
https://github.com/rotexsoft/file-renderer
escaper escaping html php php-escaper php-escaping php-html-templating php-lightweight php-render php-renderer php-template-engine php-template-view php-templating php-view php-views php-xss template-engine templates templating views
Last synced: 4 days ago
JSON representation
A tool for rendering PHP files that are meant to generate output.
- Host: GitHub
- URL: https://github.com/rotexsoft/file-renderer
- Owner: rotexsoft
- License: bsd-3-clause
- Created: 2015-11-14T00:48:15.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2026-01-21T18:17:21.000Z (5 days ago)
- Last Synced: 2026-01-22T06:24:25.031Z (5 days ago)
- Topics: escaper, escaping, html, php, php-escaper, php-escaping, php-html-templating, php-lightweight, php-render, php-renderer, php-template-engine, php-template-view, php-templating, php-view, php-views, php-xss, template-engine, templates, templating, views
- Language: PHP
- Homepage:
- Size: 250 KB
- Stars: 5
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# PHP File Renderer
[](https://github.com/rotexsoft/file-renderer/actions?query=workflow%3A%22Run+PHP+Tests+and+Code+Quality+Tools%22)
[](https://coveralls.io/github/rotexsoft/file-renderer?branch=master)
- [PHP File Renderer](#php-file-renderer)
- [Introduction](#introduction)
- [Main Features](#main-features)
- [Acknowledgement](#acknowledgement)
- [Changelog](#changelog)
- [Contribution](#contribution)
- [Running Tests](#running-tests)
- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
- [Basic Usage](#basic-usage)
- [Getting, Setting and Unsetting View Data](#getting-setting-and-unsetting-view-data)
- [Setting View Data](#setting-view-data)
- [Getting View Data](#getting-view-data)
- [Unsetting View Data](#unsetting-view-data)
- [File paths](#file-paths)
- [Escaping Data to be Passed to Views](#escaping-data-to-be-passed-to-views)
- [Using Wild Cards in Escape Specification](#using-wild-cards-in-escape-specification)
- [Advanced Usage](#advanced-usage)
- [Implementing a Two-Step View Templating System](#implementing-a-two-step-view-templating-system)
- [Sharing Data between Layout and Page Content Views](#sharing-data-between-layout-and-page-content-views)
- [Nesting Renderers](#nesting-renderers)
## Introduction
This is a simple, elegant and flexible tool that can be used to render php files (also referred to as `Views` within this documentation)
that emit valid html output to a web-browser. It is designed to be unobtrusive; your view files can easily be used with a different
rendering or templating library. You do not need to learn any new syntax (or markup / templating language) in order to compose your
views; simply write your views in plain old php. This package also provides escaping functionality for data passed to the view file(s).
This package can easily be used by framework developers to implement the View layer of an MVC (Model-View-Controller) framework.
It can also be easily incorporated into existing frameworks.
100% Unit Test Coverage.
Users of this package are still responsible for making sure that they validate or sanitize data coming into their application(s) via user input
(eg. via html forms) with tools like [Respect\Validation](https://github.com/Respect/Validation), [Valitron](https://github.com/vlucas/valitron),
[Upload](https://github.com/brandonsavage/Upload), [Volan](https://github.com/serkin/Volan), [Sirius Validation](https://github.com/siriusphp/validation),
[Filterus](https://github.com/ircmaxell/filterus), etc.
### Main Features
* No new templating language or syntax to learn, just good old PHP is required to compose view files to be rendered.
* View file(s) in existing projects can easily be adapted for rendering via this package with very little effort.
* This package can be easily used to implement a Two-Step-View system where all your site's pages share a common layout file and the content for each page gets injected into the layout file.
* Data (variables) can be injected into the files to be rendered via an associative array whose keys will be converted to variables when rendering occurs.
* Escaping is performed on the values in the data array based on specified escape rules.
* Auto-Escaping is possible on a per instance basis of the **Renderer** class (escaping rules must be specified when instantiating a **Renderer** object for this feature to work).
## Acknowledgement
The escaping functionality in this package is implemented using the [laminas-escaper](https://docs.laminas.dev/laminas-escaper/) package.
## Changelog
[Here](https://github.com/rotexsoft/file-renderer/releases).
## Contribution
Since the goal of this package is to be lean and flexible, pull requests for significant
new features will not be accepted. Users are encouraged to extend the package with new
feature(s) in their own projects. However, bug fix and documentation enhancement
related pull requests are greatly welcomed.
### Running Tests
` ./vendor/bin/phpunit --coverage-text`
### Branching
These are the branches in this repository:
- **master:** contains code for the latest major version of this package
- **1.X:** contains code for the **1.x** version of this package
- **2.X:** contains code for the **2.x** version of this package
- **5.x:** contains code for the **5.x** version of this package
- **6.x:** contains code for the **6.x** version of this package
- **7.x:** contains code for the **7.x** version of this package
## Requirements
* PHP 8.1+
* Not currently certified for use with HHVM (unit tests failing when run in an HHVM environment).
## Installation
`composer require rotexsoft/file-renderer`
## Usage
### Basic Usage
Your main php script may look like below (let's call it `test.php` and assume it's located at the root directory of your project's folder):
`/some/path/my-project/test.php`
```php
alert('You\\'ve been XSSed!')
INPUT;
$bad_css_with_xss2 = ' display: block; " onclick="alert(\'You\\\'ve been XSSed!\'); ';
$bad_url_segment_with_xss = ' " onmouseover="alert(\'zf2\')';
$view_data = [
'paragraph_data_from_file_renderer' => 'This is a Paragraph!!',
'var_that_should_be_html_escaped' => '<script>alert("zf2");</script>',
'var_that_should_be_html_attr_escaped' => 'faketitle" onmouseover="alert(/ZF2!/);',
'var_that_should_be_css_escaped' => $bad_css_with_xss,
'another_var_that_should_be_css_escaped' => $bad_css_with_xss2,
'var_that_can_be_safely_js_escaped' => "javascript's cool",
'a_var_that_can_be_safely_js_escaped' => '563',
'a_var_that_cant_be_guaranteed_to_be_safely_js_escaped' => ' var x = \'Yo!\'; alert(x); ',
'var_that_should_be_url_escaped' => $bad_url_segment_with_xss,
];
//You MUST include the file extension in the file name (in this case `.php`)
//NOTE: that the fourth argument represents the encoding that will be used
// by the escaping functions in the renderer. This value should be the
// same as the encoding specified in the view file being rendered
// (eg. the charset value of the http-equiv meta tag in your view).
$renderer = new \Rotexsoft\FileRenderer\Renderer('view.php', $view_data, $file_paths, 'utf-8');
//You could alternately create the Renderer object like below:
//$renderer = new \Rotexsoft\FileRenderer\Renderer('./views/view.php', $view_data);
$renderer->renderToScreen(); //Render the file immediately to the screen
// The two lines below are equivalent to $renderer->renderToScreen()
$output = $renderer->renderToString(); //First capture the output of rendering
//the file in a string variable.
echo $output;
//The render*() methods will extract the elements of the data array into
//variables (array keys will be used as variable names) that will be
//available to the view file to be rendered before rendering the view.
//You can also pass the file name and data parameters to the render*() methods.
//You will have to include the path in the file name if you did not supply an
//array of file paths when your Renderer object was created.
$renderer2 = new \Rotexsoft\FileRenderer\Renderer();
$renderer2->renderToScreen('./views/view.php', $view_data);
//OR
$output = $renderer2->renderToString('./views/view.php', $view_data);
echo $output;
?>
```
`/some/path/my-project/views/view.php`
```php
<!DOCTYPE html>
<html>
<head>
<title>Escaped Entities</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<style>
<?php // CSS escaping is being applied to the variable below ?>
<?php echo $this->escapeCss($var_that_should_be_css_escaped); ?>
// Javascript escaping is being applied to the variable below
var some_string = '<?php echo $this->escapeJs($var_that_can_be_safely_js_escaped); ?>';
alert(some_string);
What framework are you using?
escapeHtml($var_that_should_be_html_escaped); ?>
User controlled CSS needs to be properly escaped!
Javascript escaping the variable in this paragraph's onclick attribute should
be safe if the variable contains basic alphanumeric characters. It will definitely
prevent XSS attacks.
Javascript escaping the variable in this paragraph's onclick attribute may lead
to Javascript syntax error(s) but will prevent XSS attacks.
User controlled CSS needs to be properly escaped!