README

PHP 的 Blackprint 引擎

在 PHP 环境中运行导出的 Blackprint。

文档

警告：此项目尚未达到稳定版本（语义版本控制，v1.0.0）
但请尝试使用它并帮助改进此项目

此引擎设计得与 engine-js 类似，一些 API 和属性将相似。

最低 PHP 版本 >= 8.1

定义 Blackprint 节点和接口

由于 PHP 支持 class-based 编程，为了使节点导入更有效和简单，此引擎将仅支持使用类声明的 Node/Interface。

但在那之前，我们需要创建一个文件夹来存储我们的 Node/Interface 逻辑。例如 /BPNode。

注册命名空间文件夹

require_once('../vendor/autoload.php');

// This can be called on different PHP libraries
\Blackprint\registerNamespace(__DIR__.'/BPNode');

// When registering with Namespace, the default root namespace is always "BPNode"
// Please name your nodes namespace along with your library name to avoid conflict with other library

定义节点和接口

在 ./BPNode 命名空间文件夹注册后，您现在可以创建一个带有您库名的文件夹。例如： ./BPNode/Example。

// file: ./BPNode/Example/Hello.php
namespace \BPNode\Example;

// The class name must match with the file name
// This will be registered as Node definition
class Hello extends \Blackprint\Node {
    // Please remember to capitalize the port name
    // Set the output port structure for your node (Optional)
    static $output = [
        'Changed'=> Types::Trigger,
        // Callable: $this->output['Changed']()

        'Output'=> Types::Number,
        // $this->output['Value'] = 246
    ];

    // Set the input port structure for your node (Optional)
    static $input = [
        'Multiply'=> Types::Number,
        // $val = $this->output['Value']
    ]

    function __construct($instance){
        // Call the parent constructor first, passing the $instance (Blackprint\Engine)
        parent::__construct($instance);

        // Set the Interface, let it empty if you want
        // to use default empty interface "setInterface()"
        $iface = $this->setInterface('BPIC/Example/Hello');
        $iface->title = "Hello"; // Set the title for debugging
    }
}

让我们也定义我们的自定义接口，这是可选的，仅在您想为其他开发者提供访问时需要。就像一个 API（应用程序编程接口）。

// same file: ./BPNode/Example/Hello.php
namespace \BPNode\Example;

// Your Interface namespace must use "BPIC" as the prefix
\Blackprint\registerInterface('BPIC/Example/Hello', HelloIFace::class);
class HelloIFace extends \Blackprint\Interfaces {
    function __construct($node){
        // Call the parent constructor first, passing the $node (Blackprint\Node)
        parent::__construct($node);
        // $this->node => Blackprint\Node

        // Define IFace's data (optional if you want to export/import data from JSON)
        // Because getter/setter feature only available on class, we will create from `class MyData`
        $this->data = new MyData($this);
        // $this->data->value === 123 (if the default value is not replaced when importing JSON)
    }

    function recalculate(){
        // Get value from input port
        $multiplyBy = $this->node->input['Multiply'];

        // Assign new value to output port
        $this->node->output['Output'] = $this->data->value * $multiplyBy;
    }
}

// Getter and setter should be changed with basic property accessor
class MyData {
    // Constructor promotion, $iface as private MyData property
    function __construct(private $iface){}

    // Draft: please design it like below after
    // this PR was merged to PHP https://github.com/php/php-src/pull/6873
    private $_value = 123;
    public $value {
        get { return $this->_value };
        set {
            $this->_value = $value;
            $this->iface->recalculate(); // Call recalculate() on HelloIFace
        };
    };

    // Current polyfill for property accessor (https://github.com/php/php-src/pull/6873)
    private $data = ["value"=> 123];
    function __get($key) {
        return $this->data[$key];
    }

    function __set($key, $val) {
        $this->data[$key] = &$val;

        if($key === 'value')
            $this->iface->recalculate($val); // Call recalculate() on HelloIFace
    }
}

创建新的引擎实例

// Create Blackprint Engine instance
$instance = new Blackprint\Engine();

// You can import nodes with JSON
// if the nodes haven't been registered, this will throw an error
$instance->importJSON(`{...}`);

// You can also create the node dynamically
$iface = $instance->createNode('Example/Hello', /* [..options..] */);

// ----

// Change the default data 'value' property
$iface->data->value = 123;

// Assign the 'Multiply' input port = 2
$iface->node->input['Multiply'] = 2;

// Get the value from 'Output' output port
echo $iface->node->output['Output']; // 246

示例

此存储库提供了一个带有 JSON 的示例，您可以使用 PHP CLI 尝试它。

# Change your working directory into empty folder first
$ git clone --depth 1 https://github.com/Blackprint/engine-php .
$ composer install
$ php ./example/init.php