README

PinkCrab 渲染接口的 BladeOne 提供器。

支持并测试了 PinkCrab Perique 框架的 1.4.* 版本

为什么？

BladeOne 对渲染接口的实现，允许在 PinkCrab 框架中使用 Blade。

设置

$ composer require pinkcrab/bladeone-provider

启用 BladeOne 的最简单方法是使用 BladeOne_Bootstrap 辅助类，这将完全配置 BladeOne 以作为 Renderable 实现使用。要使用此功能，只需在插件.php 文件中（针对插件）或 functions.php 文件中（针对主题）在 Perique 设置之前包含以下内容。

/**
 * Bootstrap Blade into Perique
 * 
 * @param string|array                             $views_path   The Path or paths used for the template files.
 * @param string                                   $cache_path   The path where all compiled/cached template files.
 * @param int|null                                 $blade_mode   The mode to start blade one using ( )
 * @param class_string | PinkCrab_BladeOne::class  $blade_class  The implementation of BladeOne to use
 */
BladeOne_Bootstrap::use( $views_path, $cache_path, $blade_mode, $blade_class );

// Bootstrap for Perique follows as normal.. 
$app = ( new App_Factory() )->with_wp_dice( true )
	->.....

$views_path :: 这可以是一个字符串或字符串数组。如果传递了一个数组，将使用存在的第一个路径。如果没有传递，将使用 Perique 中定义的路径。

$cache_path :: 这应该是缓存目录的字符串路径。如果没有传递，路径将被设置为 WP_CONTENT_DIR . 'uploads/compiled/blade'

$blade_mode :: 更多选项详情请 查看官方文档

$blade_class :: 这应该是类名或扩展 PinkCrab_BladeOne::class 的类的实例，这允许创建自定义组件并扩展 BladeOne。更多详情请 查看官方文档。不传递或传递无效类型将只使用默认的 PinkCrab_BladeOne。

如果缓存目录不存在，BladeOne 将为您创建它。但是，最好自己创建以确保权限等。

包含的组件

PinkCrab_BladeOne 默认包含 BladeOneHTML 特性，提供了对所有 HTML 组件的访问权。 BladeOneHTML 文档

配置 BladeOne

BladeOne 核心是一个代表 Blade 的单个类及其大多数核心功能。为了使其在从 DI 容器注入时可以进行配置，我们有一个可以扩展并添加到注册数组中的自定义类，就像任何其他 Hookable 类一样。

class My_Blade_Config extends Abstract_BladeOne_Config {

	// Services can be injected using DI as normal (with Perique)
	protected $service;
	public function __construct( Mock_Service $service ) {
		$this->service = $service;
	}

	/**	
	 * This is the only method that must be implemented
	 * @param BladeOne_Provider $provider The instance of BladeOne being used.
	 */
	public function config( BladeOne_Provider $provider ): void {
		// Use this method to configure Blade 
		// Details of methods can be found below.		
		$provider->set_compiled_extension( $this->service->get_cache_file_extension() );
		$provider->directive( 'test', [ $this->service, 'some_method' ] );
		$provider->allow_pipe( false ); // Pipe is enabled by default, unlike standard BladeOne
	}
}

您可以拥有任意数量的这些配置类，这允许您拆分任何自定义指令、全局值、别名等。

公开方法

BladeOne_Provider 类有许多方法，可用于配置底层的 BladeOne 实现。这可以通过上述 Config 类中的 config() 方法完成。

allow_pipe

/**
 * Sets if piping is enabled in templates.
 *
 * @param bool $bool
 * @return self
 */
public function allow_pipe( bool $bool = true ): self{}

调用此方法将允许您打开或关闭管道 {{ $var | esc_html }}。默认情况下，这是启用的。
详细信息: https://github.com/EFTEC/BladeOne/wiki/Template-Pipes-\(Filter\)

directive

/**
 * Register a handler for custom directives.
 *
 * @param string   $name
 * @param callable $handler
 * @return self
 */
public function directive( string $name, callable $handler ): self{}

调用此方法将允许您创建自定义指令

// Directive Example
$provider->directive('datetime', function ($expression) {
	// Return a valid PHP expression in php tags
    return "<?php echo ($expression)->format('m/d/Y H:i'); ?>";
});

<!-- Called like so in your views. -->
<p class="date">@datetime($now)</p> 

<!-- Rendered as. -->
<p class="date">01/24/2021 14:34</p>

// You will need to pass $now to your view
$class->render('path.to.view', ['now' => new DateTime()]);

详细信息: https://github.com/EFTEC/BladeOne/wiki/Methods-of-the-class#directive

别忘了我们的配置类是通过 DI 容器加载的，因此您可以将指令回调封装到类中，并使用 DI 容器注入依赖项。（见上方示例）

directive_rt

/**
 * Register a handler for custom directives at runtime only.
 *
 * @param string   $name
 * @param callable $handler
 * @return self
 */
public function directive_rt( string $name, callable $handler ): self{}

调用此方法将允许您创建自定义指令

// Directive at Run Time Example
$provider->directive_rt('datetime', function ($expression) {
	// Just print/echo the value.
	return "echo $expression->format('m/d/Y H:i');";
});

<!-- Called like so in your views. -->
<p class="date">@datetime($now)</p> 

<!-- Rendered as. -->
<p class="date">01/24/2021 14:34</p>

// You will need to pass $now to your view
$class->render('path.to.view', ['now' => new DateTime()]);

add_include

/**
 * Define a template alias
 *
 * @param string      $view  example "folder.template"
 * @param string|null $alias example "mynewop". If null then it uses the name of the template.
 * @return self
 */
public function add_include( $view, $alias = null ): self{}

这将允许您为模板设置别名，这对于全局变量（share()）来说很理想。

// Directive at Run Time Example
$provider->add_include('some.long.path.no.one.wants.to.type', 'longpath');

// This can then be used when rendering.
$class->render('longpath', ['data' => $data]);

add_alias_classes

/**
 * Define a class with a namespace
 *
 * @param string $alias_name
 * @param string $class_with_namespace
 * @return self
 */
public function add_alias_classes( $alias_name, $class_with_namespace ): self{}

这允许在模板中使用更简单、更短的类名。

$provider->add_alias_classes('MyClass', 'Namespace\\For\\Class');

<!-- Called like so in your views. -->
{{MyClass::some_method()}}
{!! MyClass::some_method() !!}
@MyClass::some_method()

share

/**
 * Adds a global variable. If <b>$var_name</b> is an array then it merges all the values.
 * <b>Example:</b>
 * <pre>
 * $this->share('variable',10.5);
 * $this->share('variable2','hello');
 * // or we could add the two variables as:
 * $this->share(['variable'=>10.5,'variable2'=>'hello']);
 * </pre>
 *
 * @param string|array<string, mixed> $var_name It is the name of the variable or it is an associative array
 * @param mixed        $value
 * @return self
 */
public function share( $var_name, $value = null ): self{}

允许创建全局变量。最佳设置方式是在上述的 Config 类中设置，因为你可以传递依赖项。

$provider->share('GLOBAL_foo', [$this->injected_dep, 'method']);

<!-- Called like so in your views. -->
{{ $GLOBAL_foo }}
@include('some.path') <!-- Where some.path uses GLOBAL_foo, ideal for dynamic components like nav menus >

当你传递值以渲染 \$foo->render('template.path', []) 时，你不需要定义 $GLOBAL_foo。

详情: https://github.com/EFTEC/BladeOne/wiki/Methods-of-the-class#share

set_mode

/**
 * Set the compile mode
 *
 * @param int $mode 
 * 	Constants
 *	BladeOne::MODE_AUTO, 
 *	BladeOne::MODE_DEBUG, 
 *	BladeOne::MODE_FAST, 
 *	BladeOne::MODE_SLOW
 * @return self
 */
	public function set_mode( int $mode ): self{}

允许设置自定义渲染模式。默认使用 MODE_AUTO。

$provider->set_mode(BladeOne::MODE_AUTO);

set_file_extension

/**
 * Set the file extension for the template files.
 * It must includes the leading dot e.g. .blade.php
 *
 * @param string $file_extension Example: .prefix.ext
 * @return self
 */
public function set_file_extension( string $file_extension ): self{}

允许你为你的 blade 模板定义一个自定义扩展。

$provider->set_file_extension('.view.php');

// Can then be used to pass my.view.php as
$foo->render('my', ['data'=>'foo']);

set_compiled_extension

/**
 * Set the file extension for the compiled files.
 * Including the leading dot for the extension is required, e.g. .bladec
 *
 * @param string $file_extension
 * @return self
 */
public function set_compiled_extension(( string $file_extension ): self{}

允许你为你的编译视图定义一个自定义扩展。

$provider->set_file_extension('.view_cache');

set_esc

/**
 * Sets the esc function.
 * 
 * @param callable(mixed):string $esc
 * @return self
 */
public function set_esc_function( callable $esc ): self {}

允许你为你的视图定义一个自定义的 esc 函数。默认设置为 esc_html。

$provider->set_esc_function('esc_attr');

魔法调用方法

BladeOne 类有大量的静态和常规方法，这些方法都可以从 BladeOne_Provider 访问。这些方法可以按照以下方式调用。

// None static
$this->view->engine()->some_method($data);

// As static 
BladeOne_Provider::some_method($data);

关于方法的完整列表，请访问 https://github.com/EFTEC/BladeOne/wiki/Methods-of-the-class

如果你想使用静态方式访问非静态方法，你可以使用

// Using the App's View method to access none static methods on the fly.
App::view()->engine()->some_method($data);

在视图中调用engine()，将返回底层渲染引擎，在本例中是 BladeOne_Provider。

当然，你可以使用 $provider->share('view_helper', [App::view(), 'engine']) 将引擎本身设置为全局变量。然后你可以在视图中使用 {$view_helper->some_method(\$data)}。

视图模型

在你的模板中，你可以通过以下任一方法渲染视图模型。

// @file /views/template.blade.php

// Using the $this->view_models() method.
{!! $this->view_modes(new View_Model('path.template', ['key' => 'value'])) !!}

// Using the directive
@viewModel(new View_Model('path.template', ['key' => 'value']))

组件

在你的模板中，你可以通过以下任一方法渲染组件。

// @file /views/template.blade.php

// Using the $this->component() method.
{!! $this->component(new SomeComponent()) !!}

// Using the directive
@component(new SomeComponent())

请注意，@component 与常规 BLADE 组件不同。BladeOne 不支持这些，这是 Perique Frameworks 的自有实现。

依赖项

• BladeOne 4.1
• BladeOne HTML 2.0

需要

• PinkCrab Perique 框架 V1.2.0 及以上版本。
• PHP7.2+

许可

MIT 许可证

https://open-source.org.cn/licenses/mit-license.html

先前 Perique 支持

• 对于 Perique 1.3.* 的支持，请使用 BladeOne_Provider 1.3.*。
• 对于 0.5.* - 1.1.* 所有版本的支持，请使用 BladeOne_Provider 1.2.*。
• 对于初始 PinkCrab 插件框架（版本 0.2.* -> 0.4.*）的支持，请使用 BladeOne_Provider 1.0.3。

变更日志

• 1.4.1 - 修复了未通过 Bootstrap::use() 传递时路径未正确假设的问题。
• 1.4.0 - 现在与 Perique 1.4.0 中的更改相匹配，不再兼容 Perique 1.3.0 及以下版本。
• 1.3.2 - 更新以匹配 Perique 1.3.0，支持组件和视图模型。放弃了 PHP 7.1 的支持。
• 1.3.1 - 在视图中直接支持 $this->component() 和 $this->view_models()，与原生的 PHP_Engine 渲染器保持一致。
• 1.3.0 - 更新以匹配 Perique 1.2.0，支持组件和视图模型。放弃了 PHP 7.1 的支持。
• 1.2.2 - 确保 BladeOne 仅在 wp 加载后加载一次。这避免了在 WP 完成加载之前注册模板全局变量的问题。参见问题 #13。
• 1.2.1 - 更新了 Readme 并将 BladeOne 和 BladeOneHTMl 升级到最新版本，现在仅与 Perique 1.*.* 兼容。
• 1.2.0 - 包含引导加载器，能够配置内部 blade 实例并使用自定义实现添加指令、组件和配置。
• 1.1.1 - 更新 composer.json 以支持 Perique 1.* 并将 github 设置为在 PR & Merge 到 Dev 时运行操作。
• 1.1.0 - 移至新的 Perique 命名。
• 1.0.3 - 默认包含 HTML 扩展。
• 1.0.2 - 将对插件框架版本 0.4.* 的内部支持提升到最新版本。