README

DocFX PHP

这个库可以帮助你生成 PHP 类的 YAML 表示，它可以集成到 DocFx。

DocFX-php 仅支持 DocFX v2。它尚未在较新版本上测试。

免责声明 此项目主要是为个人使用而创建的。它尚未经过彻底测试，可能缺少一些功能。我也没有长期维护此项目的计划。请自行决定使用。

入门

依赖关系

php: >= 8.1
nikic/php-parser: ^4.13
symfony/yaml: ^6
phpdocumentor/reflection-docblock: ^5
maennchen/zipstream-php: ^2.1

安装

DocFX-php 可在 Packagist 上获取。因此，建议通过 Composer 安装库。

要开始，请在您的项目中执行以下命令

composer require --dev picorose/docfx-php

或者将这一行添加到您的 composer.json

"picorose/docfx-php": "^1.0"

或者，您可以下载最新版本作为 zip 文件，并将其手动包含到您的项目中。请注意，当您想要使用库及其所有依赖项时，您将需要手动包含每个文件。

以下代码片段显示了一种包含源文件夹中所有文件的方法，而无需手动指定每个文件

<?php
function loadFiles(string $path) {
    if (!is_dir($path))
        return;

    // Loop through each file in the given path
    foreach (scandir($path) as $file) {
        if ($file == "." || $file == "..")
            continue;
            
        // Only load php files
        if (strlen($file) > 4 && strtolower(substr($file, -4)) == ".php")
            require_once realpath($path) . "/$file";
            
        // Recursively load files in sub-directories
        if (is_dir($file))
            loadFiles($path . "/$file");
    }
}

loadFiles("src");

用法

使用命令行工具

解析类的最简单方法是使用命令行工具。如果项目是通过 composer 安装的，则会有一个 vendor/bin/docfx-php 文件。

> vendor/bin/docfx-php help
DocFX-php v1.2.0
Copyright (c) 2022 Picorose
This is opensource software under the MIT license.

    Usage: docfx-php <subcommand> [<args>]
    Example: docfx-php build project/src -o project.zip -ns "com\\Picorose\\Example"

Do 'docfx-php help <command>' to read more about a specific subcommand.

    build                  : Build the yaml files for a project
    help, -h, --help       : Show a help page for a subcommand or this command
    version, -v, --version : Show the current version of the tool

该工具非常直接，并在必要时提供帮助。一个示例用法可以是

> vendor/bin/docfx-php build src -o target/myProject.zip -ns com\\Picorose\\Examples
Successfully parsed classes! File was saved to '/home/user/Documents/target/myProject.zip'

使用 PHP

首先，确保您想要解析的类通过使用 require、require_once 或 include 包含。以下示例我们将参考此项目示例文件夹中的 IAnimal 类。

<?php
// Load composer dependencies
require_once "PATH/TO/VENDOR/autoload.php";

// Load model classes
loadFiles("Models");

解析 PHP 类和命名空间非常简单。有三种方法可以序列化类

<?php
use \com\Picorose\DocFx\ClassParser;

// Parse a single class into a managed reference. This will generate a single ManagedReference instance 
$managedReference = ClassParser::parseClass("com\\Picorose\\Examples\\Dog");
$yaml = $managedReference->toYaml();

// Parse all classes in the given namespace. In addition to generating ManagedReference instances for each class, this
// will also generate a TableOfContents instance and a ManagedReference instance for the namespace itself
$namespace = ClassParser::parseNamespace("com\\Picorose\\Examples");
$yamlFiles = [];
foreach ($namespace as $obj)
    $yamlFiles[] = $obj->toYaml();

// Does the same as the previous method, except that it will also convert the resulting objects into yaml files, package
// them all in a zip file and set the headers for downloading the zip file
ClassParser::parseNamespaceAsZip("com\\Picorose\\Examples");

为 Dog 类生成的 yaml 应该看起来像这样

### YamlMime:ManagedReference
items:
  -
    uid: com.Picorose.Examples.Dog
    id: Dog
    parent: com.Picorose.Examples
    children:
      - 'com.Picorose.Examples.Dog.__construct(Human,string,Color,string)'
      - com.Picorose.Examples.Dog.getColor()
      - com.Picorose.Examples.Dog.getBreed()
      - com.Picorose.Examples.Dog.doesEat(IAnimal)
      - com.Picorose.Examples.Dog.mixedVal
      - com.Picorose.Examples.Dog.type
      - com.Picorose.Examples.Dog.VARIABLE
    langs:
      - php
    name: Dog
    nameWithType: Dog
    fullName: com\Picorose\Examples\Dog
    type: Class
    namespace: com\Picorose\Examples
    assemblies:
      - php
    syntax:
      content: 'class Dog extends Pet'
    inheritance:
      - com.Picorose.Examples.Pet
    implements:
      - com.Picorose.Examples.IAnimal
    inheritedMembers:
      - com.Picorose.Examples.Pet.getOwner()
      - com.Picorose.Examples.Pet.getName()
      - com.Picorose.Examples.Pet.toArray()
    summary: "Represents human's best friend, a dog"
  -
    uid: 'com.Picorose.Examples.Dog.__construct(Human,string,Color,string)'
    id: '__construct(Human,string,Color,string)'
    parent: com.Picorose.Examples.Dog
    langs:
      - php
    name: '__construct(?Human $owner, ?string $name, Color $color, string $breed)'
    nameWithType: 'Dog->__construct(?Human $owner, ?string $name, Color $color, string $breed)'
    fullName: 'com\Picorose\Examples\Dog->__construct(?Human $owner, ?string $name, Color $color, string $breed)'
    type: Constructor
    namespace: com\Picorose\Examples
    assemblies:
      - php
    syntax:
      content: 'public function __construct(?Human $owner, ?string $name, Color $color, string $breed)'
      parameters:
        -
          id: owner
          type: com.Picorose.Examples.Human
          allowsNull: true
          description: 'The owner of the dog'
        -
          id: name
          type: string
          allowsNull: true
          description: 'The name of the dog'
        -
          id: color
          type: com.Picorose.Examples.Color
          description: 'The fur color of the dog'
        -
          id: breed
          type: string
          description: 'The breed of the dog'
    modifiers:
      - public
    summary: 'Main constructor for the Dog class'
  -
    uid: com.Picorose.Examples.Dog.getColor()
    id: getColor()
    parent: com.Picorose.Examples.Dog
    langs:
      - php
    name: getColor()
    nameWithType: Dog->getColor()
    fullName: com\Picorose\Examples\Dog->getColor()
    type: Method
    namespace: com\Picorose\Examples
    assemblies:
      - php
    syntax:
      content: 'public function getColor(): Color'
      return:
        type: com.Picorose.Examples.Color
        description: 'The fur color of the dog'
    modifiers:
      - public
  -
    uid: com.Picorose.Examples.Dog.getBreed()
    id: getBreed()
    parent: com.Picorose.Examples.Dog
    langs:
      - php
    name: getBreed()
    nameWithType: Dog->getBreed()
    fullName: com\Picorose\Examples\Dog->getBreed()
    type: Method
    namespace: com\Picorose\Examples
    assemblies:
      - php
    syntax:
      content: 'public function getBreed(): string'
      return:
        type: string
        description: 'The breed of the dog'
    modifiers:
      - public
  -
    uid: com.Picorose.Examples.Dog.doesEat(IAnimal)
    id: doesEat(IAnimal)
    parent: com.Picorose.Examples.Dog
    langs:
      - php
    name: 'doesEat(IAnimal $other)'
    nameWithType: 'Dog->doesEat(IAnimal $other)'
    fullName: 'com\Picorose\Examples\Dog->doesEat(IAnimal $other)'
    type: Method
    namespace: com\Picorose\Examples
    assemblies:
      - php
    syntax:
      content: 'public function doesEat(IAnimal $other): bool'
      return:
        type: bool
        description: 'True if the animal would eat the animal'
      parameters:
        -
          id: other
          type: com.Picorose.Examples.IAnimal
          description: 'The animal to be eaten'
    modifiers:
      - public
    summary: 'Checks if the animal would eat another animal'
  -
    uid: com.Picorose.Examples.Dog.mixedVal
    id: mixedVal
    name: mixedVal
    type: Field
    assemblies:
      - php
    syntax:
      content: 'public mixed $mixedVal'
      return:
        type: mixed
  -
    uid: com.Picorose.Examples.Dog.type
    id: type
    name: type
    type: Field
    assemblies:
      - php
    syntax:
      content: 'public string $type = "Meh"'
      return:
        type: string
  -
    uid: com.Picorose.Examples.Dog.VARIABLE
    id: VARIABLE
    name: VARIABLE
    type: Field
    assemblies:
      - php
    syntax:
      content: 'const VARIABLE = "Blegh"'
references:
  -
    uid: com.Picorose.Examples.Human
    name: Human
    fullName: com\Picorose\Examples\Human
    nameWithType: Human
  -
    uid: string
    name: string
    fullName: string
    nameWithType: string
    isExternal: true
  -
    uid: com.Picorose.Examples.Color
    name: Color
    fullName: com\Picorose\Examples\Color
    nameWithType: Color
  -
    uid: com.Picorose.Examples.IAnimal
    name: IAnimal
    fullName: com\Picorose\Examples\IAnimal
    nameWithType: IAnimal
  -
    uid: bool
    name: bool
    fullName: bool
    nameWithType: bool
    isExternal: true
  -
    uid: com.Picorose.Examples.Pet.getOwner()
    name: getOwner()
    fullName: com\Picorose\Examples\Pet->getOwner()
    nameWithType: Pet->getOwner()
  -
    uid: com.Picorose.Examples.Pet.getName()
    name: getName()
    fullName: com\Picorose\Examples\Pet->getName()
    nameWithType: Pet->getName()
  -
    uid: com.Picorose.Examples.Pet.toArray()
    name: toArray()
    fullName: com\Picorose\Examples\Pet->toArray()
    nameWithType: Pet->toArray()
  -
    uid: mixed
    name: mixed
    fullName: mixed
    nameWithType: mixed
    isExternal: true
memberType: SeparatePages

部署到 DocFX

如果您尚未设置 DocFX 项目，可以按照以下简单步骤使用从 ClassParser 生成的 yaml 文件设置基本项目。

下载 DocFX 可执行文件。确保您下载 DocFX v2
初始化新的 DocFX 项目： docfx init -q
为您的类生成 yaml 文件，并将其放置在刚刚创建的 docfx_project 文件夹的 api 文件夹中
构建静态站点： docfx build docfx_project/docfx.json
使用内置的 web 服务器提供静态站点： docfx serve docfx_project/_site
您的文档将在 https://:8080/ 上可用

PHP Xref

有一个 xrefmap.yml 文件可用于原生 PHP 参考。该文件确保原生 PHP 类型（如 string、mixed、mysqli_result 等）链接到相关的 PHP 文档。

它可通过以下链接访问：https://picorose.com/assets/uploads/xrefmap.yml，或者在本项目的 refs 文件夹中。

要开始使用它，只需在您的 docfx.json 文件的 build -> xref 部分添加对 xrefmap.yml 文件的链接。

"build": {
  "xref": [ "https://picorose.com/assets/uploads/xrefmap.yml" ]
}

待办事项

[ ] 支持内联 {@inheritDoc} 标签
[ ] 支持内联 {@see} 标签

picorose / docfx-php

维护者

详细信息