PHPackages                             charcoal/view - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Templating & Views](/categories/templating)
4. /
5. charcoal/view

ActiveLibrary[Templating & Views](/categories/templating)

charcoal/view
=============

Charcoal View (templates rendering and tools)

v5.0.0(2y ago)01034MITPHPPHP ^7.4 || ^8.0

Since Feb 4Pushed 2y ago2 watchersCompare

[ Source](https://github.com/charcoalphp/view)[ Packagist](https://packagist.org/packages/charcoal/view)[ Docs](https://charcoal.locomotive.ca)[ RSS](/packages/charcoal-view/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (13)Versions (45)Used By (4)

Charcoal View
=============

[](#charcoal-view)

The View package provides an integration with [Mustache](https://github.com/bobthecow/mustache.php) and [Twig](https://github.com/twigphp/Twig) for templating.

Installation
------------

[](#installation)

```
composer require charcoal/view
```

For Charcoal projects, the service provider can be registered from your configuration file:

```
{
    "service_providers": {
        "charcoal/view/service-provider/view": {}
    }
}
```

Usage
-----

[](#usage)

It is a thin layer on top of various *rendering engines*, such as **mustache** or **twig** that can be used either as a *View* component with any frameworks, as PSR-7 renderer for such frameworks (such as Slim)

A `View` can be used to render any template (which can be loaded from the engine) with any object (or array, for twig) as context.

```
use Charcoal\View\Mustache\MustacheLoader;
use Charcoal\View\Mustache\MustacheEngine;
use Charcoal\View\GenericView;

$loader = new MustacheLoader([
    'base_path' => __DIR__,
    'paths'     => [
        'templates',
        'views',
    ],
]);

$engine = new MustacheEngine([
    'loader' => $loader,
]);

$view = new GenericView([
    'engine' => $engine,
]);

echo $view->render('foo/bar/template', $context);

// A template string can also be used directly, with `renderTemplate()`
$str = 'My name is {{what}}';
echo $view->renderTemplate($str, $context);
```

### Basic Usage, with service provider

[](#basic-usage-with-service-provider)

All this bootstrapping code can be avoided by using the `ViewServiceProvider`. This provider expects a `config` object

```
use Pimple\Container;
use Charcoal\View\ViewServiceProvider;

$container = new Container([
    'base_path' => __DIR__,
    'view'      => [
        'default_engine' => 'mustache',
        'paths'          => [
            'views',
            'templates',
        ],
    ],
]);
$container->register(new ViewServiceProvider());

echo $container['view']->render('foo/bar/template', $context);
```

> 👉 The default view engine, used in those examples, would be *mustache*.

### Using the Renderer, with Slim

[](#using-the-renderer-with-slim)

A view can also be implicitely used as a rendering service. Using the provided `view/renderer`, with a PSR7 framework (in this example, Slim 3):

```
use Charcoal\View\ViewServiceProvider;
use Slim\App;

$app = new App();
$container = $app->getContainer();
$container->register(new ViewServiceProvider());

$app->get('/hello/{name}', function ($request, $response, $args) {
    // This will render the "hello" template
    return $this->renderer->render($response, 'hello', $args);
});

$app->run();
```

> Just like the view, it is possible to simply register all dependencies on a Pimple container (with the `ViewServiceProvider`) to avoid all this bootstrapping code. The renderer is available as `$container['view/renderer']`.

Module components
-----------------

[](#module-components)

The basic components in the View package are:

- [**View**](#views), which provide the basic interface to all components.
- [**Engine**](#view-engines), to actually render the templates.
- [**Loader**](#loader), to load *template files*.
- [**Viewable**](#viewable-interface-and-trait), which allow any object to be rendered with a *View*.
- **Renderer**, an extra helper to use a view to render into PSR-7 request/response objects.

### Views

[](#views)

The `Charcoal\View\ViewInterface` defines all that is needed to render templates via a view engine:

- `render($templateIdent = null, $context = null)`
- `renderTemplate($templateString, $context = null)`

The abstract class `Charcoal\View\AbstractView` fully implements the `ViewInterface` and adds the methods:

#### Generic view

[](#generic-view)

As convenience, the `\Charcoal\View\GenericView` class implements the full interface by extending the `AbstractView` base class.

### View Engines

[](#view-engines)

Charcoal *views* support different templating Engines\_, which are responsible for loading the appropriate template (through a *loader*) and render a template with a given context according to its internal rules. Every view engines should implement `\Charcoal\View\EngineInterface`.

There are 3 engines available by default:

- `mustache` (**default**)
- `php`
- `twig`

#### Mustache Helpers

[](#mustache-helpers)

Mustache can be extended with the help of `helpers`. Those helpers can be set by extending `view/mustache/helpers` in the container:

```
$container->extend('view/mustache/helpers', function(array $helpers, Container $container) {
    return array_merge($helpers, [
        'my_extended_method' => function($text, LambdaHelper $lambda) {
            if (isset($helper)) {
                $text = $helper->render($text);
            }
            return customMethod($text);
        },
    ]);
});
```

**Provided helpers:**

- **Assets** helpers:
    - `purgeJs`
    - `addJs`
    - `js`
    - `addJsRequirement`
    - `jsRequirements`
    - `addCss`
    - `purgeCss`
    - `css`
    - `addCssRequirement`
    - `cssRequirements`
    - `purgeAssets`
- **Translator** helpers:
    - `_t` Translate a string with `{{#_t}}String to translate{{/_t}}`
- **Markdown** helpers:
    - `markdown` Parse markdown to HTML with `{{#markdown}}# this is a H1{{/markdown}}`

#### Twig Helpers

[](#twig-helpers)

Twig can be extended with the help of [TwigExtension](https://twig.symfony.com/doc/3.x/advanced.html#creating-an-extension). Those helpers can be set by extending `view/twig/helpers` in the container:

```
$container['my/twig/helper'] = function (Container $container): MyTwigHelper {
    return new MyTwigHelper();
};

$container->extend('view/twig/helpers', function (array $helpers, Container $container): array {
    return array_merge(
        $helpers,
        $container['my/twig/helper']->toArray(),
    );
});
```

**Provided helpers:**

- **Debug** helpers
    - `debug` function `{{ debug() }}`
    - `isDebug` function alias of `debug`
- **Translator** helpers:
    - `trans` filter a string with `{{ "String to translate"|trans }}`
    - `transChoice` filter: ```
            {{ '{0}First: %test%|{1}Second: %test%'|transChoice(0, {'%test%': 'this is a test'}) }}
            {# First: this is a test #}
            {{ '{0}First: %test%|{1}Second: %test%'|transChoice(1, {'%test%': 'this is a test'}) }}
            {# Second: this is a test #}

        ```
- **Url** helpers:
    - `baseUrl` function `{{ baseUrl() }}`
    - `siteUrl` function alias of `baseUrl`
    - `withBaseUrl` function `{{ withBaseUrl('/example/path') }}`

### Loaders

[](#loaders)

A `Loader` service is attached to every engine. Its function is to load a given template content

#### Templates

[](#templates)

Templates are simply files, stored on the filesystem, containing the main view (typically, HTML code + templating tags, but can be kind of text data).

- For the *mustache* engine, they are `.mustache` files.
- For the *php* engine, they are `.php` files.
- For the *twig* engine, they are `.twig` files.

Templates are loaded with template *loaders*. Loaders implement the `Charcoal\View\LoaderInterface` and simply tries to match an identifier (passed as argument to the `load()` method) to a file on the filesystem.

Calling `$view->render($templateIdent, $context)` will automatically use the engine's `Loader` object to find the template `$templateIdent`.

Otherwise, calling `$view->renderTemplate($templateString, $context)` expects an already-loaded template string as parameter.

### Viewable Interface and Trait

[](#viewable-interface-and-trait)

Any objects can be made renderable (viewable) by implementing the `Charcoal\View\ViewableInterface` by using the `Charcoal\View\ViewableTrait`.

The interface adds the following methods to their implementing objects:

- `setTemplateIdent($ident)`
- `templateIdent()`
- `setView($view)`
- `view()`
- `render($templateIdent = null)`
- `renderTemplate($templateString)`

#### Examples

[](#examples)

Given the following classes:

```
use \Charcoal\View\ViewableInterface;
use \Charcoal\View\ViewableTrait;

class MyObject implements ViewableInterface
{
    use ViewableTrait;

    public function world()
    {
        return 'world!';
    }
}
```

The following code:

```
$obj = new MyObject();
$obj->renderTemplate('Hello {{world}}');
```

would output: `"Hello world!"`

### View Service Provider

[](#view-service-provider)

As seen in the various examples above, it is recommended to use the `ViewServiceProvider` to set up the various dependencies, according to a `config`, on a `Pimple` container.

The Service Provider adds the following service to a container:

- `view` The base view instance.
- `view/renderer` A PSR-7 view renderer.
- `view/parsedown` A parsedown service, to render markdown into HTML.

Other services / options are:

- `view/config` View configuration options.
- `view/engine` Currently used view engine.
- `view/loader` Currently used template loader.

The `ViewServiceProvider` expects the following services / keys to be set on the container:

- `config` Application configuration. Should contain a "view" key to build the *ViewConfig* obejct.

#### The View Config

[](#the-view-config)

Most service options can be set dynamically from a configuration object (available in `$container['view/config']`).

**Example for Mustache:**

```
{
    "base_path":"/",
    "view": {
        "default_engine":"mustache",
        "paths":[
            "templates",
            "views"
        ]
    }
}
```

**Example for Twig:**

```
{
    "view": {
        "default_engine": "twig",
        "use_cache": false,
        "strict_variables": true,
        "paths": [
            "templates",
            "views"
        ]
    }
}
```

Resources
---------

[](#resources)

- [Contributing](https://github.com/charcoalphp/.github/blob/main/CONTRIBUTING.md)
- [Report issues](https://github.com/charcoalphp/charcoal/issues) and [send pull requests](https://github.com/charcoalphp/charcoal/pulls)in the [main Charcoal repository](https://github.com/charcoalphp/charcoal)

###  Health Score

36

—

LowBetter than 82% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity10

Limited adoption so far

Community22

Small or concentrated contributor base

Maturity81

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 68.4% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~74 days

Recently: every ~15 days

Total

41

Last Release

796d ago

Major Versions

0.4.0 → v2.1.22022-06-21

v2.2.3 → v3.1.02022-08-08

v3.1.8 → v4.0.02022-09-21

v4.1.0 → v5.0.02024-03-13

PHP version history (4 changes)0.1PHP >=5.5.0

0.1.5PHP >=5.6.0

0.3.4PHP >=5.6.0 || >=7.0

v2.1.2PHP ^7.4 || ^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/cfb071c0ff7ce9500c528a003a2c53124248debc3e5bf367c17f89f5e6136125?d=identicon)[mducharme](/maintainers/mducharme)

![](https://www.gravatar.com/avatar/0a4f39523b4b2837562ba0848a0327b8d340118d1ba87cb0f5d59b1d5cb6beba?d=identicon)[mcaskill](/maintainers/mcaskill)

![](https://www.gravatar.com/avatar/f3f29e38395113e2400bdd7e51bea982b17f120d4d5a53d4473b53118ee46f8d?d=identicon)[JoelAlphonso](/maintainers/JoelAlphonso)

![](https://www.gravatar.com/avatar/4229f19eecd12c2b651b6502dcc5adfba48c5770db3d2dbea55fc92c7a246b2b?d=identicon)[BeneRoch](/maintainers/BeneRoch)

---

Top Contributors

[![mducharme](https://avatars.githubusercontent.com/u/12157?v=4)](https://github.com/mducharme "mducharme (162 commits)")[![mcaskill](https://avatars.githubusercontent.com/u/29353?v=4)](https://github.com/mcaskill "mcaskill (50 commits)")[![actions-user](https://avatars.githubusercontent.com/u/65916846?v=4)](https://github.com/actions-user "actions-user (19 commits)")[![BeneRoch](https://avatars.githubusercontent.com/u/3017380?v=4)](https://github.com/BeneRoch "BeneRoch (3 commits)")[![JoelAlphonso](https://avatars.githubusercontent.com/u/10762266?v=4)](https://github.com/JoelAlphonso "JoelAlphonso (3 commits)")

---

Tags

charcoalphpread-only-repositoryviewenginetwigmustacheviewtemplatescharcoal

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/charcoal-view/health.svg)

```
[![Health](https://phpackages.com/badges/charcoal-view/health.svg)](https://phpackages.com/packages/charcoal-view)
```

###  Alternatives

[shoot/shoot

Shoot aims to make providing data to your templates more manageable

40229.9k2](/packages/shoot-shoot)[laminas/laminas-view

Fast and type safe HTML templating library with a flexible plugin system supporting multistep template composition

7526.3M230](/packages/laminas-laminas-view)[wyrihaximus/twig-view

Twig powered View for CakePHP

804.7M1](/packages/wyrihaximus-twig-view)[san-kumar/laravel-crud

Laravel CRUD generator: Generate CRUD for any db table with the crud:generate command.

564.4k](/packages/san-kumar-laravel-crud)[daycry/twig

twig for Codeigniter 4

145.1k2](/packages/daycry-twig)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)