whikloj / bagittools
A PHP library to manipulate and verify BagIt bags.
Installs: 13 293
Dependents: 1
Suggesters: 0
Security: 0
Stars: 11
Watchers: 6
Forks: 5
Open Issues: 4
Requires
- php: >=7.3
- ext-curl: *
- ext-intl: *
- ext-mbstring: *
- ext-zip: *
- pear/archive_tar: ^1.4.14
- symfony/console: ^5.4
Requires (Dev)
- donatj/mock-webserver: ^2.6
- phpstan/phpstan: ^1.4
- phpunit/phpunit: ^9.0
- sebastian/phpcpd: ^6.0
- squizlabs/php_codesniffer: ^3.5
README
Introduction
BagItTools is a PHP implementation of the BagIt v1.0 specification (RFC-8493).
Features:
- Create new bag
- Load existing directory as a bag.
- Load archive file (*.zip, *.tar, *.tar.gz, *.tgz, *.tar.bz2)
- Validate a bag
- Add/Remove files
- Add/Remove fetch urls
- Add/Remove hash algorithms (md5, sha1, sha224, sha256, sha384, sha512, sha3-224, sha3-256, sha3-384, sha3-512)
- Generate payload for all data/ files for all hash algorithms (depending on PHP support)
- Generate tag manifests for all root level files and any additional tag directories/files.
- Add/Remove tags from bag-info.txt files, maintains ordering of tags loaded.
- Generates/updates payload-oxum and bagging-date.
- Passes all bagit-conformance-suite tests.
- Create an archive (zip, tar, tar.gz, tgz, tar.bz2)
- In-place upgrade of bag from v0.97 to v1.0
Installation
Composer
composer require "whikloj/bagittools"
Clone from Github
git clone https://github.com/whikloj/BagItTools
cd BagItTools
composer install --no-dev
Dependencies
All dependencies are installed or identified by composer.
Some PHP extensions are required and this library will not install if they cannot be found in the default PHP installation (the one used by composer).
The required extensions are:
Usage
You can integrate BagItTools into your own code as a library using the API, or use the CLI commands for some simple functionality.
Command line
Validating a bag
./bin/console validate <path to bag>
This will output a message as to whether the bag is or is NOT valid. It will also respond with an appropriate exit code (0 == valid, 1 == invalid).
If you add the -v
flag it will also print any errors or warnings.
This can command can be used with the bagit-conformance-suite like this
./test-harness <path to BagItTools>/bin/console -- -v validate
API
Create a new bag
As this is a v1.0 implementation, by default bags created use the UTF-8 file encoding and the SHA-512 hash algorithm.
require_once './vendor/autoload.php'; use \whikloj\BagItTools\Bag; $dir = "./newbag"; // Create new bag as directory $dir $bag = Bag::create($dir); // Add a file $bag->addFile('../README.md', 'data/documentation/myreadme.md'); // Add another algorithm $bag->addAlgorithm('sha1'); // Get the algorithms $algos = $bag->getAlgorithms(); var_dump($algos); // array( // 'sha512', // 'sha1', // ) // Add a fetch url $bag->addFetchFile('http://www.google.ca', 'data/mywebsite.html'); // Add some bag-info tags $bag->addBagInfoTag('Contact-Name', 'Jared Whiklo'); $bag->addBagInfoTag('CONTACT-NAME', 'Additional admins'); // Check for tags. if ($bag->hasBagInfoTag('contact-name')) { // Get tags $tags = $bag->getBagInfoByTag('contact-name'); var_dump($tags); // array( // 'Jared Whiklo', // 'Additional admins', // ) // Remove a specific tag value using array index from the above listing. $bag->removeBagInfoTagIndex('contact-name', 1); // Get tags $tags = $bag->getBagInfoByTag('contact-name'); var_dump($tags); // array( // 'Jared Whiklo', // ) $bag->addBagInfoTag('Contact-NAME', 'Bob Saget'); // Get tags $tags = $bag->getBagInfoByTag('contact-name'); var_dump($tags); // array( // 'Jared Whiklo', // 'Bob Saget', // ) // Without the case sensitive flag as true, you must be exact. $bag->removeBagInfoTagValue('contact-name', 'bob saget'); $tags = $bag->getBagInfoByTag('contact-name'); var_dump($tags); // array( // 'Jared Whiklo', // 'Bob Saget', // ) // With the case sensitive flag set to false, you can be less careful $bag->removeBagInfoTagValue('contact-name', 'bob saget', false); $tags = $bag->getBagInfoByTag('contact-name'); var_dump($tags); // array( // 'Jared Whiklo', // ) // Remove all values for the specified tag. $bag->removeBagInfoTag('contact-name'); } // Write bagit support files (manifests, bag-info, etc) $bag->update(); // Write the bag to the specified path and filename using the expected archiving method. $bag->package('./archive.tar.bz2');
Maintainer
License
Development
To-Do:
- CLI interface to handle simple bag CRUD (CReate/Update/Delete) functions.