README

Pine Annotations

简介

Pine Annotations包使得在任意Laravel 5项目中创建和读取注释变得无缝。在幕后，Pine Annotations利用了doctrine-annotations项目，但试图简化其与Laravel 5的集成。

许可证

Pine Annotations是开源软件，受MIT许可证许可。

版本兼容性

安装

$ composer require larachimp/pine-annotations

配置

如果你使用Laravel >= 5.5，你可以利用Laravel自动包发现功能跳过服务注册。

安装后，你需要在你的config/app.php配置文件中注册LaraChimp\PineAnnotations\PineAnnotationsServiceProvider。

'providers' => [
    ...
    LaraChimp\PineAnnotations\PineAnnotationsServiceProvider::class,
],

你也可以注册Reader别名，它有助于读取对象的注释。

'aliases' => [
    ...
    'AnnotationsReader' => LaraChimp\PineAnnotations\Facades\Reader::class,
]

你现在可以使用以下命令发布配置

$ php artisan vendor:publish

这将创建配置目录中的pine-annotations.php文件。

在AnnotationRegistry中注册你的注释

pine-annotations.php配置文件有两个部分：autoload_files和autoload_namespaces。

autoload_files

'autoload_files' => [
    app_path('Annotations/FooAnnotation.php'),
],

在这个数组中，你可以包含所有注释类文件的路径。这些文件将注册到AnnotationRegistry中。你可以包含你需要的任意多个文件。

autoload_namespaces

'autoload_namespaces' => [
    'App\Annotations',
],

这个数组包含你的注释类所在的命名空间。如果你想一次性注册一个命名空间下的所有注释类，这很有用。

使用Reader手动添加条目到Registry

或者，你也可以使用addFilesToRegistry()和addNamespacesToRegistry()方法手动将文件和命名空间条目添加到注释注册表中。

// Adding files manually to the Registry.
AnnotationsReader::addFilesToRegistry($filesPaths);

// Adding namespaces manually to the Registry.
AnnotationsReader::addNamespacesToRegistry($namespaces);

你必须以某种方式使用Reader注册你的注释类。否则，AnnotationsReader将无法解析它们。

AnnotationsReader

要创建AnnotationsReader的实例，可以使用Laravel的IOC注入或通过app()方法或App外观创建它

<?php

use LaraChimp\PineAnnotations\Support\Reader\AnnotationsReader;

class MyService 
{
    /**
     * AnnotationsReader instance.
     * 
     * @var AnnotationsReader
     */
    protected $annotationsReader;
   
    /**
     * Constructor.
     * 
     * @var AnnotationsReader $annotationsReader
     */
    public function __construct(AnnotationsReader $annotationsReader) 
    {
        $this->annotationsReader = $annotationsReader;
    }
}

或

$annotationsReader = app(\LaraChimp\PineAnnotations\Support\Reader\AnnotationsReader::class);

或者也可以使用AnnotationsReader外观LaraChimp\PineAnnotations\Facades\Reader::class进行所有注释的读取。

读取一个类的所有注释

考虑以下被FooAnnotation注释的类

<?php

/**
 * Class Baz.
 *
 * @FooAnnotation(bar="Percy")
 */
class Baz
{
    //
}

要读取这个类的注释，只需创建一个以类为目标的AnnotationsReader实例

// Read all class annotations on class.
$annotations = AnnotationsReader::target('class')->read(Baz::class);

AnnotationsReader将返回一个包含类注释的Collection，其值已填充到正确的属性中

Illuminate\Support\Collection {
  #items: array:1 [
    0 => FooAnnotation {
      +bar: "Percy"
    }
  ]
}

注意，默认情况下，所有注释都缓存以方便使用。因此，AnnotationsReader不需要每次从目标读取注释时解析文档块，否则这将是一项成本高昂的操作。AnnotationsReader使用你在Laravel App中定义的默认缓存。

读取一个类的特定注释

考虑以下被FooAnnotation和FooDoubleAnnotation注释的类

<?php

/**
 * Class Baz.
 *
 * @FooAnnotation(bar="Percy")
 * @FooDoubleAnnotation(bar="Mamedy")
 */
class Baz
{
    //
}

现在我们可能只想解析或读取@FooDoubleAnnotation(bar="Mamedy")文档块。要做到这一点，我们可以在我们的AnnotationsReader实例上使用only()方法。该only()方法接受单个参数，即注解的类名。

// Read specific class annotations on class.
$annotations = AnnotationsReader::target('class')->only(FooDoubleAnnotation::class)->read(Baz::class);

这将返回一个包含目标注解的键和值的Collection。

Illuminate\Support\Collection {
  #items: array:1 [
    "bar" => "Mamedy"
  ]
}

读取类上属性的注解

考虑以下类，它在其name属性上有给定的注解块

<?php

class Baz
{
    /**
     * Name.
     *
     * @PropertyAnnotation(bar="Jeffrey")
     * @PropertyDoubleAnnotation(bar="Way")
     *
     * @var string
     */
    protected $name = '';
    
    //
}

要读取name属性的注解，我们将使用target作为property，以及在AnnotationsReader上该属性的名称

// Read all class annotations on property.
$annotations = AnnotationsReader::target('property', 'name')->read(Baz::class);

结果是包含所有注解对象及其属性值的Collection。

Illuminate\Support\Collection {
  #items: array:2 [
    0 => PropertyAnnotation {
      +bar: "Jeffrey"
    }
    1 => PropertyDoubleAnnotation {
      +bar: "Way"
    }
  ]
}

读取类上属性的特定注解

考虑以下类，它在其name属性上有给定的注解块

<?php

class Baz
{
    /**
     * Name.
     *
     * @PropertyAnnotation(bar="Jeffrey")
     * @PropertyDoubleAnnotation(bar="Way")
     *
     * @var string
     */
    protected $name = '';
    
    //
}

现在我们可能只想解析或读取@PropertyDoubleAnnotation(bar="Way")文档块。要做到这一点，我们将使用目标为property，以及该属性的名称和我们的AnnotationsReader实例上的only()方法。该only()方法接受单个参数，即注解的类名。

// Read all class annotations on property.
$annotations = AnnotationsReader::target('property', 'name')->only(PropertyDoubleAnnotation::class)
                                                            ->read(Baz::class);

这将返回一个包含目标注解的键和值的Collection。

Illuminate\Support\Collection {
  #items: array:1 [
    "bar" => "Way"
  ]
}

读取类上方法的注解

考虑以下类，它在其someMethod()方法上有给定的注解块

<?php

class Baz
{  
    /**
     * Some method that does somethin.
     *
     * @MethodAnnotation(bar="Way")
     * @MethodDoubleAnnotation(bar="Otwell")
     *
     * @return string
     */
     public function someMethod()
     {
        return 'I did something.';
     }
}

要读取someMethod()方法的所有注解，我们将使用目标为method，以及我们的AnnotationsReader实例上的方法名称

// Read all class annotations on property.
$annotations = AnnotationsReader::target('method', 'someMethod')->read(Baz::class);

结果是包含所有注解对象及其属性值的Collection。

Illuminate\Support\Collection {
  #items: array:2 [
    0 => MethodAnnotation {
      +bar: "Way"
    }
    1 => MethodDoubleAnnotation {
      +bar: "Otwell"
    }
  ]
}

读取类上方法的特定注解

考虑以下类，它在其someMethod()方法上有给定的注解块

<?php

class Baz
{  
    /**
     * Some method that does somethin.
     *
     * @MethodAnnotation(bar="Way")
     * @MethodDoubleAnnotation(bar="Otwell")
     *
     * @return string
     */
     public function someMethod()
     {
        return 'I did something.';
     }
}

现在我们可能只想解析或读取@MethodDoubleAnnotation(bar="Otwell")文档块。要做到这一点，我们将使用目标为method，以及该方法的名称和我们的AnnotationsReader实例上的only()方法。该only()方法接受单个参数，即注解的类名。

// Read all class annotations on property.
$annotations = AnnotationsReader::target('method', 'someMethod')->only(MethodDoubleAnnotation::class)
                                                                ->read(Baz::class);

这将返回一个包含目标注解的键和值的Collection。

Illuminate\Support\Collection {
  #items: array:1 [
    "bar" => "Otwell"
  ]
}

致谢

向所有努力创造惊人事物的研究员表示衷心的感谢！

创作者

Twitter: @PercyMamedy

GitHub: percymamedy