README

Path Hasher

Description

Path Hasher is a PHP library for deterministically hashing filesystem objects (files, directories, and symlinks) in a reproducible and platform-independent way.

The library provides two implementations:

• NAR: Serializes and hashes paths using the Nix ARchive (NAR) format, as used in the Nix ecosystem. See chapter 5 of Eelco Dolstra’s PhD thesis for technical details about the NAR format.
• SWHID: Computes SWHID (Software Heritage persistent identifiers) for files, directories, and symlinks, following the Software Heritage specification.

With this library, you can:

• Hash any filesystem path in a deterministic way (NAR, SWHID).
• Extract or reconstruct filesystem trees from NAR archives (NAR)

Installation

composer require loophp/path-hasher

Usage

NAR Example

<?php

use Loophp\PathHasher\NAR;

$path = '/path/to/your/file_or_directory';

$hash = (new NAR())->hash($path);

echo $hash; // Outputs the SRI hash (e.g., sha256-<base64>)

nix hash path /path/to/your/file_or_directory

<?php

use Loophp\PathHasher\NAR;

$nar = new NAR();

$handle = fopen('vendor.nar', 'w');
foreach ($nar->stream('./vendor') as $chunk) {
    fwrite($handle, $chunk);
}
fclose($handle);

Methods available are:

• hash: Compute the SRI hash of a given path.
• extract: Extract a NAR archive to a specified directory.
• stream: Get a stream generator of the NAR archive.
• computeHashes: Compute hashes of the NAR archive with different algorithms.

SWHID Example

<?php

use Loophp\PathHasher\SWHID;

$path = '/path/to/your/file_or_directory';

// Compute the SWHID for a file, directory, or symlink
$swhid = (new SWHID())->hash($path);

echo $swhid; // Outputs e.g. swh:1:cnt:<sha1> or swh:1:dir:<sha1>```

Note:

• The SWHID implementation only supports the "cnt" (content) and "dir" (directory) object types, which correspond to files, symlinks, and directories on the filesystem.
• Higher-level SWHID types ("rel" for release, "rev" for revision, "snp" for snapshot) are not supported by this implementation yet.

Methods available are:

• hash: Compute the SWHID of a given path.
• stream: Get a stream generator of the SWHID archive.

Code quality, tests, benchmarks

Every time changes are introduced into the library, Github runs the tests.

The library has tests written with PHPUnit. Feel free to check them out in the tests directory.

Before each commit, some inspections are executed with GrumPHP; run composer grumphp to check manually.

Contributing

Feel free to contribute by sending pull requests. We are a usually very responsive team and we will help you going through your pull request from the beginning to the end.

For some reasons, if you can't contribute to the code and willing to help, sponsoring is a good, sound and safe way to show us some gratitude for the hours we invested in this package.

Sponsor me on Github and/or any of the contributors.