{"id":24540682,"url":"https://github.com/mistralys/changelog-parser","last_synced_at":"2025-03-16T05:43:30.245Z","repository":{"id":153607150,"uuid":"629989504","full_name":"Mistralys/changelog-parser","owner":"Mistralys","description":"PHP library to parse Markdown-based change log files.","archived":false,"fork":false,"pushed_at":"2023-10-17T08:08:44.000Z","size":50,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-23T11:45:32.673Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Mistralys.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-04-19T12:44:26.000Z","updated_at":"2023-12-19T18:08:55.000Z","dependencies_parsed_at":"2023-05-20T11:45:41.254Z","dependency_job_id":null,"html_url":"https://github.com/Mistralys/changelog-parser","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mistralys%2Fchangelog-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mistralys%2Fchangelog-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mistralys%2Fchangelog-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mistralys%2Fchangelog-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mistralys","download_url":"https://codeload.github.com/Mistralys/changelog-parser/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243830914,"owners_count":20354850,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-22T18:14:40.981Z","updated_at":"2025-03-16T05:43:30.222Z","avatar_url":"https://github.com/Mistralys.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Changelog Parser\n\nPHP library to parse Markdown-formatted change log files.\n\n## Requirements\n\n- PHP \u003e= 7.4\n- JSON extension\n- [Composer](https://getcomposer.org)\n\n## Installation\n\nAdd the package to your `composer.json` file with the following command:\n\n```shell\ncomposer require mistralys/changelog-parser\n```\n\nAlso see the [Packagist page](https://packagist.org/packages/mistralys/changelog-parser).\n\n## Supported changelog formats\n\nThe parser expects all versions to be listed as headers with the same\nheader level, and individual changes to be added as a list. Both of \nthese examples will work:\n\n```markdown\n# v1.2.3\n- Made some changes\n\n# v1.2.2\n- Lotsa code changes\n- Added some documentation\n```\n\n```markdown\n### v1.2.3\n- Made some changes\n\n### v1.2.2\n- Lotsa code changes\n- Added some documentation\n```\n\n### Version heading formats\n\nAll the following headings are valid formats that the parser will recognize:\n\n```markdown\n# v1\n\n# v1.2\n\n# v1.2.3\n\n# 1\n\n# 1.2\n\n# 1.2.3\n\n# 1.2.3-ALPHA\n\n# 1.2.3-BranchName-SNAPSHOT\n\n# 5.0 - Optional version label\n\n# 5.0 | Optional version label\n\n# 5.0 ~ Optional version label\n```\n\nFor more information on the spectrum of version strings that can be used,\nhave a look at the supported formats in the [mistralys/version-parser](https://github.com/Mistralys/version-parser#supported-version-strings) \npackage, which is used to read them. \n\n### Nesting the changelog in a document\n\nThe way the parser analyzes the Markdown document means that the\nchangelog can be nested anywhere. The heading level will be inferred\nfrom the first version heading it encounters.\n\nIn this example, the changelog is not a separate document, but is\nnested in a subsection. \n\n```markdown\n# Application name\n\n## Usage\n\nLearn how to use the application with this documentation.\n\n## Change log\n\n### v1.2.3\n- Made some changes\n\n### v1.2.2\n- Lotsa code changes\n- Added some documentation\n\n## Credits\n\nMany people contributed to the application.\n```\n\n\u003e The changelog parser will stick to the first changelog it finds in\n\u003e the document, meaning that only the first of multiple, separate \n\u003e version lists will be used, even if they have the same heading level. \n\n### Subheaders within versions\n\nThe parser will recognize subheaders within a version entry, and add\ncollect these as plain text to be accessed again later. This makes it\npossible to further document things like breaking changes for example.\n\n```markdown\n# v2.0.0 - Complete rework (breaking)\n- Code entirely refurbished\n- Documentation rewritten\n\n## Breaking changes\n- Renamed all methods\n- Renamed all files\n```\n\nOnly the items below the version will be considered changes in the\nversion. The \"Breaking changes\" subheader and any additional content\nis captured as text, which can be accessed via `getFreeformText()`:\n\n```php\nuse Mistralys\\ChangelogParser\\ChangelogParser;\n\n$version = ChangelogParser::parseMarkdownFile('changelog.md')-\u003egetVersionByNumber('2.0.0');\n\necho $version-\u003egetFreeformText();\n```\n\nThis will output:\n\n```markdown\n## Breaking changes\n- Renamed all methods\n- Renamed all files\n```\n\n## Usage examples\n\n### Fetch all versions\n\n```php\nuse Mistralys\\ChangelogParser\\ChangelogParser;\n\n$versions = ChangelogParser::parseMarkdownFile('changelog.md')-\u003egetVersions();\n\nforeach($versions as $version)\n{\n    echo $version-\u003egetNumber().PHP_EOL;\n}\n```\n\n### Fetch the latest version\n\n```php\nuse Mistralys\\ChangelogParser\\ChangelogParser;\n\n$parser = ChangelogParser::parseMarkdownFile('changelog.md');\n\n$latest = $parser-\u003egetLatestVersion();\n```\n\n### Get a version by number\n\n```php\nuse Mistralys\\ChangelogParser\\ChangelogParser;\n\n$parser = ChangelogParser::parseMarkdownFile('changelog.md');\n\n$version = $parser-\u003egetVersionByNumber('5.2.0');\n```\n\nThis will throw an exception if the version is not found. To check if a\nversion number exists beforehand\n\n### Check if a version exists\n\n```php\nuse Mistralys\\ChangelogParser\\ChangelogParser;\n\n$parser = ChangelogParser::parseMarkdownFile('changelog.md');\n\nif($parser-\u003eversionExists('5.2.0'))\n{\n    $version = $parser-\u003egetVersionByNumber('5.2.0');\n}\n```\n\nNote that this requires the exact version number to be known (major, minor \nand patch version numbers). For a more flexible way to find versions, the \nversion info is best used instead. \n\nFor example, to find all versions matching `v4.2.x`:\n\n```php\nuse Mistralys\\ChangelogParser\\ChangelogParser;\n\n$versions = ChangelogParser::parseMarkdownFile('changelog.md')-\u003egetVersions();\n\nforeach($versions as $version)\n{\n    $info = $version-\u003egetVersionInfo();\n    \n    if($info-\u003egetMajorVersion() === 4 \u0026\u0026 $info-\u003egetMinorVersion() === 2) \n    {\n        // Matches v4.2\n    }\n}\n```\n\n### Go through individual changes in a version\n\n```php\nuse Mistralys\\ChangelogParser\\ChangelogParser;\n\n$version = ChangelogParser::parseMarkdownFile('changelog.md')-\u003erequireLatestVersion();\n\n$changes = $version-\u003egetChanges();\n\necho \"Changes in version \".$version-\u003egetNumber().\":\".PHP_EOL;\n\nforeach($changes as $change)\n{\n    echo '- '.$change-\u003egetText().PHP_EOL;\n}\n```\n\n\u003e Note the use of the `requireLatestVersion()` method: This will throw\n\u003e an exception instead of `NULL` if no versions are found in the \n\u003e change log. Handy to avoid checking for a null value.\n \n## Persisting and caching\n\nTo easily store or transmit changelog information, the parser offers the\npossibility to serialize the data to JSON. This can be decoded again later\ninstead of parsing the source file each time.\n\n```php\nuse Mistralys\\ChangelogParser\\ChangelogParser;\n\nif(!file_exists('changelog.json'))\n{\n    $changelog = ChangelogParser::parseMarkdownFile('changelog.md');\n    $changelog-\u003etoJSONFile('changelog.json');\n}\nelse\n{\n    $changelog = ChangelogParser::parseJSONFile('changelog.json');\n}\n```\n\nThis example will automatically create a JSON cache file, which performs\nbetter than parsing the source markdown file each time, especially for large\nfiles. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmistralys%2Fchangelog-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmistralys%2Fchangelog-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmistralys%2Fchangelog-parser/lists"}