README

Magento 2 的注解

在扩展开发过程中，我们经常遇到一些 插件 或 观察者 只应在某些 Magento 版本和 Magento 版本中执行的情况。为了解决这个问题，我们通常注入 \Magento\Framework\App\ProductMetadataInterface，然后对版本和版本进行额外的检查。

Magento 2 的注解 将帮助解决这个问题，并提供灵活的条件组合配置。

要求

• PHP >= 7.1
• Magento 任何版本 >= 2.3.0

如何安装

通过 composer 安装（推荐）

在 Magento 2 根目录下运行以下命令

composer require fom/module-annotations
php bin/magento setup:upgrade
php bin/magento setup:static-content:deploy

开发者指南

在 Magento 2 中，所有使用 \Magento\Framework\App\ProductMetadataInterface 检查当前版本和版本的 插件 和 观察者 仍然会继续实例化、执行和使用内存和处理器。 Magento 2 的注解 模块使用一种优化的方法，对于当前版本和版本不应执行的插件和观察者将在构建插件和观察者配置的阶段被禁用。这意味着是否执行插件或观察者的检查将仅在一次进行，即在缓存构建阶段，这将略微减少堆栈跟踪，这反过来又应该对性能产生积极影响。

使用 属性（PHP >= 8.0）或 Doctrine Annotations（PHP >= 7.1）来配置 插件 和 观察者。

Magento 2 的注解 提供了两个属性类

• Fom\Annotations\Attribute\Platform
• Fom\Annotations\Attribute\Operator

Fom\Annotations\Attribute\Platform

该属性用于描述 Magento 的版本、版本和比较运算符。此属性是可重复的，可以多次添加到类中。

参数

• edition - string，包含 Magento 版本。可接受值

  • 'any' - 对应于常量 Platform::EDITION_ANY
  • 'Community' - 对应于常量 Platform::EDITION_COMMUNITY
  • 'Commerce' - 对应于常量 Platform::EDITION_COMMERCE
  • 'B2B' - 对应于常量 Platform::EDITION_B2B

  如果传递空值，检查将按照Platform::EDITION_ANY的值进行。

• version - string，任何正确的版本，将传递给version_compare()函数。

• comparison - string，任何由version_compare()函数接受的合法比较运算符。

  • '<' - 对应于常量Platform::COMPARISON_LESS_THAN
  • '<=' - 对应于常量Platform::COMPARISON_LESS_THAN_OR_EQUAL
  • '>' - 对应于常量Platform::COMPARISON_GREATER_THAN
  • '>=' - 对应于常量Platform::COMPARISON_GREATER_THAN_OR_EQUAL
  • '=' - 对应于常量Platform::COMPARISON_EQUAL
  • '!=' - 对应于常量Platform::COMPARISON_NOT_EQUAL

  如果没有传递值，默认使用Platform::COMPARISON_GREATER_THAN_OR_EQUAL。

Fom\Annotations\Attribute\Operator

如果类的属性Platform被添加多次，此属性用于汇总从Platform列表中获取的结果。此属性是可选的，并且只能应用于类一次。

参数

• operator - string，用于将结果逻辑上求和为AND和OR。

  • 'and' - 对应于常量Operator::OPERATOR_AND
  • 'or' - 对应于常量Operator::OPERATOR_OR

  默认使用Operator::OPERATOR_AND。

示例

在示例中我们将演示观察者，但插件使用的是完全相同的声明。

使用PHP8属性的观察者

让我们禁用低于2.4.4版本的任何 Magento 版本的观察者。

<?php

declare(strict_types=1);

namespace Vendor\Module\Observer;

use Magento\Framework\Event\Observer;
use Magento\Framework\Event\ObserverInterface;

#[
    \Fom\Annotations\Attribute\Platform(
        edition: \Fom\Annotations\Attribute\Platform::EDITION_ANY,
        version: '2.4.4',
        comparison: \Fom\Annotations\Attribute\Platform::COMPARISON_LESS_THAN
    ),
    \Fom\Annotations\Attribute\Operator(operator: \Fom\Annotations\Attribute\Operator::OPERATOR_AND)
]
class SomeKindOfActionObserver implements ObserverInterface
{
    public function execute(Observer $observer): void
    {
        // ...
    }
}

我们还可以导入我们的属性以使用简短的类名。

<?php

declare(strict_types=1);

namespace Vendor\Module\Observer;

use Fom\Annotations\Attribute\Operator;
use Fom\Annotations\Attribute\Platform;
use Magento\Framework\Event\Observer;
use Magento\Framework\Event\ObserverInterface;

#[
    Platform(
        edition: Platform::EDITION_ANY,
        version: '2.4.4',
        comparison: Platform::COMPARISON_LESS_THAN
    ),
    Operator(operator: Operator::OPERATOR_AND)
]
class SomeKindOfActionObserver implements ObserverInterface
{
    public function execute(Observer $observer): void
    {
        // ...
    }
}

使用 Doctrine 注释（PHP < 8.0）的观察者

让我们做同样的事情，但使用 docblock 部分以允许使用较旧的 PHP 版本。

<?php

declare(strict_types=1);

namespace Vendor\Module\Observer;

use Magento\Framework\Event\Observer;
use Magento\Framework\Event\ObserverInterface;

/**
 * @\Fom\Annotations\Attribute\Platform(
 *     edition = \Fom\Annotations\Attribute\Platform::EDITION_ANY,
 *     version = "2.4.4",
 *     comparison = \Fom\Annotations\Attribute\Platform::COMPARISON_LESS_THAN
 * )
 * @\Fom\Annotations\Attribute\Operator(operator = \Fom\Annotations\Attribute\Operator::OPERATOR_AND)
 */
class SomeKindOfActionObserver implements ObserverInterface
{
    public function execute(Observer $observer): void
    {
        // ...
    }
}

我们仍然可以导入我们的属性以使用简短的类名。

<?php

declare(strict_types=1);

namespace Vendor\Module\Observer;

use Fom\Annotations\Attribute\Operator;
use Fom\Annotations\Attribute\Platform;
use Magento\Framework\Event\Observer;
use Magento\Framework\Event\ObserverInterface;

/**
 * @Platform(
 *     edition = Platform::EDITION_ANY,
 *     version = "2.4.4",
 *     comparison = Platform::COMPARISON_LESS_THAN
 * )
 * @Operator(operator = Operator::OPERATOR_AND)
 */
class SomeKindOfActionObserver implements ObserverInterface
{
    public function execute(Observer $observer): void
    {
        // ...
    }
}

使用组合声明的观察者，PHP 8 属性和 Doctrine 注释，允许此模块与不同的 PHP 版本一起使用。

我们必须使用一行 PHP8 属性符号。在这种情况下，我们的 PHP8 属性将被解释为较旧 PHP 版本的注释，因为它以#开头。

<?php

declare(strict_types=1);

namespace Vendor\Module\Observer;

use Fom\Annotations\Attribute\Operator;
use Fom\Annotations\Attribute\Platform;
use Magento\Framework\Event\Observer;
use Magento\Framework\Event\ObserverInterface;

/**
 * @Platform(
 *     edition = Platform::EDITION_ANY,
 *     version = "2.4.4",
 *     comparison = Platform::COMPARISON_LESS_THAN
 * )
 * @Operator(operator = Operator::OPERATOR_AND)
 */
#[Platform(edition: Platform::EDITION_ANY, version: '2.4.4', comparison: Platform::COMPARISON_LESS_THAN), Operator(operator: Operator::OPERATOR_AND)]
class SomeKindOfActionObserver implements ObserverInterface
{
    public function execute(Observer $observer): void
    {
        // ...
    }
}

不使用Operator属性示例

由于默认情况下Operator 等于 Operator::OPERATOR_AND，在以下情况下我们可以省略它：

仅使用一个平台条件

<?php

declare(strict_types=1);

namespace Vendor\Module\Observer;

use Fom\Annotations\Attribute\Operator;
use Fom\Annotations\Attribute\Platform;
use Magento\Framework\Event\Observer;
use Magento\Framework\Event\ObserverInterface;

#[
    Platform(
        edition: Platform::EDITION_ANY,
        version: '2.4.4',
        comparison: Platform::COMPARISON_LESS_THAN
    )
]
class SomeKindOfActionObserver implements ObserverInterface
{
    public function execute(Observer $observer): void
    {
        // ...
    }
}

使用多个平台条件，但所有条件必须同时满足

<?php

declare(strict_types=1);

namespace Vendor\Module\Observer;

use Fom\Annotations\Attribute\Platform;
use Magento\Framework\Event\Observer;
use Magento\Framework\Event\ObserverInterface;

#[
    Platform(
        edition: Platform::EDITION_COMMERCE,
        version: '2.4.4',
        comparison: Platform::COMPARISON_LESS_THAN
    ),
    Platform(
        edition: Platform::EDITION_B2B,
        version: '2.4.4',
        comparison: Platform::COMPARISON_LESS_THAN
    )
]
class SomeKindOfActionObserver implements ObserverInterface
{
    public function execute(Observer $observer): void
    {
        // ...
    }
}

Operator::OPERATOR_AND 的使用示例

在罕见的情况下，当插件或观察者必须同时在不同的版本和版本上工作时，我们可能需要使用特定的条件，在这种情况下，我们可以描述几个必要的平台条件，并使用 Operator::OPERATOR_AND 进行总结。在这种情况下，如果至少满足一个条件，我们的观察者或插件将被执行。

在下面的示例中，观察者将在 Magento Community Edition = 2.4.3 或在 Magento Commerce Edition = 2.4.2 上执行，在其他版本或版本上，此观察者将被禁用。

<?php

declare(strict_types=1);

namespace Vendor\Module\Observer;

use Fom\Annotations\Attribute\Operator;
use Fom\Annotations\Attribute\Platform;
use Magento\Framework\Event\Observer;
use Magento\Framework\Event\ObserverInterface;

#[
    Platform(
        edition: Platform::EDITION_COMMUNITY,
        version: '2.4.3',
        comparison: Platform::COMPARISON_EQUAL
    ),
    Platform(
        edition: Platform::EDITION_COMMERCE,
        version: '2.4.2',
        comparison: Platform::COMPARISON_LESS_THAN
    ),
    Operator(operator: Operator::OPERATOR_OR)
]
class SomeKindOfActionObserver implements ObserverInterface
{
    public function execute(Observer $observer): void
    {
        // ...
    }
}

附加工具

• PHP Annotations - 扩展 PhpStorm 以支持 DocBlocks 中的注释。

版权

版权所有 © FriendsOfMagento