spoova / enlist

v2.5.0 2023-07-08 07:36 UTC

MIT

• Akinola Saheed

Published on Packagist.org on 2023-07-08 07:46 UTC

README

Enlist lists and renames files in a directory. It can change file names, extensions, and numbering, but it is not a file-conversion tool. Use view() before a real rename and inspect the result before changing files.

Installation

composer require spoova/enlist

require_once 'vendor/autoload.php';

use Spoova\Enlist\Enlist;
use Spoova\Enlist\Enlisted;

$enlist = new Enlist;

Select a source

source(string $path, string|array $filters = '*') selects a directory and returns the same Enlist instance. Check sourceValid() before listing or renaming.

$enlist->source(__DIR__.'/images', ['jpg', 'png']);

if ($enlist->sourceValid()) {
   $files = $enlist->dirFiles();
}

The selector is case-insensitive. Supported formats are:

Selector	Meaning
*	All non-hidden files, with or without extensions
*.	All non-hidden files having an extension
.	All hidden files
.name	Hidden files whose extension is name
#	Files with no extension
#name	The named file with no extension
#name.	The named file with an extension
jpg	Non-hidden files with the jpg extension

Selectors may be supplied as an array, for example ['jpg', 'png'], ['.', 'jpg'], or ['#README', '*.']. Conflicting selectors are rejected and can be inspected with error().

filters() returns the normalized filters supplied to source(). dirFiles($extension = [], $fullpath = false) lists matching files; its optional filter is independent of the source filter.

Rename files

$enlist->source(__DIR__.'/images', 'jpg');
$enlist->prefix('photo-')->reNumber()->startFrom(10);
$enlist->reSpace('_')->smartUrl();

$result = $enlist->rename('png');

rename(true) keeps each file's extension. rename('png') assigns a new extension. prefix($prefix, $strict = false) adds a prefix, reNumber(true) numbers files, and reNumber(Closure $callback) allows custom numbering logic. startFrom(0) starts at 1; reSpace() replaces spaces with _, and accepts - as the other replacement character.

Use view() to calculate the same destinations without changing the filesystem. View mode tracks simulated destinations, so collisions within the planned rename are reported consistently.

$enlist->source(__DIR__.'/images', '*')->view();
$planned = $enlist->rename();

The second rename() argument receives the resulting path map by reference. A third argument accepts a callback that receives an Enlisted proxy for each candidate file:

$enlist->rename('jpg', $result, function (Enlisted $file): void {
   if ($file->name() === 'skip.jpg') {
      $file->avert();
      return;
   }

   $file->setFileName('processed-'.$file->candidateIndex());
   $file->after(function (Enlisted $file): void {
      // Runs after this candidate has been processed.
   });
});

The Enlisted proxy provides file(), name(), newFile(), newName(), presumedFile(), fileExt(), files(), count(), status(), loopIndex(), candidateIndex(), renamedIndex(), done(), isView(), isRenamed(), selected(), isAverted(), badName(), identical(), and exists(). setFileName() accepts a filename stem and automatically de-duplicates repeated names. cleanFileName() converts internal dots to hyphens while preserving the final extension.

Ignored paths

ignoredPaths() excludes exact files or directories from operations that use the reference resolver. Paths are normalized before comparison.

$enlist->ignoredPaths([
   __DIR__.'/images/.keep',
   __DIR__.'/images/archive',
]);

Sessions and reversal

Use withSession() to store successful rename pairs in PHP session storage, then reverse() to restore them.

$enlist->source(__DIR__.'/images')
   ->withSession('enlist-renames')
   ->prefix('backup-');

$enlist->rename();
$enlist->reverse($reversed);

reverse($reversed, $sessionName) can target a named session store. Existing destination files are not overwritten during reversal.

Results and errors

data(&$data) copies the most recent result from dirFiles(), rename(), or reverse(). error() returns the most recent error. Enable debug() before processing to collect traces with debugs(), or use debug(2) to throw an ErrorException when an error is recorded.

$enlist->debug();
$enlist->source(__DIR__.'/images')->view()->rename('png', $result);

$enlist->debugs($errors);

Method summary

source(), sourceValid(), filters(), dirFiles(), prefix(), startFrom(), reSpace(), smartUrl(), reNumber(), view(), rename(), ignoredPaths(), withSession(), reverse(), data(), error(), debug(), and debugs() are the public Enlist methods. resolveFiles() and resolveDirectories() are protected extension points for derived classes.