README

Jaxon 库的注解

此包为 Jaxon 库提供注解支持。与 Jaxon 类相关的配置选项可以直接在类文件中使用注解进行设置。

允许使用两种不同的注解语法：默认的类似数组的语法和自版本 1.4 起可用的类似文档块语法。

安装

使用 composer 安装此包。它需要 jaxon-php/jaxon-core v4 或更高版本。

composer require jaxon-php/jaxon-annotations

将注解配置选项设置为开启。

jaxon()->setOption('core.annotations.enabled', true);

使用方法

以下提供了以下注解。

@exclude

它阻止方法或类被导出到 JavaScript。它接受一个可选的布尔参数。

/**
 * @exclude(true)
 */
class JaxonExample
{
// This class will not be exported to javascript.
}

class JaxonExample
{
    /**
     * @exclude
     */
    public function doNot()
    {
        // This method will not be exported to javascript.
    }
}

也可以使用 PHP-DOC 语法。

class JaxonExample
{
    /**
     * @exclude false
     */
    public function do()
    {
        // This method will be exported to javascript.
    }

    /**
     * @exclude true
     */
    public function doNot()
    {
        // This method will not be exported to javascript.
    }
}

@upload

它向 AJAX 请求添加文件上传。它需要一个必选的 HTML 字段 ID。它仅适用于方法。

class JaxonExample extends \Jaxon\App\CallableClass
{
    /**
     * @upload('field' => 'div-user-file')
     */
    public function saveFile()
    {
        // Get the uploaded files.
        $files = $this->upload()->files();
    }
}

也可以使用 PHP-DOC 语法。

class JaxonExample extends \Jaxon\App\CallableClass
{
    /**
     * @upload div-user-file
     */
    public function saveFile()
    {
        // Get the uploaded files.
        $files = $this->upload()->files();
    }
}

@before

它定义一个类的方法作为在处理请求之前要调用的回调。它需要一个必选的方法名称参数，以及一个作为可选参数传递给回调的数组。它适用于方法和类。

class JaxonExample
{
    protected function funcBefore1()
    {
        // Do something
    }

    protected function funcBefore2($param1, $param2)
    {
        // Do something with parameters
    }

    /**
     * @before('call' => 'funcBefore1')
     * @before('call' => 'funcBefore2', 'with' => ['value1', 'value2'])
     */
    public function action()
    {
    }
}

也可以使用 PHP-DOC 语法。

class JaxonExample
{
    protected function funcBefore1()
    {
        // Do something
    }

    protected function funcBefore2($param1, $param2)
    {
        // Do something with parameters
    }

    /**
     * @before funcBefore1
     * @before funcBefore2 ["value1", "value2"]
     */
    public function action()
    {
    }
}

@after

它定义一个类的方法作为在处理请求之后要调用的回调。它需要一个必选的方法名称参数，以及一个作为可选参数传递给回调的数组。它适用于方法和类。

class JaxonExample
{
    protected function funcAfter1()
    {
        // Do something
    }

    protected function funcAfter2($param)
    {
        // Do something with parameter
    }

    /**
     * @after('call' => 'funcAfter1')
     * @after('call' => 'funcAfter2', 'with' => ['value'])
     */
    public function action()
    {
    }
}

也可以使用 PHP-DOC 语法。

class JaxonExample
{
    protected function funcAfter1()
    {
        // Do something
    }

    protected function funcAfter2($param)
    {
        // Do something with parameter
    }

    /**
     * @after funcAfter1
     * @after funcAfter2 ["value"]
     */
    public function action()
    {
    }
}

@callback

它定义一个在处理 AJAX 请求时要使用的 JavaScript 对象作为回调。

它从版本 2.2.0 开始添加。

/**
 * Default callback for all the requests to the class.
 *
 * @callback('name' => 'jaxon.ajax.callback.example')
 */
class JaxonExample
{
    /**
     * Specific callback for this method. It replaces the default class callback.
     *
     * @callback('name' => 'jaxon.ajax.callback.action')
     */
    public function action()
    {
    }
}

也可以使用 PHP-DOC 语法。

/**
 * Default callback for all the requests to the class.
 *
 * @callback jaxon.ajax.callback.example
 */
class JaxonExample
{
    /**
     * Specific callback for this method. It replaces the default class callback.
     *
     * @callback jaxon.ajax.callback.action
     */
    public function action()
    {
    }
}

@databag

它定义一个要附加到方法 AJAX 请求中的数据包。它需要一个必选的数据包名称参数。它适用于方法和类。

class JaxonExample extends \Jaxon\App\CallableClass
{
    /**
     * @databag('name' => 'user')
     */
    public function action()
    {
        // Update a value in the data bag.
        $count = $this->bag('user')->get('count', 0);
        $this->bag('user')->set('count', $count++);
    }
}

也可以使用 PHP-DOC 语法。

class JaxonExample extends \Jaxon\App\CallableClass
{
    /**
     * @databag user
     */
    public function action()
    {
        // Update a value in the data bag.
        $count = $this->bag('user')->get('count', 0);
        $this->bag('user')->set('count', $count++);
    }
}

@di

它定义一个将被注入到类中的属性。

当应用于方法和类时，它接受属性名称和类作为参数。

class JaxonExample extends \Jaxon\App\CallableClass
{
    /**
     * @var \App\Services\Translator
     */
     protected $translator;

    /**
     * @di('attr' => 'translator', class => '\App\Services\Translator')
     */
    public function translate(string $phrase)
    {
        // The $translator property is set from the DI container when this method is called.
        $phrase = $this->translator->translate($phrase);
    }
}

类参数是可选的，如果已经通过 @var 注解指定，则可以省略。

class JaxonExample extends \Jaxon\App\CallableClass
{
    /**
     * @var \App\Services\Translator
     */
     protected $translator;

    /**
     * @di('attr' => 'translator')
     */
    public function translate(string $phrase)
    {
        // The $translator property is set from the DI container when this method is called.
        $phrase = $this->translator->translate($phrase);
    }
}

当应用于属性时，它只接受属性类作为参数，如果已经通过 @var 注解指定，则可以省略。

class JaxonExample extends \Jaxon\App\CallableClass
{
    /**
     * @di(class => '\App\Services\Translator')
     * @var \App\Services\Translator
     */
     protected $translator;

    public function translate(string $phrase)
    {
        // The $translator property is set from the DI container when this method is called.
        $phrase = $this->translator->translate($phrase);
    }
}

class JaxonExample extends \Jaxon\App\CallableClass
{
    /**
     * @di
     * @var \App\Services\Translator
     */
     protected $translator;

    public function translate(string $phrase)
    {
        // The $translator property is set from the DI container when this method is called.
        $phrase = $this->translator->translate($phrase);
    }
}

如果类名不以 "\" 开头，则将使用 use 指令或源文件中的 namespace 设置相应的完全限定名称 (FQN)。

namespace App\Ajax;

use App\Services\Translator;

class JaxonExample extends \Jaxon\App\CallableClass
{
    /**
     * @var Translator
     */
     protected $translator;

    /**
     * @var Formatter
     */
     protected $formatter;

    /**
     * @di('attr' => 'translator', class => 'Translator')
     * @di('attr' => 'formatter', class => 'Formatter')
     */
    public function translate(string $phrase)
    {
        // The Translator FQN is defined by the use instruction => App\Services\Translator.
        // The Formatter FQN is defined by the current namespace => App\Ajax\Formatter.
        $phrase = $this->formatter->format($this->translator->translate($phrase));
    }
}

也可以使用 PHP-DOC 语法。

namespace App\Ajax;

use App\Services\Translator;

class JaxonExample extends \Jaxon\App\CallableClass
{
    /**
     * @var Translator
     */
     protected $translator;

    /**
     * @var Formatter
     */
     protected $formatter;

    /**
     * @di $translator   Translator
     * @di $formatter    Formatter
     */
    public function translate(string $phrase)
    {
        // The Translator FQN is defined by the use instruction => App\Services\Translator.
        // The Formatter FQN is defined by the current namespace => App\Ajax\Formatter.
        $phrase = $this->formatter->format($this->translator->translate($phrase));
    }
}

namespace App\Ajax;

use App\Services\Translator;

/**
 * @di $translator   Translator
 * @di $formatter    Formatter
 */
class JaxonExample extends \Jaxon\App\CallableClass
{
    /**
     * @var Translator
     */
     protected $translator;

    /**
     * @var Formatter
     */
     protected $formatter;

    public function translate(string $phrase)
    {
        // The Translator FQN is defined by the use instruction => App\Services\Translator.
        // The Formatter FQN is defined by the current namespace => App\Ajax\Formatter.
        $phrase = $this->formatter->format($this->translator->translate($phrase));
    }
}

namespace App\Ajax;

use App\Services\Translator;

class JaxonExample extends \Jaxon\App\CallableClass
{
    /**
     * @di  Translator
     * @var Translator
     */
     protected $translator;

    /**
     * @di  Formatter
     * @var Formatter
     */
     protected $formatter;

    public function translate(string $phrase)
    {
        // The Translator FQN is defined by the use instruction => App\Services\Translator.
        // The Formatter FQN is defined by the current namespace => App\Ajax\Formatter.
        $phrase = $this->formatter->format($this->translator->translate($phrase));
    }
}