PHP自定義注解：增強(qiáng)代碼靈活性和可擴(kuò)展性

本文探討如何在Symfony 3應(yīng)用中創(chuàng)建和使用自定義注解。注解是我們?cè)陬?lèi)、方法和屬性上方看到的文檔塊元數(shù)據(jù)/配置，常用于聲明控制器路由（@Route()）、Doctrine ORM映射（@ORM()）或控制對(duì)Rauth等包中各種類(lèi)和方法的訪(fǎng)問(wèn)。本文將介紹如何自定義注解，并在不加載類(lèi)的情況下讀取類(lèi)或方法信息。

關(guān)鍵要點(diǎn):

• PHP自定義注解可用于向代碼添加元數(shù)據(jù)，影響代碼行為，使其更靈活、更易于適應(yīng)。它們可用于定義路由信息、指定驗(yàn)證規(guī)則或配置依賴(lài)注入。
• 創(chuàng)建PHP自定義注解需要定義一個(gè)新的類(lèi)來(lái)表示該注解。此類(lèi)應(yīng)具有與您希望在注解中設(shè)置的值相對(duì)應(yīng)的屬性。
• Doctrine支持自定義注解。您可以定義自己的注解并將其用于Doctrine實(shí)體中。Doctrine的注解讀取器將解析這些注解，然后可以使用它們來(lái)影響實(shí)體的行為。
• 使用PHP自定義注解的一個(gè)限制是它們不受語(yǔ)言本身的原生支持。這意味著您需要使用提供注解支持的庫(kù)或工具，例如Doctrine或PHP-DI。
• PHP自定義注解的用途多種多樣，包括在Web應(yīng)用程序中定義路由信息、為表單輸入指定驗(yàn)證規(guī)則或配置依賴(lài)注入。它們還可用于向代碼添加文檔。

免責(zé)聲明: 注解與Symfony無(wú)關(guān)，它是作為Doctrine項(xiàng)目的一部分開(kāi)發(fā)的概念，用于解決將ORM信息映射到類(lèi)方法的問(wèn)題。

本文將構(gòu)建一個(gè)名為WorkerBundle的小型可重用捆綁包（僅用于演示目的，并非真正可打包的）。我們將開(kāi)發(fā)一個(gè)小型概念，允許定義各種以不同速度“運(yùn)行”的Worker類(lèi)型，然后應(yīng)用程序中的任何人都可以使用它們。實(shí)際的worker操作不在本文的討論范圍之內(nèi)，因?yàn)槲覀冴P(guān)注的是設(shè)置管理它們的系統(tǒng)（并通過(guò)注解發(fā)現(xiàn)它們）。

您可以查看這個(gè)倉(cāng)庫(kù)并按照其中介紹的說(shuō)明在本地Symfony應(yīng)用程序中設(shè)置捆綁包。

Worker

Worker將實(shí)現(xiàn)一個(gè)接口，該接口需要一個(gè)方法：::work()。在新的WorkerBundle中，讓我們創(chuàng)建一個(gè)Workers/目錄來(lái)保持整潔，并在其中添加接口：

<?php
namespace WorkerBundle\Workers;

interface WorkerInterface
{
    /**
     * 執(zhí)行工作
     *
     * @return NULL
     */
    public function work();
}

注解

每個(gè)worker都必須實(shí)現(xiàn)上述接口。很清楚。但除此之外，我們還需要它們?cè)陬?lèi)上方有一個(gè)注解，以便找到它們并讀取有關(guān)它們的某些元數(shù)據(jù)。

Doctrine將文檔塊注解映射到一個(gè)類(lèi)，該類(lèi)的屬性表示注解本身內(nèi)部的鍵。讓我們創(chuàng)建我們自己的注解并實(shí)際操作一下。

每個(gè)WorkerInterface實(shí)例在其文檔塊中都將具有以下注解：

<?php
namespace WorkerBundle\Workers;

interface WorkerInterface
{
    /**
     * 執(zhí)行工作
     *
     * @return NULL
     */
    public function work();
}

我們將保持簡(jiǎn)單，只有兩個(gè)屬性：唯一名稱(chēng)（字符串）和worker速度（整數(shù)）。為了使Doctrine的注解庫(kù)能夠識(shí)別此注解，我們必須創(chuàng)建一個(gè)匹配的類(lèi)，不出所料，它自己也有一些注解。

我們將此類(lèi)放在捆綁包命名空間的Annotation文件夾中，并將其簡(jiǎn)單地命名為Worker：

/**
 * @Worker(
 *     name = "唯一的Worker名稱(chēng)",
 *     speed = 10
 * )
 */

如您所見(jiàn)，我們有兩個(gè)屬性和一些簡(jiǎn)單的getter方法。更重要的是，我們?cè)陧敳坑袃蓚€(gè)注解：@Annotation（告訴Doctrine此類(lèi)表示一個(gè)注解）和@Target("CLASS")（告訴它應(yīng)該在整個(gè)類(lèi)而不是方法或?qū)傩陨戏绞褂茫?。就是這樣，WorkerInterface類(lèi)現(xiàn)在可以通過(guò)確保在文件頂部使用use語(yǔ)句導(dǎo)入相應(yīng)的類(lèi)來(lái)使用此注解：

<?php
namespace WorkerBundle\Annotation;

use Doctrine\Common\Annotations\Annotation;

/**
 * @Annotation
 * @Target("CLASS")
 */
class Worker
{
    /**
     * @Required
     *
     * @var string
     */
    public $name;

    /**
     * @Required
     *
     * @var int
     */
    public $speed;

    /**
     * @return string
     */
    public function getName()
    {
        return $this->name;
    }

    /**
     * @return int
     */
    public function getSpeed()
    {
        return $this->speed;
    }
}

管理器

接下來(lái)，我們需要一個(gè)管理器，我們的應(yīng)用程序可以使用它來(lái)獲取所有可用worker的列表并創(chuàng)建它們。在與WorkerInterface相同的命名空間中，我們可以使用這個(gè)簡(jiǎn)單的管理器類(lèi)：

use WorkerBundle\Annotation\Worker;

發(fā)現(xiàn)器

我們注解演示的關(guān)鍵部分實(shí)際上是發(fā)現(xiàn)過(guò)程的一部分。為什么？因?yàn)槲覀兪褂肳orker注解來(lái)確定是否應(yīng)將相應(yīng)的類(lèi)視為Worker。在此過(guò)程中，我們?cè)趯?shí)際實(shí)例化對(duì)象之前使用了元數(shù)據(jù)。讓我們看看我們的WorkerDiscovery類(lèi)：

<?php
namespace WorkerBundle\Workers;

class WorkerManager
{
    // ... (代碼與原文相同) ...
}

連接起來(lái)

現(xiàn)在我們有了主要組件，是時(shí)候?qū)⑺袃?nèi)容連接起來(lái)了。首先，我們需要服務(wù)定義，因此在捆綁包的Resource/config文件夾中，我們可以有這個(gè)services.yml文件：

<?php
namespace WorkerBundle\Workers;

// ... (代碼與原文相同) ...
}

為了使我們的服務(wù)定義能夠被容器集中拾取，我們需要編寫(xiě)一個(gè)小的擴(kuò)展類(lèi)。因此，在捆綁包的DependencyInjection文件夾中，創(chuàng)建一個(gè)名為WorkerExtension的類(lèi)。位置和名稱(chēng)對(duì)于Symfony自動(dòng)拾取它都很重要。

services:
    worker_manager:
        class: WorkerBundle\Workers\WorkerManager
        arguments: ["@worker_discovery"]
    worker_discovery:
        class: WorkerBundle\Workers\WorkerDiscovery
        arguments: ["%worker_namespace%", "%worker_directory%", "%kernel.root_dir%", "@annotation_reader"]

最后，我們需要注冊(cè)我們的捆綁包。在我們的AppKernel中：

<?php
namespace WorkerBundle\DependencyInjection;

// ... (代碼與原文相同) ...
}

就是這樣。

讓我們工作！

現(xiàn)在我們準(zhǔn)備工作了。讓我們?cè)谥醒雙arameters.yml文件中配置我們的worker將在哪里找到：

public function registerBundles()
{
    return array(
        // ...
        new WorkerBundle\WorkerBundle(),
        // ...
    );
}

這些參數(shù)從容器傳遞到WorkerDiscovery類(lèi)，如上所述。

位置由您決定，但現(xiàn)在讓我們將我們的worker放在應(yīng)用程序的主要AppBundle捆綁包中。我們的第一個(gè)worker可能如下所示：

<?php
namespace WorkerBundle\Workers;

interface WorkerInterface
{
    /**
     * 執(zhí)行工作
     *
     * @return NULL
     */
    public function work();
}

我們的注解在那里，use語(yǔ)句到位，因此沒(méi)有任何東西可以阻止某些業(yè)務(wù)邏輯找到它并實(shí)例化它。讓我們假設(shè)在一個(gè)Controller方法內(nèi)部：

/**
 * @Worker(
 *     name = "唯一的Worker名稱(chēng)",
 *     speed = 10
 * )
 */

或者

<?php
namespace WorkerBundle\Annotation;

use Doctrine\Common\Annotations\Annotation;

/**
 * @Annotation
 * @Target("CLASS")
 */
class Worker
{
    /**
     * @Required
     *
     * @var string
     */
    public $name;

    /**
     * @Required
     *
     * @var int
     */
    public $speed;

    /**
     * @return string
     */
    public function getName()
    {
        return $this->name;
    }

    /**
     * @return int
     */
    public function getSpeed()
    {
        return $this->speed;
    }
}

結(jié)論

我們現(xiàn)在可以使用注解來(lái)表達(dá)有關(guān)類(lèi)（或方法和屬性）的元數(shù)據(jù)。在本教程中，我們構(gòu)建了一個(gè)小型包，它使應(yīng)用程序（或其他外部捆綁包）能夠通過(guò)定義有關(guān)它們的某些元數(shù)據(jù)來(lái)聲明能夠執(zhí)行某些工作的worker。此元數(shù)據(jù)不僅使它們易于發(fā)現(xiàn)，而且還提供有關(guān)是否應(yīng)該實(shí)際使用它們的信息。

您在自己的項(xiàng)目中使用自定義注解嗎？如果是這樣，您是如何實(shí)現(xiàn)它們的？也許還有第三種方法？讓我們知道！

(感興趣了解更多關(guān)于Symfony、Doctrine、注解以及各種企業(yè)級(jí)PHP內(nèi)容的信息？加入我們，參加為期三天的動(dòng)手研討會(huì)，WebSummerCamp——唯一一個(gè)完全手動(dòng)的會(huì)議，并且還會(huì)照顧您想帶去的任何人！)

(原文的FAQ部分已省略，因?yàn)槠鋬?nèi)容與已翻譯和改寫(xiě)的內(nèi)容高度重復(fù)。)

以上是您自己的自定義注釋 - 不僅僅是評(píng)論！的詳細(xì)內(nèi)容。更多信息請(qǐng)關(guān)注PHP中文網(wǎng)其他相關(guān)文章！