berlioz/php-doc

Berlioz PhpDoc 是一个PHP库，用于读取代码中的文档（类、方法和函数）并进行高级注释解释。

维护者

详细信息

github.com/BerliozFramework/PhpDoc

主页

源代码

问题

安装数: 7,620

依赖: 1

建议者: 0

安全性: 0

星标: 1

关注者: 2

分支: 0

公开问题: 0

v1.1.0 2020-11-05 14:00 UTC

Requires

Requires (Dev)

MIT 8258841288edc8e03039a627ee4fe66a567ec399

  • Ronan Giron <ronan.woop@getberlioz.com>

This package is auto-updated.

Last update: 2024-09-07 19:40:30 UTC

README

Latest Version Software license Build Status Quality Grade Total Downloads

Berlioz PhpDoc 是一个PHP库，用于通过高级注释解释读取代码中的文档（类、方法和函数）。

安装

Composer

您可以使用 Composer 安装 Berlioz PhpDoc，这是推荐的安装方式。

$ composer require berlioz/php-doc

依赖

  • PHP ^7.1 || ^8.0
  • 包
    • psr/simple-cache
    • psr/log

使用

基本

$phpDocFactory = new PhpDocFactory;

// To get class PhpDoc
$doc = $phpDocFactory->getClassDoc(ClassOfMyProject::class);

// To get class property PhpDoc
$doc = $phpDocFactory->getPropertyDoc(ClassOfMyProject::class, 'myProperty');

// To get class method PhpDoc
$doc = $phpDocFactory->getMethodDoc(ClassOfMyProject::class, 'myMethod');

// To get function PhpDoc
$doc = $phpDocFactory->getFunctionDoc('myFunction');

缓存

该库支持PSR-16（缓存库的通用接口）。

要使用它，您需要将缓存管理器作为第一个参数传递给 PhpDocFactory 类。

$simpleCacheManager = new MySimpleCacheManager;

$phpDocFactory = new PhpDocFactory($simpleCacheManager);

这样，您就可以实现磁盘I/O优化，并且您的应用程序将比不使用缓存管理器时运行得更快。

Berlioz\PhpDoc\DocBlock 类

当您调用这些工厂方法时，会返回一个 DocBlock 类或它们的数组

  • PhpDocFactory::getClassDocs() 返回一个 Berlioz\PhpDoc\DocBlock 数组
  • PhpDocFactory::getClassDoc() 返回一个 Berlioz\PhpDoc\DocBlock\ClassDocBlock 对象
  • PhpDocFactory::getPropertyDoc() 返回一个 Berlioz\PhpDoc\DocBlock\PropertyDocBlock 对象
  • PhpDocFactory::getMethodDoc() 返回一个 Berlioz\PhpDoc\DocBlock\MethodDocBlock 对象
  • PhpDocFactory::getFunctionDoc() 返回一个 Berlioz\PhpDoc\DocBlock\FunctionDocBlock 对象

一些方法可以通过 DocBlock 对象访问

  • DocBlock::getTitle() 返回 PhpDoc 中的标题部分
  • DocBlock::getDescription() 返回 PhpDoc 中的描述部分
  • DocBlock::getTags() 返回 PhpDoc 中所有存在的标签
  • DocBlock::getTag() 返回 PhpDoc 中存在的标签
  • DocBlock::hasTag() 返回标签是否存在于 PhpDoc 中

通过扩展 DocBlock 类，还有更多方法可供使用

  • Berlioz\PhpDoc\DocBlock\FunctionDocBlock:
    • FunctionDocBlock::getName(): 返回函数的完整名称
    • FunctionDocBlock::getShortName(): 返回函数的短名称
    • FunctionDocBlock::getNamespaceName(): 返回函数的命名空间名称
    • FunctionDocBlock::getClassName(): 返回类的名称
    • FunctionDocBlock::isDisabled(): 确定函数是否被禁用
    • FunctionDocBlock::isUserDefined(): 确定是否为用户定义的函数
    • FunctionDocBlock::isInternal(): 确定函数是否为内部函数
    • FunctionDocBlock::isClosure(): 确定函数是否为闭包
    • FunctionDocBlock::isDeprecated(): 确定函数是否已弃用
    • FunctionDocBlock::isGenerator(): 确定函数是否为生成器
    • FunctionDocBlock::isVariatic(): 确定函数是否为可变函数
  • Berlioz\PhpDoc\DocBlock\ClassDocBlock:
    • ClassDocBlock::getName(): 返回类的完整名称
    • ClassDocBlock::getShortName(): 返回类的短名称
    • ClassDocBlock::getNamespaceName(): 返回类的命名空间名称
    • ClassDocBlock::isAbstract(): 确定类是否为抽象类
    • ClassDocBlock::isFinal(): 确定类是否为最终类
    • ClassDocBlock::isInternal(): 确定类是否为内部类
    • ClassDocBlock::isUserDefined(): 确定是否为用户定义的类
    • ClassDocBlock::isAnonymous(): 确定类是否为匿名类
    • ClassDocBlock::isCloneable(): 确定类是否可克隆
    • ClassDocBlock::isInstantiable(): 确定类是否可实例化
    • ClassDocBlock::isInterface()：判断类是否为接口
    • ClassDocBlock::isIterable()：判断类是否可迭代
    • ClassDocBlock::isIterateable()：判断类是否可迭代
    • ClassDocBlock::isTrait()：判断类是否为特性
  • Berlioz\PhpDoc\DocBlock\PropertyDocBlock:
    • PropertyDocBlock::getName()：返回属性的完整名称
    • PropertyDocBlock::getShortName()：返回属性的简称
    • PropertyDocBlock::getNamespaceName()：返回类的命名空间名称
    • PropertyDocBlock::getClassName()：返回类的名称
    • PropertyDocBlock::isPublic()：判断属性是否有公开可见性
    • PropertyDocBlock::isProtected()：判断属性是否有受保护可见性
    • PropertyDocBlock::isPrivate()：判断属性是否有私有可见性
    • PropertyDocBlock::isStatic()：判断属性是否为静态
    • PropertyDocBlock::isDefault()：判断属性是否为默认
  • Berlioz\PhpDoc\DocBlock\MethodDocBlock:
    • MethodDocBlock::getName()：返回方法的完整名称
    • MethodDocBlock::getShortName()：返回方法的简称
    • MethodDocBlock::getNamespaceName()：返回类的命名空间名称
    • MethodDocBlock::getClassName()：返回类的名称
    • MethodDocBlock::isConstructor()：判断方法是否为构造函数
    • MethodDocBlock::isDestructor()：判断方法是否为析构函数
    • MethodDocBlock::isPublic()：判断方法是否有公开可见性
    • MethodDocBlock::isProtected()：判断方法是否有受保护可见性
    • MethodDocBlock::isPrivate()：判断方法是否有私有可见性
    • MethodDocBlock::isStatic()：判断方法是否为静态
    • MethodDocBlock::isAbstract()：判断方法是否为抽象
    • MethodDocBlock::isFinal()：判断方法是否为最终
    • MethodDocBlock::isUserDefined()：判断是否为用户定义方法
    • MethodDocBlock::isInternal()：判断方法是否为内部方法
    • MethodDocBlock::isClosure()：判断方法是否为闭包
    • MethodDocBlock::isDeprecated()：判断方法是否已弃用
    • MethodDocBlock::isGenerator()：判断方法是否为生成器
    • MethodDocBlock::isVariatic()：判断方法是否为可变

标签

格式

库支持一些标签格式，DocBlock 类返回的值是 PHP 代码而不是字符串。

示例

/**
 * Test doc.
 *
 * My description of my method.
 * Multi-line.
 *
 * @test false
 * @novalue
 * @value Only text
 * @test2("test", param1=true, param2="test", param3={"test":"test"})
 * @value Second text
 * @jsonTest {"test":"test"}
 * @jsonArrayTest [{"test":"test"}, {"test2":"test2"}]
 */

DocBlock::getTags() 方法的返回结果是

array(6) {
  ["test"]=>
  array(1) {
    [0]=>
    object(Berlioz\PhpDoc\Tag) (2) {
      ["name":"Berlioz\PhpDoc\Tag":private]=>
      string(4) "test"
      ["value":"Berlioz\PhpDoc\Tag":private]=>
      bool(false)
    }
  }
  ["novalue"]=>
  array(1) {
    [0]=>
    object(Berlioz\PhpDoc\Tag) (2) {
      ["name":"Berlioz\PhpDoc\Tag":private]=>
      string(7) "novalue"
      ["value":"Berlioz\PhpDoc\Tag":private]=>
      NULL
    }
  }
  ["value"]=>
  array(2) {
    [0]=>
    object(Berlioz\PhpDoc\Tag) (2) {
      ["name":"Berlioz\PhpDoc\Tag":private]=>
      string(5) "value"
      ["value":"Berlioz\PhpDoc\Tag":private]=>
      string(9) "Only text"
    }
    [1]=>
    object(Berlioz\PhpDoc\Tag) (2) {
      ["name":"Berlioz\PhpDoc\Tag":private]=>
      string(5) "value"
      ["value":"Berlioz\PhpDoc\Tag":private]=>
      string(11) "Second text"
    }
  }
  ["test2"]=>
  array(1) {
    [0]=>
    object(Berlioz\PhpDoc\Tag) (2) {
      ["name":"Berlioz\PhpDoc\Tag":private]=>
      string(5) "test2"
      ["value":"Berlioz\PhpDoc\Tag":private]=>
      array(4) {
        [0]=>
        string(4) "test"
        ["param1"]=>
        bool(true)
        ["param2"]=>
        string(4) "test"
        ["param3"]=>
        object(stdClass) (1) {
          ["test"]=>
          string(4) "test"
        }
      }
    }
  }
  ["jsonTest"]=>
  array(1) {
    [0]=>
    object(Berlioz\PhpDoc\Tag) (2) {
      ["name":"Berlioz\PhpDoc\Tag":private]=>
      string(8) "jsonTest"
      ["value":"Berlioz\PhpDoc\Tag":private]=>
      object(stdClass) (1) {
        ["test"]=>
        string(4) "test"
      }
    }
  }
  ["jsonArrayTest"]=>
  array(1) {
    [0]=>
    object(Berlioz\PhpDoc\Tag) (2) {
      ["name":"Berlioz\PhpDoc\Tag":private]=>
      string(13) "jsonArrayTest"
      ["value":"Berlioz\PhpDoc\Tag":private]=>
      array(2) {
        [0]=>
        object(stdClass) (1) {
          ["test"]=>
          string(4) "test"
        }
        [1]=>
        object(stdClass) (1) {
          ["test2"]=>
          string(5) "test2"
        }
      }
    }
  }
}

可用标签

一些标签默认可用

  • Berlioz\PhpDoc\Tag\ParamTag
  • Berlioz\PhpDoc\Tag\ReturnTag
  • Berlioz\PhpDoc\Tag\VarTag

扩展

您可以扩展标签并将它们声明给解析器。您的标签必须实现 TagInterface 接口。

$phpDocFactory = new PhpDocFactory;
$phpDocFactory->getParser()->addTagClass('tagName', MyTagClass::class);