BagItTools

Bag
in package

Bag class as normal interface for all actions and holder of supporting constructs.

Tags
author

whikloj

since
1.0.0

Table of Contents

BAG_INFO_GENERATED_ELEMENTS  = ['payload-oxum', 'bag-size', 'bagging-date']
Fields you can't set because we generate them on $bag->update().
BAG_INFO_MUST_NOT_REPEAT  = ['payload-oxum']
Bag-info fields that MUST not be repeated.
BAG_INFO_RESERVED_ELEMENTS  = ['source-organization', 'organization-address', 'contact-name', 'contact-phone', 'contact-email', 'external-description', 'bagging-date', 'external-identifier', 'payload-oxum', 'bag-size', 'bag-group-identifier', 'bag-count', 'internal-sender-identifier', 'internal-sender-description']
Reserved element names for Bag-info fields.
BAG_INFO_SHOULD_NOT_REPEAT  = ['bagging-date', 'bag-size', 'bag-group-identifer', 'bag-count']
Bag-info fields that SHOULD NOT be repeated.
BAGINFO_AUTOWRAP_GUESS_LENGTH  = 70
The length of a line over which we assume the line has been auto-wrapped.
BAGINFO_AUTOWRAP_START  = 77
Length we start trying to wrap at.
DEFAULT_BAGIT_VERSION  = ['major' => 1, 'minor' => 0]
The default bagit version.
DEFAULT_FILE_ENCODING  = 'UTF-8'
The default file encoding if one is not specified.
DEFAULT_HASH_ALGORITHM  = 'sha512'
The default algorithm to use if one is not specified.
HASH_ALGORITHMS  = array('md5' => 'md5', 'sha1' => 'sha1', 'sha224' => 'sha224', 'sha256' => 'sha256', 'sha384' => 'sha384', 'sha512' => 'sha512', 'sha3224' => 'sha3-224', 'sha3256' => 'sha3-256', 'sha3384' => 'sha3-384', 'sha3512' => 'sha3-512')
Array of BagIt approved names of hash algorithms to the PHP names of those hash algorithms for use with hash_file().
TAR_EXTENSIONS  = ['tar', 'tgz', 'tar.gz', 'tar.bz2']
Extensions which map to a tar file.
WINDOWS_PATH_CHARACTERS  = ['<', '>', ':', '"', '/', '|', '?', '*']
WINDOWS_RESERVED_NAMES  = ['CON', 'PRN', 'AUX', 'NUL', 'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9', 'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9']
File names that are not allowed on windows, should be disallowed in bags for interoperability.
ZIP_EXTENSIONS  = ['zip']
Extensions which map to a zip file.
$bagErrors  : array<string|int, mixed>
Errors when validating a bag.
$bagInfoData  : array<string|int, mixed>
Bag Info data.
$bagInfoTagIndex  : array<string|int, mixed>
Unique array of all Bag info tags/values. Tags are stored once in lower case with an array of all instances of values. This index does not save order.
$bagRoot  : string
The absolute path to the root of the bag, all other file paths are relative to this. This path is stored with / as directory separator regardless of the OS.
$bagWarnings  : array<string|int, mixed>
Warnings when validating a bag.
$changed  : bool
Have we changed the bag and not written it to disk?
$currentFileEncoding  : string
Current bag file encoding.
$currentVersion  : array<string|int, mixed>
Array of current bag version with keys 'major' and 'minor'.
$fetchFile  : Fetch
Reference to a Fetch file or null if not used.
$isExtended  : bool
Is this an extended bag?
$loaded  : bool
Did we load this from disk.
$packageExtensions  : array<string|int, mixed>
All the extensions in one array.
$payloadFiles  : array<string|int, mixed>
List of relative file paths for all files.
$payloadManifests  : array<string|int, mixed>
Array of payload manifests.
$tagManifests  : array<string|int, mixed>
Array of tag manifests.
$validHashAlgorithms  : array<string|int, mixed>
The valid algorithms from the current version of PHP filtered to those supported by the BagIt specification. Stored to avoid extraneous calls to hash_algos().
addAlgorithm()  : void
Add a hash algorithm to the bag.
addBagInfoTag()  : void
Add tag and value to bag-info.
addBagInfoTags()  : void
Add multiple bag info tags from an array.
addFetchFile()  : mixed
Add a file to your fetch file.
addFile()  : void
Add a file to the bag.
algorithmIsSupported()  : bool
The algorithm is supported.
checkForEmptyDir()  : void
Check the directory we just deleted a file from, if empty we should remove it too.
clearFetch()  : void
Wipe the fetch file data
create()  : Bag
Static function to create a new Bag
createFile()  : void
Add a string as a file to the bag.
decodeText()  : string
Utility function to convert text to UTF-8
encodeText()  : string
Utility function to convert text back to the encoding for the file.
finalize()  : void
This does cleanup functions related to packaging, for example deleting downloaded files referenced in fetch.txt
getAlgorithms()  : array<string|int, mixed>
Get the currently active payload (and tag) manifests.
getBagInfoByTag()  : array<string|int, mixed>
Find all instances of tag and return an array of values.
getBagInfoData()  : array<string|int, mixed>
Return raw bag info data.
getBagRoot()  : string
Return path to the bag root.
getDataDirectory()  : string
Return path to the data directory.
getErrors()  : array<string|int, mixed>
Get errors on the bag.
getFileEncoding()  : string
Get current file encoding or default if not specified.
getHashName()  : string
Return the BagIt sanitized algorithm name.
getPayloadManifests()  : array<string|int, mixed>
Get the payload manifests as an associative array with hash algorithm as key.
getTagManifests()  : array<string|int, mixed>|null
Get the tag manifests as an associative array with hash algorithm as key.
getVersion()  : array<string|int, mixed>
Get the current version array or default if not specified.
getVersionString()  : string
Get current version as string.
getWarnings()  : array<string|int, mixed>
Get any warnings related to the bag.
hasAlgorithm()  : bool
Do we have this hash algorithm already?
hasBagInfoTag()  : bool
Case-insensitive search of bag-info tags.
isExtended()  : bool
Check the bag's extended status.
isValid()  : bool
Is the bag valid as it appears on disk.
listFetchFiles()  : array<string|int, mixed>
Return the fetch file data, an array of arrays with keys 'url', 'destination' and (optionally) 'size'.
load()  : Bag
Static constructor to load an existing bag.
makeAbsolute()  : string
Add the bag root to the front of a relative bag path and return with OS directory separator.
makeRelative()  : string
Remove all the extraneous path information and make relative to bag root.
package()  : void
Package a bag up into an archive.
pathInBagData()  : bool
Is the path inside the payload directory?
removeAlgorithm()  : void
Remove a hash algorithm from the bag.
removeBagInfoTag()  : void
Remove ALL instances of tag.
removeBagInfoTagIndex()  : void
Removes a specific entry for a tag by the array index. This can be determined using the index in the array returned by getBagInfoByKey().
removeBagInfoTagValue()  : void
Remove a specific entry for a tag by the tag value.
removeFetchFile()  : void
Delete a line from the fetch file.
removeFile()  : void
Remove a payload file.
setAlgorithm()  : void
Replaces any existing hash algorithms with the one requested.
setAlgorithms()  : void
Replaces any existing hash algorithms with the ones requested.
setExtended()  : void
Turn extended bag features on or off.
setFileEncoding()  : void
Set the file encoding.
update()  : void
Write the updated BagIt files to disk.
upgrade()  : void
Upgrade an older bag to comply with the 1.0 specification.
validate()  : bool
Validate the bag as it appears on disk.
__construct()  : mixed
Bag constructor.
addBagError()  : void
Utility function to add bag error.
addBagInfoTagsInternal()  : void
Internal function adding the values to the various tag arrays.
addBagWarning()  : void
Utility function to add bag error.
arrayKeyExistsNoCase()  : bool
Case-insensitive version of array_key_exists
bagInfoTagExists()  : bool
Internal case insensitive search of bag info.
calculateTotalFileSizeAndAmountOfFiles()  : array<string|int, mixed>|null
Calculate the total file size and amount of files of all payload files.
clearFilesOfPattern()  : void
Utility to remove files using a pattern.
clearPayloadManifests()  : void
Remove all manifest files.
clearTagManifests()  : void
Remove all tagmanifest files.
compareVersion()  : int
Compare the provided version against the current one.
convertToHumanReadable()  : string
Convert given byte value to a human readable value.
createNewBag()  : void
Create a new bag and output the default parts.
determineHashFromFilename()  : string|null
Parse manifest/tagmanifest file names to determine hash algorithm.
ensureTagManifests()  : void
Utility to setup tag manifests.
extensionTarCompression()  : string|null
Determine the correct compression (if any) from the extension.
extractDir()  : string
Generate a temporary directory name.
filterPhpHashAlgorithms()  : bool
Check if the algorithm PHP has is allowed by the specification.
getDirectory()  : string
Locate the extracted bag directory from inside our temporary directory.
getParentDir()  : string
Get the parent directory of the current Bag.
hasExtension()  : bool
Retrieve whether the given filepath has one of the extensions
hasHash()  : bool
Do we have a payload manifest with this internal hash name. Internal use only to avoid getHashName()
hashIsSupported()  : bool
Is the internal named hash supported by our PHP. Internal use only to avoid getHashName()
internalPath()  : string
Convert paths from using the OS directory separator to using /.
isCompressed()  : bool
Test a filepath to see if we think it is compressed.
loadBag()  : void
Load a bag from disk.
loadBagInfo()  : bool
Read in the bag-info.txt file.
loadBagIt()  : void
Load the bagit.txt on disk.
loadFetch()  : void
Load a fetch.txt if it exists.
loadPayloadManifests()  : void
Load all payload manifests found on disk.
loadTagManifests()  : bool
Load all tag manifests (if any).
makePackage()  : void
Create an archive file of the current bag.
makeTar()  : void
Create a Tar archive.
makeZip()  : void
Create a Zip archive.
mergeErrors()  : void
Utility to merge manifest and fetch errors into the bag errors.
mergeWarnings()  : void
Utility to merge manifest and fetch warnings into the bag warnings.
mustNotRepeatBagInfoExists()  : bool
Check that the key is not non-repeatable and already in the bagInfo.
normalizeHashAlgorithmName()  : void
Normalize a PHP hash algorithm to a BagIt specification name. Used to alter the incoming $item.
removeAllPayloadManifests()  : void
Remove payload manifests.
removeAllTagManifests()  : void
Remove tag manifests.
removeBagInfo()  : void
Remove the bag-info.txt file and data.
removePayloadManifest()  : void
Remove a single payload manifest.
removeTagManifest()  : void
Remove a single tag manifest.
reservedFilename()  : bool
Is the requested destination filename reserved on Windows?
resetErrorsAndWarnings()  : void
On new bag or load bag or update we need to refresh these containers.
setAlgorithmsInternal()  : void
Internal utility to remove all algorithms not specified and add any missing.
shouldNotRepeatBagInfoExists()  : bool
Check that the key is not non-repeatable and already in the bagInfo.
trimLower()  : string
Return a trimmed and lowercase version of text.
trimSpacesOnly()  : string
Just trim spaces NOT newlines and carriage returns.
uncompressBag()  : string
Uncompress a BagIt archive file.
untarBag()  : string
Untar a tar file.
unzipBag()  : string
Unzip a zip file.
updateBagInfo()  : void
Write the contents of the bag-info array to disk.
updateBagInfoIndex()  : void
Generate a faster index of Bag-Info tags.
updateBagIt()  : void
Update the bagit.txt on disk.
updateCalculateBagInfoFields()  : void
Update the calculated bag-info fields
updateFetch()  : void
Update a fetch.txt if it exists.
updatePayloadManifests()  : void
Run update against the payload manifests.
updateTagManifests()  : void
Run update against the tag manifests.
wrapAtLength()  : array<string|int, mixed>
Utility to remove newline characters, wrap the string and return an array of the rows.
wrapBagInfoText()  : array<string|int, mixed>
Wrap bagInfo lines to 79 characters if possible

Constants

BAG_INFO_GENERATED_ELEMENTS

Fields you can't set because we generate them on $bag->update().

private mixed BAG_INFO_GENERATED_ELEMENTS = ['payload-oxum', 'bag-size', 'bagging-date']

BAG_INFO_MUST_NOT_REPEAT

Bag-info fields that MUST not be repeated.

private mixed BAG_INFO_MUST_NOT_REPEAT = ['payload-oxum']

BAG_INFO_RESERVED_ELEMENTS

Reserved element names for Bag-info fields.

private mixed BAG_INFO_RESERVED_ELEMENTS = ['source-organization', 'organization-address', 'contact-name', 'contact-phone', 'contact-email', 'external-description', 'bagging-date', 'external-identifier', 'payload-oxum', 'bag-size', 'bag-group-identifier', 'bag-count', 'internal-sender-identifier', 'internal-sender-description']

BAG_INFO_SHOULD_NOT_REPEAT

Bag-info fields that SHOULD NOT be repeated.

private mixed BAG_INFO_SHOULD_NOT_REPEAT = ['bagging-date', 'bag-size', 'bag-group-identifer', 'bag-count']

BAGINFO_AUTOWRAP_GUESS_LENGTH

The length of a line over which we assume the line has been auto-wrapped.

private mixed BAGINFO_AUTOWRAP_GUESS_LENGTH = 70

BAGINFO_AUTOWRAP_START

Length we start trying to wrap at.

private mixed BAGINFO_AUTOWRAP_START = 77

DEFAULT_BAGIT_VERSION

The default bagit version.

private mixed DEFAULT_BAGIT_VERSION = ['major' => 1, 'minor' => 0]

DEFAULT_FILE_ENCODING

The default file encoding if one is not specified.

private mixed DEFAULT_FILE_ENCODING = 'UTF-8'

DEFAULT_HASH_ALGORITHM

The default algorithm to use if one is not specified.

private mixed DEFAULT_HASH_ALGORITHM = 'sha512'

HASH_ALGORITHMS

Array of BagIt approved names of hash algorithms to the PHP names of those hash algorithms for use with hash_file().

private array<string|int, mixed> HASH_ALGORITHMS = array('md5' => 'md5', 'sha1' => 'sha1', 'sha224' => 'sha224', 'sha256' => 'sha256', 'sha384' => 'sha384', 'sha512' => 'sha512', 'sha3224' => 'sha3-224', 'sha3256' => 'sha3-256', 'sha3384' => 'sha3-384', 'sha3512' => 'sha3-512')
Tags
see
https://tools.ietf.org/html/rfc8493#section-2.4

TAR_EXTENSIONS

Extensions which map to a tar file.

private mixed TAR_EXTENSIONS = ['tar', 'tgz', 'tar.gz', 'tar.bz2']

WINDOWS_PATH_CHARACTERS

private mixed WINDOWS_PATH_CHARACTERS = ['<', '>', ':', '"', '/', '|', '?', '*']

WINDOWS_RESERVED_NAMES

File names that are not allowed on windows, should be disallowed in bags for interoperability.

private mixed WINDOWS_RESERVED_NAMES = ['CON', 'PRN', 'AUX', 'NUL', 'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9', 'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9']

ZIP_EXTENSIONS

Extensions which map to a zip file.

private mixed ZIP_EXTENSIONS = ['zip']

Properties

$bagErrors

Errors when validating a bag.

private array<string|int, mixed> $bagErrors

$bagInfoData

Bag Info data.

private array<string|int, mixed> $bagInfoData = []

$bagInfoTagIndex

Unique array of all Bag info tags/values. Tags are stored once in lower case with an array of all instances of values. This index does not save order.

private array<string|int, mixed> $bagInfoTagIndex = []

$bagRoot

The absolute path to the root of the bag, all other file paths are relative to this. This path is stored with / as directory separator regardless of the OS.

private string $bagRoot

$bagWarnings

Warnings when validating a bag.

private array<string|int, mixed> $bagWarnings

$changed

Have we changed the bag and not written it to disk?

private bool $changed = false

$currentFileEncoding

Current bag file encoding.

private string $currentFileEncoding = self::DEFAULT_FILE_ENCODING

$currentVersion

Array of current bag version with keys 'major' and 'minor'.

private array<string|int, mixed> $currentVersion = self::DEFAULT_BAGIT_VERSION

$fetchFile

Reference to a Fetch file or null if not used.

private Fetch $fetchFile = null

$isExtended

Is this an extended bag?

private bool $isExtended = false

$loaded

Did we load this from disk.

private bool $loaded

$packageExtensions

All the extensions in one array.

private array<string|int, mixed> $packageExtensions

$payloadFiles

List of relative file paths for all files.

private array<string|int, mixed> $payloadFiles

$payloadManifests

Array of payload manifests.

private array<string|int, mixed> $payloadManifests

$tagManifests

Array of tag manifests.

private array<string|int, mixed> $tagManifests

$validHashAlgorithms

The valid algorithms from the current version of PHP filtered to those supported by the BagIt specification. Stored to avoid extraneous calls to hash_algos().

private array<string|int, mixed> $validHashAlgorithms

Methods

addAlgorithm()

Add a hash algorithm to the bag.

public addAlgorithm(string $algorithm) : void
Parameters
$algorithm : string

Algorithm to add.

Tags
throws
BagItException

Asking for an unsupported algorithm.

Return values
void —

addBagInfoTag()

Add tag and value to bag-info.

public addBagInfoTag(string $tag, string $value) : void
Parameters
$tag : string

The tag to add.

$value : string

The value to add.

Tags
throws
BagItException

When you try to set an auto-generated tag value.

Return values
void —

addBagInfoTags()

Add multiple bag info tags from an array.

public addBagInfoTags(array<string|int, mixed> $tags) : void
Parameters
$tags : array<string|int, mixed>

Associative array of tag => value

Tags
throws
BagItException

When you try to set an auto-generated tag value.

Return values
void —

addFetchFile()

Add a file to your fetch file.

public addFetchFile(string $url, string $destination[, null|int $size = null ]) : mixed
Parameters
$url : string

The source URL.

$destination : string

The destination path in the bag.

$size : null|int = null

Size of the file to be stored in the fetch file, if desired.

Tags
throws
BagItException

On errors adding the file.

Return values
mixed —

addFile()

Add a file to the bag.

public addFile(string $source, string $dest) : void
Parameters
$source : string

Full path to the source file.

$dest : string

Relative path for the destination.

Tags
throws
BagItException

Source file does not exist or the destination is outside the data directory.

throws
FilesystemException

Issues writing to the filesystem.

Return values
void —

algorithmIsSupported()

The algorithm is supported.

public algorithmIsSupported(string $algorithm) : bool
Parameters
$algorithm : string

The requested hash algorithm

Return values
bool —

Whether it is supported by our PHP.

checkForEmptyDir()

Check the directory we just deleted a file from, if empty we should remove it too.

public checkForEmptyDir(string $path) : void
Parameters
$path : string

The file just deleted.

Return values
void —

clearFetch()

Wipe the fetch file data

public clearFetch() : void
Tags
throws
FilesystemException

Issues deleting files/directories from the filesystem.

Return values
void —

create()

Static function to create a new Bag

public static create(string $rootPath) : Bag
Parameters
$rootPath : string

Path to the new bag, must not exist

Tags
throws
BagItException

If we can't create the directory.

Return values
Bag —

The bag.

createFile()

Add a string as a file to the bag.

public createFile(string $string, string $dest) : void
Parameters
$string : string

The contents of the file.

$dest : string

The name of the file in the bag.

Tags
throws
BagItException

Source file does not exist or the destination is outside the data directory.

throws
FilesystemException

Issues creating/deleting temporary file.

Return values
void —

decodeText()

Utility function to convert text to UTF-8

public decodeText(string $text) : string
Parameters
$text : string

The source text.

Return values
string —

The converted text.

encodeText()

Utility function to convert text back to the encoding for the file.

public encodeText(string $text) : string
Parameters
$text : string

The source text.

Return values
string —

The converted text.

finalize()

This does cleanup functions related to packaging, for example deleting downloaded files referenced in fetch.txt

public finalize() : void
Tags
throws
FilesystemException

Issues deleting files from filesystem.

Return values
void —

getAlgorithms()

Get the currently active payload (and tag) manifests.

public getAlgorithms() : array<string|int, mixed>
Return values
array<string|int, mixed> —

Internal hash names for current manifests.

getBagInfoByTag()

Find all instances of tag and return an array of values.

public getBagInfoByTag(string $tag) : array<string|int, mixed>
Parameters
$tag : string

Bag info tag to locate

Return values
array<string|int, mixed> —

Array of values for the tag.

getBagInfoData()

Return raw bag info data.

public getBagInfoData() : array<string|int, mixed>
Return values
array<string|int, mixed> —

Bag Info data.

getBagRoot()

Return path to the bag root.

public getBagRoot() : string
Return values
string —

The bag root path.

getDataDirectory()

Return path to the data directory.

public getDataDirectory() : string
Return values
string —

The bag data directory path.

getErrors()

Get errors on the bag.

public getErrors() : array<string|int, mixed>
Return values
array<string|int, mixed> —

The errors.

getFileEncoding()

Get current file encoding or default if not specified.

public getFileEncoding() : string
Return values
string —

Current file encoding.

getHashName()

Return the BagIt sanitized algorithm name.

public static getHashName(string $algorithm) : string
Parameters
$algorithm : string

A algorithm name

Return values
string —

The sanitized version of algorithm or an empty string if invalid.

getPayloadManifests()

Get the payload manifests as an associative array with hash algorithm as key.

public getPayloadManifests() : array<string|int, mixed>
Return values
array<string|int, mixed> —

hash algorithm => Payload manifests

getTagManifests()

Get the tag manifests as an associative array with hash algorithm as key.

public getTagManifests() : array<string|int, mixed>|null
Return values
array<string|int, mixed>|null —

hash algorithm => Tag manifests or null if not an extended bag.

getVersion()

Get the current version array or default if not specified.

public getVersion() : array<string|int, mixed>
Return values
array<string|int, mixed> —

Current version.

getVersionString()

Get current version as string.

public getVersionString() : string
Return values
string —

Current version in M.N format.

getWarnings()

Get any warnings related to the bag.

public getWarnings() : array<string|int, mixed>
Return values
array<string|int, mixed> —

The warnings.

hasAlgorithm()

Do we have this hash algorithm already?

public hasAlgorithm(string $hashAlgorithm) : bool
Parameters
$hashAlgorithm : string

The requested hash algorithms.

Return values
bool —

Do we already have this payload manifest.

hasBagInfoTag()

Case-insensitive search of bag-info tags.

public hasBagInfoTag(string $tag) : bool
Parameters
$tag : string

Bag info tag to locate

Return values
bool —

Does the tag exist.

isExtended()

Check the bag's extended status.

public isExtended() : bool
Return values
bool —

Does the bag use extended features?

isValid()

Is the bag valid as it appears on disk.

public isValid() : bool
Tags
throws
BagItException

Problems writing to disk.

Return values
bool —

True if the bag is valid

listFetchFiles()

Return the fetch file data, an array of arrays with keys 'url', 'destination' and (optionally) 'size'.

public listFetchFiles() : array<string|int, mixed>
Return values
array<string|int, mixed> —

load()

Static constructor to load an existing bag.

public static load(string $rootPath) : Bag
Parameters
$rootPath : string

Path to the existing bag.

Tags
throws
BagItException

If we can't read files in the bag.

Return values
Bag —

The bag object.

makeAbsolute()

Add the bag root to the front of a relative bag path and return with OS directory separator.

public makeAbsolute(string $path) : string
Parameters
$path : string

The relative path.

Return values
string —

The absolute path.

makeRelative()

Remove all the extraneous path information and make relative to bag root.

public makeRelative(string $path) : string
Parameters
$path : string

The absolute path to process

Return values
string —

The shortened path or blank if it is outside bag root.

package()

Package a bag up into an archive.

public package(string $filepath) : void
Parameters
$filepath : string

The full path to create the archive at.

Tags
throws
BagItException

Problems creating the archive.

Return values
void —

pathInBagData()

Is the path inside the payload directory?

public pathInBagData(string $filepath) : bool
Parameters
$filepath : string

The internal path.

Return values
bool —

Path is inside the data/ directory.

removeAlgorithm()

Remove a hash algorithm from the bag.

public removeAlgorithm(string $algorithm) : void
Parameters
$algorithm : string

Algorithm to remove

Tags
throws
BagItException

Trying to remove the last algorithm or asking for an unsupported algorithm.

Return values
void —

removeBagInfoTag()

Remove ALL instances of tag.

public removeBagInfoTag(string $tag) : void
Parameters
$tag : string

The tag to remove.

Return values
void —

removeBagInfoTagIndex()

Removes a specific entry for a tag by the array index. This can be determined using the index in the array returned by getBagInfoByKey().

public removeBagInfoTagIndex(string $tag, int $index) : void
Parameters
$tag : string

The tag to remove.

$index : int

The index of the value to remove.

Return values
void —

removeBagInfoTagValue()

Remove a specific entry for a tag by the tag value.

public removeBagInfoTagValue(string $tag, string $value[, bool $case_sensitive = true ]) : void
Parameters
$tag : string

The tag we are removing a value of.

$value : string

The value to remove from the above tag.

$case_sensitive : bool = true

Whether to perform a case-sensitive match.

Return values
void —

removeFetchFile()

Delete a line from the fetch file.

public removeFetchFile(string $url) : void
Parameters
$url : string

The url to delete.

Tags
throws
FilesystemException

Problems deleting the file.

Return values
void —

removeFile()

Remove a payload file.

public removeFile(string $dest) : void
Parameters
$dest : string

The relative path of the file.

Tags
throws
FilesystemException

Issues deleting the file.

Return values
void —

setAlgorithm()

Replaces any existing hash algorithms with the one requested.

public setAlgorithm(string $algorithm) : void
Parameters
$algorithm : string

Algorithm to use.

Tags
throws
FilesystemException

Problems removing/reading/

throws
BagItException

Asking for an unsupported algorithm.

Return values
void —

setAlgorithms()

Replaces any existing hash algorithms with the ones requested.

public setAlgorithms(array<string|int, mixed> $algorithms) : void
Parameters
$algorithms : array<string|int, mixed>

Array of algorithms to use.

Tags
throws
FilesystemException

Problems removing/reading/creating the new payload/tag manifest files.

throws
BagItException

If an unsupported algorithm is provided.

Return values
void —

setExtended()

Turn extended bag features on or off.

public setExtended(bool $extBag) : void
Parameters
$extBag : bool

Whether the bag should be extended or not.

Return values
void —

setFileEncoding()

Set the file encoding.

public setFileEncoding(string $encoding) : void
Parameters
$encoding : string

The MIME name of the character set to encode with.

Tags
throws
BagItException

If we don't support the requested character set.

Return values
void —

update()

Write the updated BagIt files to disk.

public update() : void
Tags
throws
FilesystemException

Errors with writing files to disk.

Return values
void —

upgrade()

Upgrade an older bag to comply with the 1.0 specification.

public upgrade() : void
Tags
throws
BagItException

If the bag cannot be upgraded for some reason.

throws
FilesystemException

Issues writing files to the filesystem.

Return values
void —

validate()

Validate the bag as it appears on disk.

public validate() : bool
Tags
throws
BagItException

If problems updating the bag.

deprecated
4.1.0

Name change of same function to better signify the boolean response

see
Bag::isValid()
codeCoverageIgnore
Return values
bool —

True if bag is valid.

__construct()

Bag constructor.

private __construct(string $rootPath[, bool $new = true ]) : mixed
Parameters
$rootPath : string

The path of the root of the new or existing bag.

$new : bool = true

Are we making a new bag?

Tags
throws
FilesystemException

Problems accessing a file.

throws
BagItException

Bag directory exists for new bag or various issues for loading an existing bag.

Return values
mixed —

addBagError()

Utility function to add bag error.

private addBagError(string $filename, string $message) : void
Parameters
$filename : string

The file the error was detected in.

$message : string

The message.

Return values
void —

addBagInfoTagsInternal()

Internal function adding the values to the various tag arrays.

private addBagInfoTagsInternal(array<string|int, mixed> $tags) : void
Parameters
$tags : array<string|int, mixed>

Associative array of tag => value

Return values
void —

addBagWarning()

Utility function to add bag error.

private addBagWarning(string $filename, string $message) : void
Parameters
$filename : string

The file the error was detected in.

$message : string

The message.

Return values
void —

arrayKeyExistsNoCase()

Case-insensitive version of array_key_exists

private static arrayKeyExistsNoCase(string $search, string|int $key, array<string|int, mixed> $map) : bool
Parameters
$search : string

The key to look for.

$key : string|int

The associative or numeric key to look in.

$map : array<string|int, mixed>

The associative array to search.

Return values
bool —

True if the key exists regardless of case.

bagInfoTagExists()

Internal case insensitive search of bag info.

private bagInfoTagExists(string $internal_tag) : bool
Parameters
$internal_tag : string

Trimmed and lowercase tag.

Return values
bool —

Does it exist in the index.

calculateTotalFileSizeAndAmountOfFiles()

Calculate the total file size and amount of files of all payload files.

private calculateTotalFileSizeAndAmountOfFiles() : array<string|int, mixed>|null
Return values
array<string|int, mixed>|null —

The total file size and amount of all files or null if we couldn't read all the file sizes.

clearFilesOfPattern()

Utility to remove files using a pattern.

private clearFilesOfPattern(string $filePattern) : void
Parameters
$filePattern : string

The file pattern.

Tags
throws
FilesystemException

Problems matching or deleting files.

Return values
void —

clearPayloadManifests()

Remove all manifest files.

private clearPayloadManifests() : void
Tags
throws
FilesystemException

Errors with glob() pattern.

Return values
void —

clearTagManifests()

Remove all tagmanifest files.

private clearTagManifests() : void
Tags
throws
FilesystemException

Errors with glob() pattern or deleting files from filesystem.

Return values
void —

compareVersion()

Compare the provided version against the current one.

private compareVersion(string $version) : int
Parameters
$version : string

The version to compare against.

Return values
int —

returns -1 $version < current, 0 $version == current, and 1 $version > current.

convertToHumanReadable()

Convert given byte value to a human readable value.

private convertToHumanReadable(int $bytes) : string
Parameters
$bytes : int

Value in bytes

Return values
string —

createNewBag()

Create a new bag and output the default parts.

private createNewBag() : void
Tags
throws
BagItException

If the bag root directory already exists.

throws
FilesystemException

Problems writing to the filesystem.

Return values
void —

determineHashFromFilename()

Parse manifest/tagmanifest file names to determine hash algorithm.

private static determineHashFromFilename(string $filepath) : string|null
Parameters
$filepath : string

the filename.

Return values
string|null —

the hash or null.

ensureTagManifests()

Utility to setup tag manifests.

private ensureTagManifests() : void
Return values
void —

extensionTarCompression()

Determine the correct compression (if any) from the extension.

private static extensionTarCompression(string $filename) : string|null
Parameters
$filename : string

The filename.

Return values
string|null —

The compression string or null for no compression.

extractDir()

Generate a temporary directory name.

private static extractDir() : string
Tags
throws
FilesystemException

Issues creating/deleting files on filesystem.

Return values
string —

The path to a new temporary directory.

filterPhpHashAlgorithms()

Check if the algorithm PHP has is allowed by the specification.

private static filterPhpHashAlgorithms(string $item) : bool
Parameters
$item : string

A hash algorithm name.

Return values
bool —

True if allowed by the specification.

getDirectory()

Locate the extracted bag directory from inside our temporary directory.

private static getDirectory(string $filepath) : string
Parameters
$filepath : string

The temporary directory.

Tags
throws
BagItException

Find more or less than one directory (not including . and ..)

Return values
string —

The bag directory.

getParentDir()

Get the parent directory of the current Bag.

private getParentDir() : string
Return values
string —

The parent directory.

hasExtension()

Retrieve whether the given filepath has one of the extensions

private static hasExtension(string $filepath, array<string|int, mixed> $extensions) : bool
Parameters
$filepath : string

The full file path.

$extensions : array<string|int, mixed>

The list of extensions to check.

Return values
bool —

The list of extensions or an empty array.

hasHash()

Do we have a payload manifest with this internal hash name. Internal use only to avoid getHashName()

private hasHash(string $internal_name) : bool
Parameters
$internal_name : string

Internal name from getHashName.

Return values
bool —

Already have this algorithm.

hashIsSupported()

Is the internal named hash supported by our PHP. Internal use only to avoid getHashName()

private hashIsSupported(string $internal_name) : bool
Parameters
$internal_name : string

Output of getHashName

Tags
see
Bag::getHashName()
Return values
bool —

Do we support the algorithm

internalPath()

Convert paths from using the OS directory separator to using /.

private internalPath(string $path) : string
Parameters
$path : string

The external path.

Return values
string —

The modified path.

isCompressed()

Test a filepath to see if we think it is compressed.

private static isCompressed(string $filepath) : bool
Parameters
$filepath : string

The full path

Return values
bool —

True if compressed file (we support).

loadBag()

Load a bag from disk.

private loadBag() : void
Tags
throws
BagItException

If a file cannot be read.

Return values
void —

loadBagInfo()

Read in the bag-info.txt file.

private loadBagInfo() : bool

To support newlines in bag-info.txt any line that is less than 70 characters will have the newline at the end maintained. Otherwise, the newline is considered an auto-wrap and is removed to not interfere with the text.

Tags
throws
FilesystemException

Unable to read bag-info.txt

Return values
bool —

Does bag-info.txt exists.

loadBagIt()

Load the bagit.txt on disk.

private loadBagIt() : void
Tags
throws
FilesystemException

Can't read the file on disk.

Return values
void —

loadFetch()

Load a fetch.txt if it exists.

private loadFetch() : void
Tags
throws
FilesystemException

Unable to read fetch.txt for existing bag.

Return values
void —

loadPayloadManifests()

Load all payload manifests found on disk.

private loadPayloadManifests() : void
Tags
throws
FilesystemException

Problems with glob() pattern

throws
BagItException

Invalid algorithm detected.

Return values
void —

loadTagManifests()

Load all tag manifests (if any).

private loadTagManifests() : bool
Tags
throws
FilesystemException

Problems with glob() pattern or loading manifest.

Return values
bool —

Are there any tag manifest files.

makePackage()

Create an archive file of the current bag.

private makePackage(string $filename) : void
Parameters
$filename : string

The archive filename.

Tags
throws
FilesystemException

Problems creating the archive.

throws
BagItException

Unable to determine archive format.

Return values
void —

makeTar()

Create a Tar archive.

private makeTar(string $filename) : void
Parameters
$filename : string

The archive filename.

Tags
throws
FilesystemException

Problems creating the archive.

Return values
void —

makeZip()

Create a Zip archive.

private makeZip(string $filename) : void
Parameters
$filename : string

The archive filename.

Tags
throws
FilesystemException

Problems creating the archive.

Return values
void —

mergeErrors()

Utility to merge manifest and fetch errors into the bag errors.

private mergeErrors(array<string|int, mixed> $newErrors) : void
Parameters
$newErrors : array<string|int, mixed>

The new errors to be added.

Return values
void —

mergeWarnings()

Utility to merge manifest and fetch warnings into the bag warnings.

private mergeWarnings(array<string|int, mixed> $newWarnings) : void
Parameters
$newWarnings : array<string|int, mixed>

The new warnings to be added.

Return values
void —

mustNotRepeatBagInfoExists()

Check that the key is not non-repeatable and already in the bagInfo.

private static mustNotRepeatBagInfoExists(string $key, array<string|int, mixed> $bagData) : bool
Parameters
$key : string

The key being added.

$bagData : array<string|int, mixed>

The current bag data.

Return values
bool —

True if the key is non-repeatable and already in the

normalizeHashAlgorithmName()

Normalize a PHP hash algorithm to a BagIt specification name. Used to alter the incoming $item.

private static normalizeHashAlgorithmName(string &$item) : void
Parameters
$item : string

The hash algorithm name.

Return values
void —

removeAllPayloadManifests()

Remove payload manifests.

private removeAllPayloadManifests([array<string|int, mixed> $exclusions = [] ]) : void
Parameters
$exclusions : array<string|int, mixed> = []

Hash algorithm names of manifests to preserve.

Tags
throws
FilesystemException

Issues deleting a file.

Return values
void —

removeAllTagManifests()

Remove tag manifests.

private removeAllTagManifests([array<string|int, mixed> $exclusions = [] ]) : void
Parameters
$exclusions : array<string|int, mixed> = []

Hash algorithm names of manifests to preserve.

Tags
throws
FilesystemException

Issues deleting files from the filesystem.

Return values
void —

removeBagInfo()

Remove the bag-info.txt file and data.

private removeBagInfo() : void
Tags
throws
FilesystemException

Unable to delete the bag-info.txt file.

Return values
void —

removePayloadManifest()

Remove a single payload manifest.

private removePayloadManifest(string $internal_name) : void
Parameters
$internal_name : string

The hash name to remove.

Tags
throws
FilesystemException

Issues deleting the payload manifest file.

Return values
void —

removeTagManifest()

Remove a single tag manifest.

private removeTagManifest(string $internal_name) : void
Parameters
$internal_name : string

The hash name to remove.

Tags
throws
FilesystemException

Problems deleting the tag manifest file.

Return values
void —

reservedFilename()

Is the requested destination filename reserved on Windows?

private reservedFilename(string $filepath) : bool
Parameters
$filepath : string

The relative filepath.

Return values
bool —

True if a reserved filename.

resetErrorsAndWarnings()

On new bag or load bag or update we need to refresh these containers.

private resetErrorsAndWarnings() : void
Return values
void —

setAlgorithmsInternal()

Internal utility to remove all algorithms not specified and add any missing.

private setAlgorithmsInternal(array<string|int, mixed> $algorithms) : void
Parameters
$algorithms : array<string|int, mixed>

Array of algorithms using their internal names.

Tags
throws
FilesystemException

Errors

Return values
void —

shouldNotRepeatBagInfoExists()

Check that the key is not non-repeatable and already in the bagInfo.

private static shouldNotRepeatBagInfoExists(string $key, array<string|int, mixed> $bagData) : bool
Parameters
$key : string

The key being added.

$bagData : array<string|int, mixed>

The current bag data.

Return values
bool —

True if the key is non-repeatable and already in the

trimLower()

Return a trimmed and lowercase version of text.

private static trimLower(string $text) : string
Parameters
$text : string

The original text.

Return values
string —

The lowercase trimmed text.

trimSpacesOnly()

Just trim spaces NOT newlines and carriage returns.

private static trimSpacesOnly(string $text) : string
Parameters
$text : string

The original text

Return values
string —

The text with surrounding spaces trimmed away.

uncompressBag()

Uncompress a BagIt archive file.

private static uncompressBag(string $filepath) : string
Parameters
$filepath : string

The full path to the archive file.

Tags
throws
FilesystemException

Problems accessing and/or uncompressing files on filesystem.

throws
BagItException

Unable to determine correct archive format or file does not exist.

Return values
string —

The full path to extracted bag.

untarBag()

Untar a tar file.

private static untarBag(string $filename) : string
Parameters
$filename : string

The fullpath to the tar file.

Tags
throws
FilesystemException

Problems extracting the zip file.

Return values
string —

The path the archive file was extracted to.

unzipBag()

Unzip a zip file.

private static unzipBag(string $filename) : string
Parameters
$filename : string

The full path to the zip file.

Tags
throws
FilesystemException

Problems extracting the zip file.

Return values
string —

The path the archive file was extracted to.

updateBagInfo()

Write the contents of the bag-info array to disk.

private updateBagInfo() : void
Tags
throws
FilesystemException

Issues writing the file to disk.

Return values
void —

updateBagInfoIndex()

Generate a faster index of Bag-Info tags.

private updateBagInfoIndex() : void
Return values
void —

updateBagIt()

Update the bagit.txt on disk.

private updateBagIt() : void
Tags
throws
FilesystemException

Issues putting contents to the file.

Return values
void —

updateCalculateBagInfoFields()

Update the calculated bag-info fields

private updateCalculateBagInfoFields() : void
Return values
void —

updateFetch()

Update a fetch.txt if it exists.

private updateFetch() : void
Tags
throws
FilesystemException
Return values
void —

updatePayloadManifests()

Run update against the payload manifests.

private updatePayloadManifests() : void
Tags
throws
FilesystemException

Issues deleting payload manifest files.

Return values
void —

updateTagManifests()

Run update against the tag manifests.

private updateTagManifests() : void
Tags
throws
FilesystemException

Issues deleting the tag manifest files.

Return values
void —

wrapAtLength()

Utility to remove newline characters, wrap the string and return an array of the rows.

private static wrapAtLength(string $text, int $length) : array<string|int, mixed>
Parameters
$text : string

The text to wrap.

$length : int

The length to wrap at.

Return values
array<string|int, mixed> —

Rows of text.

wrapBagInfoText()

Wrap bagInfo lines to 79 characters if possible

private static wrapBagInfoText(string $text) : array<string|int, mixed>
Parameters
$text : string

The whole tag and value as one.

Return values
array<string|int, mixed> —

The text as an array.

Search results