README

A parser for unified diff files, returning a hydrated object graph.

Uses __toString() to serialize back into unified diff format.

Install

Install with composer:

$ composer require ptlis/diff-parser

Usage

Parsing a diff file

Create a parser:

$parser = new \ptlis\DiffParser\Parser();

And then get a changeset from a file path:

$changeset = $parser->parseFile('path/to/git/diff', Parser::VCS_GIT);

or parse the patch data stored from a variable:

$changeset = $parser->parse($patchData, Parser::VCS_SVN);

Serialization

All the value classes implement the __toString() method to support direct serialization of that component back to unified diff format.

For example this serializes the data in $changeset into the file my.patch.

\file_put_contents('my.patch', $changeset);

The Object Graph

The tree built to store changesets is very simple, mapping one-to-one to the components of a diff file. In essence:

A Changeset is the root node & contains Files
A File contain Hunks
A Hunk contain Lines
Lines are the leaf nodes.

Changeset

From a Changeset you may iterate over the array of files that have changed:

foreach ($changeset->files as $file) {
    // $file is an instance of ptlis\DiffParser\File
}

File

Get the original and new filenames:

$file->filename->original;  // Eg 'readme.md' or '' (empty) on create
$file->filename->new;       // EG 'README.md' or '' (empty) on delete

Get the operation that was performed (create, delete or change):

$file->operation;   // One of File::CREATED, File::CHANGED, File::DELETED

From a file you may iterate over the change hunks:

foreach ($file->hunks as $hunk) {
    // $hunk is an instance of ptlis\DiffParser\Hunk
}

Hunk

Get the start line number of the hunk:

$hunk->startLine->original; // Eg '0'
$hunk->startLine->new;      // Eg '0'

Get the number of lines affected in the hunk:

$hunk->affectedLines->original; // Eg '5'
$hunk->affectedLines->new;      // Eg '7'

From a hunk you may iterate over the changed lines:

foreach ($hunk->lines as $line) {
    // $line is an instance of ptlis\DiffParser\Line
}

Line

Get the original and new line numbers:

$line->number->original;    // Eg '7' or '-1' on create
$line->number->new;         // Eg '7' or '-1' on delete

Get the operation:

$line->operation;   // One of Line::ADDED, Line::REMOVED, Line::UNCHANGED

Get the value of the line:

$line->content; // Eg ' $foo = bar;'

Contributing

You can contribute by submitting an Issue to the issue tracker, improving the documentation or submitting a pull request. For pull requests i'd prefer that the code style and test coverage is maintained, but I am happy to work through any minor issues that may arise so that the request can be merged.

ptlis / diff-parser

Maintainers

Details