README

PHP 库，用于解析 Markdown 格式的变更日志文件。

要求

• PHP >= 7.4
• JSON 扩展
• Composer

安装

使用以下命令将包添加到您的 composer.json 文件中

composer require mistralys/changelog-parser

还可以查看 Packagist 页面。

支持的变更日志格式

解析器期望所有版本都被列在相同级别的标题下，并且每个更改作为一个列表添加。以下两个示例都将工作

# v1.2.3
- Made some changes

# v1.2.2
- Lotsa code changes
- Added some documentation

### v1.2.3
- Made some changes

### v1.2.2
- Lotsa code changes
- Added some documentation

版本标题格式

以下所有标题都是解析器可以识别的有效格式

# v1

# v1.2

# v1.2.3

# 1

# 1.2

# 1.2.3

# 1.2.3-ALPHA

# 1.2.3-BranchName-SNAPSHOT

# 5.0 - Optional version label

# 5.0 | Optional version label

# 5.0 ~ Optional version label

有关可以使用版本字符串的范围的更多信息，请参阅 mistralys/version-parser 包中支持的格式，该包用于读取它们。

在文档中嵌套变更日志

解析器分析 Markdown 文档的方式意味着变更日志可以嵌套在任何地方。标题级别将从它遇到的第一个版本标题推断出来。

在此示例中，变更日志不是一个单独的文档，而是嵌套在子节中。

# Application name

## Usage

Learn how to use the application with this documentation.

## Change log

### v1.2.3
- Made some changes

### v1.2.2
- Lotsa code changes
- Added some documentation

## Credits

Many people contributed to the application.

变更日志解析器将坚持于文档中找到的第一个变更日志，这意味着即使它们具有相同的标题级别，也只会使用多个独立版本列表中的第一个。

版本中的子标题

解析器将识别版本条目中的子标题，并将收集这些作为纯文本以供以后访问。这使得进一步记录诸如破坏性更改等内容成为可能。

# v2.0.0 - Complete rework (breaking)
- Code entirely refurbished
- Documentation rewritten

## Breaking changes
- Renamed all methods
- Renamed all files

只有版本下的条目将被认为是该版本的更改。 "破坏性更改" 子标题和任何其他内容将被捕获为文本，可以通过 getFreeformText() 访问。

use Mistralys\ChangelogParser\ChangelogParser;

$version = ChangelogParser::parseMarkdownFile('changelog.md')->getVersionByNumber('2.0.0');

echo $version->getFreeformText();

这将输出

## Breaking changes
- Renamed all methods
- Renamed all files

使用示例

获取所有版本

use Mistralys\ChangelogParser\ChangelogParser;

$versions = ChangelogParser::parseMarkdownFile('changelog.md')->getVersions();

foreach($versions as $version)
{
    echo $version->getNumber().PHP_EOL;
}

获取最新版本

use Mistralys\ChangelogParser\ChangelogParser;

$parser = ChangelogParser::parseMarkdownFile('changelog.md');

$latest = $parser->getLatestVersion();

按数字获取版本

use Mistralys\ChangelogParser\ChangelogParser;

$parser = ChangelogParser::parseMarkdownFile('changelog.md');

$version = $parser->getVersionByNumber('5.2.0');

如果找不到版本，这将抛出异常。要事先检查版本号是否存在

检查版本是否存在

use Mistralys\ChangelogParser\ChangelogParser;

$parser = ChangelogParser::parseMarkdownFile('changelog.md');

if($parser->versionExists('5.2.0'))
{
    $version = $parser->getVersionByNumber('5.2.0');
}

请注意，这需要知道确切的版本号（主版本、次版本和补丁版本号）。为了更灵活地查找版本，最好使用版本信息。

例如，要查找所有匹配 v4.2.x 的版本

use Mistralys\ChangelogParser\ChangelogParser;

$versions = ChangelogParser::parseMarkdownFile('changelog.md')->getVersions();

foreach($versions as $version)
{
    $info = $version->getVersionInfo();
    
    if($info->getMajorVersion() === 4 && $info->getMinorVersion() === 2) 
    {
        // Matches v4.2
    }
}

遍历版本中的单个更改

use Mistralys\ChangelogParser\ChangelogParser;

$version = ChangelogParser::parseMarkdownFile('changelog.md')->requireLatestVersion();

$changes = $version->getChanges();

echo "Changes in version ".$version->getNumber().":".PHP_EOL;

foreach($changes as $change)
{
    echo '- '.$change->getText().PHP_EOL;
}

注意 requireLatestVersion() 方法的使用：如果没有在变更日志中找到任何版本，它将抛出异常而不是 NULL。这很有用，可以避免检查空值。

持久化和缓存

为了轻松存储或传输变更日志信息，解析器提供将数据序列化为 JSON 的可能性。这可以在以后再次解码，而不是每次都解析源文件。

use Mistralys\ChangelogParser\ChangelogParser;

if(!file_exists('changelog.json'))
{
    $changelog = ChangelogParser::parseMarkdownFile('changelog.md');
    $changelog->toJSONFile('changelog.json');
}
else
{
    $changelog = ChangelogParser::parseJSONFile('changelog.json');
}

此示例将自动创建一个 JSON 缓存文件，它的性能优于每次都解析源 markdown 文件，特别是对于大型文件。