pinkcrab/perique-framework-core

PinkCrab Perique 框架的核心包。

维护者

详细信息

github.com/Pink-Crab/Perique-Framework

主页

源代码

问题

安装: 25,279

依赖者: 11

推荐者: 0

安全性: 0

星标: 5

关注者: 3

分支: 0

开放性问题: 7

2.0.4 2024-01-04 16:22 UTC

Requires

Requires (Dev)

MIT 94ae69ca2a9fca3560721e005d0513087642e274

This package is auto-updated.

Last update: 2024-09-15 01:53:54 UTC

README

logo

欢迎使用 PinkCrab Perique 插件框架的核心包，以前仅被称为 PinkCrab 插件框架。

Latest Stable Version Total Downloads License PHP Version Require GitHub contributors GitHub issues

WP5.9 [PHP7.4-8.1] Tests WP6.0 [PHP7.4-8.1] Tests WP6.1 [PHP7.4-8.3] Tests WP6.2 [PHP7.4-8.3] Tests WP6.3 [PHP7.4-8.3] Tests WP6.4 [PHP7.4-8.3] Tests

Mutation testing badge codecov Scrutinizer Code Quality Maintainability

要了解更多详细信息，请访问我们的文档。 https://perique.info

为什么选择它？

WordPress 是构建各种网站的有力工具，但由于其历史和向后兼容性承诺，使用更现代的工具进行工作往往令人沮丧。

Perique 允许创建适用于更复杂网站的插件和 MU 库。

核心包仅提供对 Hook_Loader、Registration、DI（DICE IOC 容器）、App_Config 和基本（原生）PHP_Engine 渲染视图的访问。

什么是 Perique？

Perique 是一种罕见的雪茄烟叶，产于路易斯安那州圣詹姆斯教区。这种历史悠久的烟叶在该地区生产了数百年，烟叶被取出，在压力下装入桶中，并发酵超过 12 个月。这种烟草具有强烈而辛辣的品质，可以用来大幅度增强烟草的口味、尼古丁含量和香气，而只需使用少量。这正是我们在本框架中努力实现的目标；少量的现有代码可以用来增强任何代码库，使其变得庞大、醒目和引人注目。

设置

$ composer require pinkcrab/perique-framework-core

首先，您需要创建 composer.json 和 plugin.php 文件。

plugin.php

// @file plugin.php 
<?php
     
/**
 * @wordpress-plugin
 * Plugin Name:     My Custom Plugin
 * Plugin URI:      https://my-custom-plugin.com
 * Description:     This is an example plugin for the PinkCrab Perique Framework
 * Version:         1.2.0
 * Author:          Me<me@me.com>
 * Author URI:      https://my-custom-plugin.com
 * License:         GPL-2.0+
 * License URI:     https://gnu.ac.cn/licenses/gpl-2.0.txt
 * Text Domain:     custom-plugin
 */

require_once __DIR__ . '/vendor/autoload.php';

// Creates an instance of the App_Factory with the current directory as the base path.
$factory = new PinkCrab\Perique\Application\App_Factory(__DIR__);

// Define the default rules. 
$factory->default_setup();

// Set rules and configure DI Container
$factory->di_rules(include __DIR__ . '/config/dependencies.php');

// Pass settings for App_Config
$factory->app_config( include __DIR__ . '/config/settings.php' )

// Pass all class names which should be used during registration
$factory->registration_classes(include __DIR__ . '/config/registration.php' );

// Add optional modules.
$factory->module(Some_Module::class);

// Then just boot the application.
$factory->boot();

之前（1.4.0 之前），使用 with_wp_dice() 创建应用程序，现在已弃用，但将保留一段时间以处理任何遗留代码。与 with_wp_dice() 和 default_setup() 之间的主要区别是，原先存在一个默认视图路径与基础路径相同的问题，现在已修复，默认视图路径设置为基础路径 + /views。（适用于所有 1.4 及以上版本）

自定义视图路径

如果您希望使用自定义视图路径，可以在调用 default_setup() 之前调用 $app_factory->set_base_view_path('path/to/views')。

您还可以定义一个 DI 规则，允许您将基础路径直接设置到 PHP_Engine 类。

请注意，通过这种方式，使用 APP_Config::path('views') 或 APP_Config::url('views') 将不会与您设置的路径匹配。

return array(
   PHP_Engine::class => array(
      'constructParams' => array( 'custom/view/path' ),
   ),
);

配置文件

虽然您可以将数组传递给 container_config()、app_config() 和 registration_classes()，但这些可能会变得相当大。从文件中返回它们可能会有所帮助。

这些文件可以放在任何位置，但在上述示例和我们的模板中，这三个文件都放在 /config 目录中。

dependencies.php

用于定义所有自定义 Dice 规则，有关如何使用接口和其他无法自动注入的类等更多详细信息，请参阅 Perique 文档::设置

使用完整类名至关重要，请确保包含所有需要的 use 语句。

// @file config/dependencies.php
use Some\Namespace\{Some_Interface, Some_Implementation};

return array(
   // Your custom rules
   Some_Interface::class => array(
      'instanceOf' => Some_Implementation::class
   )
);

registration.php

当应用程序启动时，所有具有钩子调用或需要被调用的类都通过此数组传递。

默认情况下，会传递可钩接中间件，因此所有实现钩接口的类都将被调用。添加自定义注册中间件将允许您在启动时将它们传递到该数组中进行初始化。

使用完整类名至关重要，请确保包含所有需要的 use 语句。

// @file config/registration.php
use Some\Namespace\Some_Controller;

return array(
   Some_Controller::class
);

有关更多详细信息，请参阅Perique 文档::注册。

settings.php

应用程序持有一个内部配置类，这可以用作定义大量常量的可注入的辅助方法。

除了常用的路径和URL值之外，您还可以设置命名空间（rest、cache）、文章类型（meta和slug）、分类（slug & term meta）、数据库表名和自定义值。

// @file config/settings.php
    
// Assumes the base directory of the plugin, is 1 level up.
$base_path  = \dirname( __DIR__, 1 );
$plugin_dir = \basename( $base_path );

return array(
   'plugin'     => array(
      'version' => '1.2.5',
   ),
   'path'       => array(
      'assets'         => $base_path . '/custom/assets',
   ),
   'url'        => array(
      'assets'         => plugins_url( $plugin_dir ) . '/custom/assets',
   ),
   'db_table' => array(
      'subscriptions' => 'some_plugin_subscribers'
   ),
   'additional' => array(
      // Custom values go here 
      'key' => 'value'   // Config::additional('key'); = value
      'other' => 'value' // $app_config->other = value
   ),
);

完整选项集可在Perique 文档::App_Config中找到。

模块和注册服务

应用程序的核心是注册过程。类可以在初始化时堆叠和执行。这允许将注册到核心WP API、触发远程API调用以及所有在加载WP核心时需要设置的其他操作。

模块

可以使用模块扩展Perique。模块是向Perique添加附加功能的一种方式，并且通常与其自己的注册中间件捆绑在一起。

通过调用$factory->module(Some_Module::class)将模块轻松添加到App_Factory，并且通常包含自己的配置和抽象类，以帮助注册过程。

请参阅Perique 文档::模块以了解更多有关创建自己的模块的详细信息，以及现有模块的精选列表。

可钩接

Loader::class加载器已被弃用，并替换为新的Hook_Loader::class。

Perique附带了一个注册中间件。`Hookable`接口和`Hookable_Middleware`对使注册任何钩子、短代码、文章类型、分类、管理页面和REST端点变得简单。任何需要处理的类，实现`Hookable`接口并创建```function register(Hook_Hook_Loader $loader): void {...}

class Some_Controller implements Hookable {
   public function register(Hook_Loader $loader): void{
      $loader->admin_action('some_action', [$this, 'some_callback']);
   }
   public function some_callback($some_arg): void {...}
}

现在当调用init钩子（优先级1）时，some_action钩子将被添加。只要请求来自wp-admin。

请参阅Perique 文档::可钩接以获取更多详细信息。

依赖注入容器

在Perique的核心中，大部分都使用了Dice DI容器的自定义版本。这允许轻松创建类和注入依赖项。

class With_Dependencies{
   private Some_Repository $repo;
   private Some_Service $service;
   private View $view;

   public function __construct(Some_Repository $repo, Some_Service $service, View $view){
      $this->repo = $repo;
      $this->service = $service;
      $this->view = $view;
   }
}

Some_Repository和Some_Service可以是具体的类、接口或抽象类。容器将解析正确的实现并将其注入到类中。对于接口和抽象类，您需要在`dependencies.php`配置文件中定义一个规则。

请参阅Perique 文档::依赖注入以获取更多详细信息。

视图

默认情况下，Perique附带一个基本的PHP视图引擎。这允许渲染模板、部分、组件和其他视图相关任务。

View类可以作为依赖项注入到类中，或从App对象静态访问。

// As a dependency
class Something{
   protected View $view;

   public function __construct(View $view){
      $this->view = $view;
   }

   public function render(): void{
      $this->view->render('some/template', ['some' => 'data']);
   }
}

// As a static call
class Something{
   public function render(): void{
      App::view()->render('some/template', ['some' => 'data']);
   }
}

所有模板路径相对于创建应用程序时定义的`view_path`。另外，`.php`扩展不是必需的，您可以选择使用`.`或`/`来分隔路径。

请访问 Perique Docs::View 以获取更多详细信息。

静态助手

App 对象有一些可以静态调用的助手方法（可以从实例或其名称调用）。

App::make(string $class, array $args = array()): object

  • @param string $class 完整命名空间类名
  • @param array<string, mixed> $args 如果需要，构造函数参数
  • @return object 对象实例
  • @throws App_Initialization_Exception 代码 4 如果应用未初始化。

make() 可以用来访问 DI 容器，以完全解析对象的依赖关系。

$emailer = App::make(Customer_Emailer::class); 
$emailer->mail(ADMIN_EMAIL, 'Some Report', $email_body); 
$emailer->send();

App::config(string $key, ...$child): mixed

  • @param string $key 要调用的配置键
  • @param ...string $child 传递的附加参数。
  • @return mixed
  • @throws App_Initialization_Exception 代码 4 如果应用未初始化。

应用启动后，您可以通过传递 App_Config 作为依赖项或使用 Apps 助手来访问 App_Config 值。

// Get post type slug
$args = ['post_type' => App::config('post_types', 'my_cpt')];

// Get current plugin version.
$version = App::config('version');

有关 App_Config 及其各种用法的更多详细信息，请查看完整文档。

App::view(): View

  • @return View
  • @throws App_Initialization_Exception 代码 4

如果您需要渲染或返回模板，可以使用 view() 助手。返回 View 类的实例，并填充了当前定义的引擎（默认使用 PHP）。

App::view()->render('signup/form', ['user' => wp_get_current_user(), 'nonce' => $nonce]);

可以在所有视图文件路径中使用点表示法。这允许以简单的方式定义用于 Win 或 Unix 文件系统的路径。

$view->render('path.to.file',['var' => 'foo']);

相当于

$view->render('path/to/file',['var' => 'foo']);

钩子

我们有一些您可以使用来扩展或修改应用工作方式的钩子。我们所有内部钩子都有 pinkcrab/pf/app/ 前缀，但我们有一个可以使用的常量类 PinkCrab\Perique\Application\Hooks:: APP_INIT_*

  • Hooks::APP_INIT_PRE_BOOT
  • Hooks::APP_INIT_PRE_REGISTRATION
  • Hooks::APP_INIT_POST_REGISTRATION
  • Hooks::APP_INIT_CONFIG_VALUES
  • Hooks::APP_INIT_REGISTRATION_CLASS_LIST
  • Hooks::APP_INIT_SET_DI_RULES
  • Hooks::COMPONENT_ALIASES
  • Hooks::MODULE_MANAGER

请参阅 Perique Docs::Hooks 以获取更多详细信息。

许可证

MIT 许可证

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

变更日志

  • 2.0.4 - 修复了在添加使用别名过滤器时，组件路径无法正确解析的错误。
  • 2.0.3 - 将 PHP8.3 添加到测试套件
  • 2.0.2 - 更新测试套件以包括 WP6.3 & 6.4
  • 2.0.1 - 更新开发依赖项并从仓库根目录中删除 plugin.php。
  • 2.0.0 -
    • 停止支持 PHP 7.2 & 7.3
    • 创建模块并从设置中删除将 Registration_Middleware 添加到应用的操作。
    • 自定义 DICE 实例，允许使用具有多个接口的 call 规则。
    • 限制在 App_Config 中设置基本和视图路径。
    • 将 wbdb_prefix 添加到 App_Config
    • 许多内部错误修复和改进。
    • 更严格的类型和返回类型。
    • 由于 infection（突变测试），测试更加严格。
  • 1.4.0 -
    • 将 set_base_view_path() 和 get_base_view_path() 添加到 App_Factory
    • 更改 App_Factory 中使用基本视图路径的方式，现在它将默认为基本路径（创建工厂时传递）+ '/views'
    • 将 get_base_path() 添加到 App_Factory，这获取插件的基路径。
    • 修复了默认 App_Config 路径设置不正确的问题，现在它们基于创建 App_Factory 时使用的基路径。
    • 将 base_view_path() 添加到 Renderable 和 PHP_Engine 实例。
    • 在 Component_Compiler 中修复了从类名添加的路径中每行两个短划线的错误。
    • 清理了各种内部对象，将许多受保护的属性替换为私有并使其最终化。
    • 将测试扩展到覆盖 Infection（突变测试），这使得测试更加稳健。
  • 1.3.1 - 为 App_Config 添加了更有意义的错误，更新了依赖项并从 PHP_Engine 中删除了未使用的函数
  • 1.3.0 - 停止测试 WP5.8 并引入 WP6.1 测试
  • 1.2.3 - 允许在视图路径中使用点表示法。
  • 1.2.2 - 修复了组件路径与基本视图路径不独立的问题。
  • 1.2.1 - 添加了过滤器，允许自定义组件路径别名。
  • 1.2.0 - 在视图和可渲染接口中添加了对组件和视图模型的支持。
  • 1.1.2 - 更新所有依赖以兼容WP6.0。
  • 1.1.1 - 优化了默认路径/URL。
  • 1.1.0 - 允许插件设置基本路径。用于回退应用配置路径/URL以及默认 PHP_Engine 模板根路径。
  • 1.0.8 - 修复了在应用初始化时默认DI规则中使用的错误接口。开发依赖项更新为使用当前PinkCrab默认值。从repo中移除了.vscode配置文件。
  • 1.0.7 - 当应用完成（通过$app->boot()方法）时，现在在DI规则中定义了WPDB。在此之前，只有在使用App_Factory创建时才会加载，并且在调用init之前不可用。
  • 1.0.6 - 通过接口添加了注入DI_Container、Hook_Loader和App_Config的方法。
  • 1.0.5 - 当导出App_Config数据时，现在正确导出元数据键的数组。同时删除了视图中不再需要的声明。
  • 1.0.4 - 在App_Config()中添加了url()、path()、additional()和namespaces()的回退值。
  • 1.0.3 - 如果在Middleware类中定义了public function set_hook_loader(Hook_Loader $loader):void{}和public function set_di_container(DI_Container $container):void{}方法，DI容器和Hook Loader现在将自动填充到Middleware中。
  • 1.0.2 - 确保只有在定义了所有内部DI规则时（esc DI容器实例）才在最终化期间构造中间件类名。
  • 1.0.1 - 允许将所有中间件作为类名传递，并通过容器构造，同时也允许传递完全实例化的类。
  • 1.0.0 - 将可注册接口重命名为可钩接口，包括内部Registerable_Middleware重命名为Hookable_Middleware。更正了错误，App::registration_classes()现在是App::registration_classes()，App_Initialization_Exception::registration_exists()现在是App_Initialization_Exception::registration_exists()。
  • 0.5.6 - 确保在App->boot()期间不将App_Config作为其DI规则集填充。这确保配置外观填充了传递的App_Config配置数组。
  • 0.5.5 - 允许通过App_Factory设置链传递注册中间件。还允许通过DI_Container作为依赖项传递。允许模块在不传递App的情况下访问DI，然后使用App::make()。
  • 0.5.4 - 移动到新repo以允许通过Packagist重命名。
  • 0.5.3 - 由于现有问题，移动到新composer名称。
  • 0.5.2 - 更新了主要命名空间从PinkCrab\Perique到PinkCrab\Perique。在composer.json中更正了包名错误，从perqiue更改为perique。
  • 0.5.1 - 删除了最后的Loader::class类型提示和引用。现在所有操作都使用Hook_Loader::class。
  • 0.5.0
    • 移动到新的Hook_Loader类型。
    • 更新App_Config（创建元子部分和将帖子类型和分类移动到简单键/值对）。
    • 向Registration_Middleware接口添加了setup()和tear_down()方法。
    • 将Collection移动到其自己的仓库。
    • 删除了未使用的服务容器接口。
  • 0.4.1 - 更新测试以反映新的Hook_Loader内部结构（测试时访问受保护的属性）。
  • 0.4.0 - 引入了新应用，包括应用工厂以帮助进行更干净的初始化。重新引入了在0.2.0中删除的Registration_Middleware。将可注册项移动到默认中间件中，该中间件在启动时自动添加。添加了一系列围绕init回调的操作，该回调运行注册过程。
  • 0.3.9 - 将Loader移动到其自己的库，所有测试和使用语句已更新。
  • 0.3.8 - 添加了缺失的 Hook_Removal 和 Loader 测试。
  • 0.3.7 - 添加了 Hook_Removal 并对 Loader 测试做了细微调整。
  • 0.3.6 - 将 remove_action() 和 remove_filter() 添加到 Loader 中
  • 0.3.5 - 将覆盖率报告添加到 gitignore 中
  • 0.3.4 - 改进了测试并连接到 codecov
  • 0.3.3 - 从服务容器中移除了对象类型提示。
  • 0.3.2 - 添加了测试并扩展了视图
  • 0.3.1 - 对 phpstan lv8 做了细微的 docblock 变更