README

This package offers a nice way to display change logs.

Thanks a lot to Grav CMS who let me use their design for the changelog modal. I use Grav myself and already replaced several Wordpress pages with it. Go check it out!

Installation

Using Composer

Call composer require syonix/changelog-viewer.

Manual installation

Download the project files and upload them to your web server. Include the class autoloader /vendor/autoload.php or configure your own autoloader.

Usage

To render a display, just call a factory function like this:

use \Syonix\ChangelogViewer\Factory\ViewerFactory;
ViewerFactory::createMarkdownHtmlViewer(__DIR__ . '/../CHANGELOG.md')->build();

Processors

Processors are the component of the library that reads the changelog file. Currently implemented is the MarkdownProcessor but you could add any of your own, as long as it implements the Processor\Processor Interface.

MarkdownProcessor

The MarkdownProcessor takes the path to a markdown file and returns an ArrayCollection containing instances of Version. The Markdown file must follow this scheme:

# Change Log
All notable changes to this project will be documented in this file.
This project adheres to [Semantic Versioning](http://semver.org/).

This header is optional but follows the Keep A Changelog recommendation.

## [v0.1.0](https://github.com/Syonix/changelog-viewer/releases/tag/v0.1.0) - 2016-01-23
[See full Changelog](https://github.com/Syonix/monolog-viewer/compare/v4.0.1...v4.0.2)

This is the version header. It contains the version string (adhering to Semantic Versioning) and a link where this release can be downloaded.

### New
- Initial release
- Modular concept to support different sources and outputs

Next are the labels New, Changed and Fixed. New is for new features, Changed is for existing features that have been improved and Fixed is for bugs that have been fixed. Under each label you have a list of changes that fall in this label (category).

This format can be overridden by setting a custom regex:

$processor = new MarkdownProcessor($path)
    ->setRegex(array(
            'version' => '/^## \[(v.+)\]\((.+)\) - ([\d-]+)/',
            'changes_url' => '/^\[See full Changelog\]\((.+)\)/',
            'label' => '/^### (.+)/',
            'change' => '/^- (.+)/',
        ));
(new HtmlFormatter($processor))->build();

Formatters

Formatters are used to display the change log. Currently there is only the HtmlFormatter which outputs the change log to HTML, but you could implement anything else.

HtmlFormatter

The HtmlFormatter prints nice HTML. You have several options for that:

(new HtmlFormatter($processor))
    ->title('Changelog')
    ->modal()
    ->frame(true)
    ->styles(true)
    ->scripts(true)
    ->downloadLinks(true)
    ->output();

Localization

If your changelog file is written in another language, you can use the LabelTranslator so the parser recognizes the labels. Refer to the German example for the structure:

{
  "new": "neu",
  "improved": "verbessert",
  "fixed": "behoben",
  "See full Changelog": "Vollständigen Changelog anzeigen"
}

Demo

After cloning or downloading the project, you can quickly launch a demo by running php -S localhost:8081 within the demo directory. Then just open your browser and visit localhost:8081.

syonix / changelog-viewer

Maintainers

Details