Download the PHP package ardabeyazoglu/php-retention without Composer

php-retention

A simple but handy php library to apply retention policy to files before deleting, archiving or anything that is possible with a custom callback. A typical example would be backup archiving based on custom policies such as "keep last 7 daily, 2 weekly and 3 monthly backups".

Features

• Apply hourly, daily, weekly, monthly and yearly policies
• Customize prune action to do something else instead of deleting (e.g. move them to cloud)
• Customize file finder logic (e.g. support different storage interfaces such as S3)
• Grouping files (e.g. prune multiple files together instead of a single file)
• Dry runnable
• Logger aware (PSR-3)
• No dependencies other than the PSR-3 logger interface (psr/log)

Install

composer require ardabeyazoglu/php-retention

Test

composer test

Usage

Policy Configuration

This library is inspired by Restic's policy model. Policy configuration without understanding how it works might be misleading. Please read the explanation to understand how each keep-*** parameter works.

keep-last: keep the most recent N files. (default: 1)
keep-hourly: for the last N hours which have one or more files, keep only the most recent one for each hour.
keep-daily: for the last N days which have one or more files, keep only the most recent one for each day.
keep-weekly: for the last N weeks which have one or more files, keep only the most recent one for each week.
keep-monthly: for the last N months which have one or more files, keep only the most recent one for each month.
keep-yearly: for the last N years which have one or more files, keep only the most recent one for each year.

Examples

1. Custom Finder

By default, it will scan target directory non-recursively and apply retention policy to each file or directory in the target directory. This will be okay for local files, mounted partitions and when using stream wrappers external storage protocols. In all other cases, a custom finder logic must be implemented to detect files to apply retention.

2. Custom Time Parser

By default, it will check posix modification time of files to detect date and time information. It can be overriden by using a custom function, to resolve a different date value. Can be handy for reading date information from a custom file name format.

NOTE: This will be only called when using default finder logic. If you are writing your own findHandler, that function is responsible for giving a valid list of files with a valid date info.

3. Custom Prune Action

Pruning action is by default unlink for files and rmdir for empty directories. It can be customized to call different delete functions or to do something else other than deleting.

4. Grouping Files to Prune Together

Let's assume the directory contains multiple backup files for the same date but for different purposes. They can be grouped by using regexp to apply the same retention to altogether.

# example:
/backup/tenant/mysql-20240106.tar.gz
/backup/tenant/files-20240106.tar.gz
/backup/tenant/mysql-20240107.tar.gz
/backup/tenant/files-20240107.tar.gz

Without the following function, a "keep-last=1" policy will prune only the first file. By grouping them based on date, it will prune first two files together.

Contribution

Feel free to post an issue if you encounter a bug or you want to implement a new feature. Please be descriptive in your posts.

ToDo

• [ ] Add keep-within-*** policy support