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

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

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

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

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

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

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

Worker

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

<?php
namespace WorkerBundle\Workers;

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

註解

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

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

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

<?php
namespace WorkerBundle\Workers;

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

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

我們將此類放在捆綁包命名空間的Annotation文件夾中，並將其簡單地命名為Worker：

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

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

<?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;
    }
}

管理器

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

use WorkerBundle\Annotation\Worker;

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

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

<?php
namespace WorkerBundle\Workers;

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

連接起來

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

<?php
namespace WorkerBundle\Workers;

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

為了使我們的服務(wù)定義能夠被容器集中拾取，我們需要編寫一個(gè)小的擴(kuò)展類。因此，在捆綁包的DependencyInjection文件夾中，創(chuàng)建一個(gè)名為WorkerExtension的類。位置和名稱對於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"]

最後，我們需要註冊我們的捆綁包。在我們的AppKernel中：

<?php
namespace WorkerBundle\DependencyInjection;

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

就是這樣。

讓我們工作！

現(xiàn)在我們準(zhǔn)備工作了。讓我們在中央parameters.yml文件中配置我們的worker將在哪裡找到：

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

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

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

<?php
namespace WorkerBundle\Workers;

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

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

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

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

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

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

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