包简介

Allows you to create custom HTML elements to render more complex template parts

README 文档

README

Allows you to create custom HTML elements to render more complex template parts with a simpler HTML representation

Requirements

PHP 8.1+

Installation

composer require lordsimal/custom-html-elements

Usage

This is an example representation of a custom HTML element you want to use:

<c-youtube src="RLdsCL4RDf8"/>

So this would appear in a HTML output like this:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <title>Example Page</title>
    <meta name="author" content="Kevin Pfeifer">
</head>
<body> 
    <c-youtube src="RLdsCL4RDf8"/>
</body>
</html>

To render this custom HTML element you need to do this:

$htmlOutput = ''; // This variable represents what is shown above
$engine = new \LordSimal\CustomHtmlElements\TagEngine::getInstance([
    'tag_directories' => [
        __DIR__.DIRECTORY_SEPARATOR.'Tags'.DIRECTORY_SEPARATOR,
        __DIR__.DIRECTORY_SEPARATOR.'OtherTagsFolder'.DIRECTORY_SEPARATOR,
    ],
]);
echo $engine->parse($htmlOutput);

The element logic can be placed in e.g. Tags/Youtube.php or OtherTagsFolder/Youtube.php:

<?php
namespace App\Tags;

use LordSimal\CustomHtmlElements\CustomTag;

class Youtube extends CustomTag 
{
    public static string $tag = 'c-youtube';

    public function render(): string
    {
        return <<< HTML
        <iframe width="560" height="315" 
            src="https://www.youtube.com/embed/{$this->src}" 
            allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" 
            allowfullscreen>
        </iframe>
HTML;
    }
}

As you can see the main 2 parts are the

public static string $tag = 'c-youtube';

which defines what HTML tag is represented by this class and the render() method.

Inside the render() method you have access to all HTML attributes which you pass onto your element.

So e.g.

<c-button type="primary" text="Click me" url="/something/stupid" />

would be accessible inside the Button class via

class Button extends CustomTag
{
    public static string $tag = 'c-button';

    public function render(): string
    {
        $classes = ['c-button'];
        if ($this->type == 'primary') {
            $classes[] = 'c-button--primary';
        }
        $classes = implode(' ', $classes);
        return <<< HTML
            <a href="$this->url" class="$classes">$this->text</a>
HTML;
    }
}

Accessing the inner content

You may want to create custom HTML elements like

<c-github>Inner Content</c-github>

To access the Inner Content text inside your class you simply have to call $this->innerContent like so

class Github extends CustomTag
{
    public static string $tag = 'c-github';

    public function render(): string
    {
        return <<< HTML
            $this->innerContent
HTML;
    }
}

Self closing elements

By default every custom HTML element can be used either way:

<c-youtube src="RLdsCL4RDf8"></c-youtube>

or

<c-youtube src="RLdsCL4RDf8" />

both are rendered the same way.

Rendering nested custom HTML elements

By default, this library renders nested custom HTML elements. So you don't need to worry about that.

Disabling custom HTML elements

You have 2 ways how you can disable custom HTML elements:

Disable all occurence of custom HTML elements

You can add the attributes

public bool $disabled = true;

to your Custom HTML Element class.

Disable only specific occurence of custom HTML elements

You can add the attribute disabled, then it will not be rendered.

<c-youtube src="RLdsCL4RDf8" disabled />

More examples?

See all the different TagEngine Tests

Limitations

Since everything gets parsed via regex, there are some limitations related to how regex works.

E.g. if you have an enormous amount of HTML which needs to be parsed at once, it may be possible that the regex fails to parse the HTML correctly (e.g. PREG_BACKTRACK_LIMIT_ERROR)

In this case you will have to find another way to encapsulate your HTML elements in PHP.

Acknowledgements

This library is inspired by the following packages

lordsimal/custom-html-elements 适用场景与选型建议

lordsimal/custom-html-elements 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 2.22k 次下载、GitHub Stars 达 4，最近一次更新时间为 2023 年 10 月 13 日，在 PHP 生态内属于活跃度较高的组件。

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

围绕 lordsimal/custom-html-elements 我们能提供哪些服务？

定制开发 / 二次开发

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

BUG 修复 & 性能优化

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

项目外包 & 长期维护

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

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

lordsimal/custom-html-elements

包简介