cstuder / temporal-shelf
Shelve files in directory structure according to years/months/days
Requires (Dev)
- mikey179/vfsstream: 1.6.8
- phpunit/phpunit: ^9
README
PHP package to shelve files in directory structures according to years/months/days.
I.e. takes a file data.txt
and copies it to ..../archive/2020/11/09/1604953664_data.txt
.
Created for usage on api.existenz.ch and indirectly on Aare.guru. As of 2020 in productive use.
Installation
composer require cstuder/temporal-shelf
Example usage
<?php require('vendor/autoload.php'); $shelf = new \cstuder\TemporalShelf\TemporalShelf($targetDirectory); $shelvedFilename = $shelf->shelveFile($filename);
See docs/example.php
for a full working example.
Documentation
The temporal-shelf
library copies files into a shelf (a file archive). A shelf is a directory structure with the default path containing current year, month and day. Additionally the file gets a prefix containing the current timestamp.
I.e.: The file download.txt
is shelved to /archive/2020/10/21/1603308783_download.txt
.
The directory structure is generated automatically, with permissions 0755
set.
Both path ($directoryPattern
) and prefix ($prefixPattern
) can be configured with a string which is then passed through the PHP DateTime::format method.
Example: Setting $directoryPattern = "Y/W"
and $prefixPattern = "N_"
would shelve the file to /archive/2020/43/3_download.txt
(Generating a weekly directory per year).
By default will throw an exceptionn when a file is already exists in the shelve with the same target name. This can be configured with the OverwriteOptions
values.
Exceptions are thrown when the file is not readable, when the directory structure cannot be built or if the copying fails.
Files are copied. The original file is left untouched and has to be cleaned up by yourself.
The library is intentionally kept simple and doesn't handle non-alphabetical directory or file prefix patterns well. Also keep the shelf directory unpolluted by other files.
__construct(string $shelfDirectory, string $directoryPattern = 'Y/m/d', string $filePrefixPattern = 'U_', string $timezone = 'UTC', int $overwriteOption = Options\OverwriteOptions::EXCEPTION_ON_OVERWRITE)
Creates the TemporalShelf object and sets the configuration.
$shelfDirectory
is the target archive directory root.
$directoryPattern
is the pattern of the subdirectories where the files are to be sorted in.
$filePrefixPattern
is the prefix added to the filename when shelving. Set it to ''
in order to disable the prefixing.
$timezone
is a timezone identifier used when converting the timestamp of the file to the directory path.
$overwriteOption
determines the behaviour when the target filename already exists in the shelf directory.
Does not validate the shelf directory.
shelveFile($filename, int $timestamp = null): string
Shelves a file with the current configuration and an optional timestamp. If the timestamp is null, takes the current time.
Returns the full path to the shelved file.
findAllShelvedFiles(int $sortOrder = Options\SortOrderOptions::ASCENDING): array
Returns an array of paths to all files in the shelf directory. All files, not just shelved files.
$sortOrder
determines the order of the array (ASCENDING|DESCENDING
).
findFreshestFile(): ?string
Returns the path to the freshest file on the shelf. Returns null
if no file is found.
Shortcut for findAllShelvedFiles(Options\SortOrderOptions::DESCENDING)[0]
.
Testing
Run composer test
to execute the PHPUnit test suite.
Releasing
- Add changes to the changelog.
- Create a new tag
vX.X.X
. - Push.
License
MIT.
Author
Christian Studer cstuder@existenz.ch, Bureau für digitale Existenz.