CodeIgniter v4.5 API

Publisher extends FileCollection
in package

Application

Publishers read in file paths from a variety of sources and copy the files out to different destinations. This class acts both as a base for individual publication directives as well as the mode of discovery for said instances. In this class a "file" is a full path to a verified file while a "path" is relative to its source or destination and may indicate either a file or directory of unconfirmed existence.

Class failures throw the PublisherException, but some underlying methods may percolate different exceptions, like FileException, FileNotFoundException or InvalidArgumentException.

Write operations will catch all errors in the file-specific $errors property to minimize impact of partial batch operations.

Properties

$destination : string: Base path to use for the destination.
$files : array<int, string>: The current list of file paths.
$source : string: Base path to use for the source.
$discovered : array<string, array<int, self>|null>: Array of discovered Publishers.
$errors : array<string, Throwable>: Exceptions for specific files from the last write operation.
$published : array<int, string>: List of file published curing the last write operation.
$replacer : ContentReplacer
$restrictions : array<string, string>: List of allowed directories and their allowed files regex.
$scratch : string|null: Directory to use for methods that need temporary storage.

Methods

__construct() : mixed: Loads the helper and verifies the source and destination directories.
__destruct() : mixed: Cleans up any temporary files in the scratch space.
add() : $this: Adds an array/single file or directory to the list.
addDirectories() : $this: Verifies and adds files from each directory to the list.
addDirectory() : $this: Verifies and adds all files from a directory.
addFile() : $this: Verifies and adds a single file to the file list.
addFiles() : $this: Verifies and adds files to the list.
addLineAfter() : bool: Add line after the line with the string
addLineBefore() : bool: Add line before the line with the string
addPath() : $this: Adds a single path to the file list.
addPaths() : $this: Verifies and adds paths to the list.
addUri() : $this: Downloads a file from the URI, and adds it to the file list.
addUris() : $this: Downloads and stages files from an array of URIs.
copy() : bool: Copies all files into the destination, does not create directory structure.
count() : int: Returns the current number of files in the collection.
discover() : array<int, self>: Discovers and returns all Publishers in the specified namespace directory.
get() : array<int, string>: Optimizes and returns the current file list.
getDestination() : string: Returns the destination directory.
getErrors() : array<string, Throwable>: Returns errors from the last write operation if any.
getIterator() : Generator<string|int, File>: Yields as an Iterator for the current files.
getPublished() : array<int, string>: Returns the files published by the last write operation.
getScratch() : string: Returns the temporary workspace, creating it if necessary.
getSource() : string: Returns the source directory.
merge() : bool: Merges all files into the destination.
publish() : bool: Reads files from the sources and copies them out to their destinations.
removeFile() : $this: Removes a single file from the list.
removeFiles() : $this: Removes files from the list.
removePattern() : $this: Removes any files from the list that match the supplied pattern (within the optional scope).
replace() : bool: Replace content
retainPattern() : $this: Keeps only the files from the list that match (within the optional scope).
set() : $this: Sets the file list directly, files are still subject to verification.
wipe() : $this: Removes the destination and all its files and folders.
define() : void: Applies any initial inputs after the constructor.
filterFiles() : array<int, string>: Removes files that are not part of the given directory (recursive).
matchFiles() : array<int, string>: Returns any files whose `basename` matches the given pattern.
resolveDirectory() : string: Resolves a full path and verifies it is an actual directory.
resolveFile() : string: Resolves a full path and verifies it is an actual file.
safeCopyFile() : void: Copies a file with directory creation and identical file awareness.
verifyAllowed() : void: Verify this is an allowed file for its destination.
wipeDirectory() : void: Removes a directory and all its files and subdirectories.

$destination

Base path to use for the destination.


    protected
        string
    $destination
     = FCPATH

$files

The current list of file paths.


    protected
        array<int, string>
    $files
     = []

$source

Base path to use for the source.


    protected
        string
    $source
     = ROOTPATH

$discovered

Array of discovered Publishers.


    private
    static    array<string, array<int, self>|null>
    $discovered
     = []

$errors

Exceptions for specific files from the last write operation.


    private
        array<string, Throwable>
    $errors
     = []

$published

List of file published curing the last write operation.


    private
        array<int, string>
    $published
     = []

$replacer read-only


    private
        ContentReplacer
    $replacer

$restrictions read-only

List of allowed directories and their allowed files regex.


    private
        array<string, string>
    $restrictions

Restrictions are intentionally private to prevent overriding.

$scratch

Directory to use for methods that need temporary storage.


    private
        string|null
    $scratch
     = null

Created on-the-fly as needed.

__construct()

Loads the helper and verifies the source and destination directories.


    public
                    __construct([string|null $source = null ][, string|null $destination = null ]) : mixed

Parameters

$source : string|null = null
$destination : string|null = null

__destruct()

Cleans up any temporary files in the scratch space.


    public
                    __destruct() : mixed

add()

Adds an array/single file or directory to the list.


    public
                    add(array<int, string>|string $paths[, bool $recursive = true ]) : $this

Parameters

$paths : array<int, string>|string
$recursive : bool = true

Return values

$this

addDirectories()

Verifies and adds files from each directory to the list.


    public
                    addDirectories(array<int, string> $directories[, bool $recursive = false ]) : $this

Parameters

$directories : array<int, string>
$recursive : bool = false

Return values

$this

addDirectory()

Verifies and adds all files from a directory.


    public
                    addDirectory(string $directory[, bool $recursive = false ]) : $this

Parameters

$directory : string
$recursive : bool = false

Return values

$this

addFile()

Verifies and adds a single file to the file list.


    public
                    addFile(string $file) : $this

Parameters

$file : string

Return values

$this

addFiles()

Verifies and adds files to the list.


    public
                    addFiles(array<int, string> $files) : $this

Parameters

$files : array<int, string>

Return values

$this

addLineAfter()

Add line after the line with the string


    public
                    addLineAfter(string $file, string $line, string $after) : bool

Parameters

$file : string
$line : string
$after : string: String to search.

Return values

bool

addLineBefore()

Add line before the line with the string


    public
                    addLineBefore(string $file, string $line, string $before) : bool

Parameters

$file : string
$line : string
$before : string: String to search.

Return values

bool

addPath()

Adds a single path to the file list.


    public
        final            addPath(string $path[, bool $recursive = true ]) : $this

Parameters

$path : string
$recursive : bool = true

Return values

$this

addPaths()

Verifies and adds paths to the list.


    public
        final            addPaths(array<int, string> $paths[, bool $recursive = true ]) : $this

Parameters

$paths : array<int, string>
$recursive : bool = true

Return values

$this

addUri()

Downloads a file from the URI, and adds it to the file list.


    public
        final            addUri(string $uri) : $this

Parameters

$uri : string: Because HTTP\URI is stringable it will still be accepted

Return values

$this

addUris()

Downloads and stages files from an array of URIs.


    public
        final            addUris(array<int, string> $uris) : $this

Parameters

$uris : array<int, string>

Return values

$this

copy()

Copies all files into the destination, does not create directory structure.


    public
        final            copy([bool $replace = true ]) : bool

Parameters

$replace : bool = true: Whether to overwrite existing files.

Return values

bool —

Whether all files were copied successfully

count()

Returns the current number of files in the collection.


    public
                    count() : int

Fulfills Countable.

Return values

int

discover()

Discovers and returns all Publishers in the specified namespace directory.


    public
        final    static        discover([string $directory = 'Publishers' ]) : array<int, self>

Parameters

$directory : string = 'Publishers'

Return values

array<int, self>

get()

Optimizes and returns the current file list.


    public
                    get() : array<int, string>

Return values

array<int, string>

getDestination()

Returns the destination directory.


    public
        final            getDestination() : string

Return values

string

getErrors()

Returns errors from the last write operation if any.


    public
        final            getErrors() : array<string, Throwable>

Return values

array<string, Throwable>

getIterator()

Yields as an Iterator for the current files.


    public
                    getIterator() : Generator<string|int, File>

Fulfills IteratorAggregate.

Return values

Generator<string|int, File>

getPublished()

Returns the files published by the last write operation.


    public
        final            getPublished() : array<int, string>

Return values

array<int, string>

getScratch()

Returns the temporary workspace, creating it if necessary.


    public
        final            getScratch() : string

Return values

string

getSource()

Returns the source directory.


    public
        final            getSource() : string

Return values

string

merge()

Merges all files into the destination.


    public
        final            merge([bool $replace = true ]) : bool

Creates a mirrored directory structure only for files from source.

Parameters

$replace : bool = true: Whether to overwrite existing files.

Return values

bool —

Whether all files were copied successfully

publish()

Reads files from the sources and copies them out to their destinations.


    public
                    publish() : bool

This method should be reimplemented by child classes intended for discovery.

Return values

bool

removeFile()

Removes a single file from the list.


    public
                    removeFile(string $file) : $this

Parameters

$file : string

Return values

$this

removeFiles()

Removes files from the list.


    public
                    removeFiles(array<int, string> $files) : $this

Parameters

$files : array<int, string>

Return values

$this

removePattern()

Removes any files from the list that match the supplied pattern (within the optional scope).


    public
                    removePattern(string $pattern[, string|null $scope = null ]) : $this

Parameters

$pattern : string: Regex or pseudo-regex string
$scope : string|null = null: The directory to limit the scope

Return values

$this

replace()

Replace content


    public
                    replace(string $file, array<string|int, mixed> $replaces) : bool

Parameters

$file : string
$replaces : array<string|int, mixed>: [search => replace]

Return values

bool

retainPattern()

Keeps only the files from the list that match (within the optional scope).


    public
                    retainPattern(string $pattern[, string|null $scope = null ]) : $this

Parameters

$pattern : string: Regex or pseudo-regex string
$scope : string|null = null: A directory to limit the scope

Return values

$this

set()

Sets the file list directly, files are still subject to verification.


    public
                    set(array<int, string> $files) : $this

This works as a "reset" method with [].

Parameters

$files : array<int, string>: The new file list to use

Return values

$this

wipe()

Removes the destination and all its files and folders.


    public
        final            wipe() : $this

Return values

$this

define()

Applies any initial inputs after the constructor.


    protected
                    define() : void

This method is a stub to be implemented by child classes.

filterFiles()

Removes files that are not part of the given directory (recursive).


    protected
        final    static        filterFiles(array<int, string> $files, string $directory) : array<int, string>

Parameters

$files : array<int, string>
$directory : string

Return values

array<int, string>

matchFiles()

Returns any files whose `basename` matches the given pattern.


    protected
        final    static        matchFiles(array<int, string> $files, string $pattern) : array<int, string>

Parameters

$files : array<int, string>
$pattern : string: Regex or pseudo-regex string

Return values

array<int, string>

resolveDirectory()

Resolves a full path and verifies it is an actual directory.


    protected
        final    static        resolveDirectory(string $directory) : string

Parameters

$directory : string

Return values

string

resolveFile()

Resolves a full path and verifies it is an actual file.


    protected
        final    static        resolveFile(string $file) : string

Parameters

$file : string

Return values

string

safeCopyFile()

Copies a file with directory creation and identical file awareness.


    private
                    safeCopyFile(string $from, string $to, bool $replace) : void

Intentionally allows errors.

Parameters

$from : string
$to : string
$replace : bool

verifyAllowed()

Verify this is an allowed file for its destination.


    private
                    verifyAllowed(string $from, string $to) : void

Parameters

$from : string
$to : string

wipeDirectory()

Removes a directory and all its files and subdirectories.


    private
            static        wipeDirectory(string $directory) : void

Parameters

$directory : string

Publisher extends FileCollection in package Application

Table of Contents

Properties

Methods

Properties

$destination

$files

$source

$discovered

$errors

$published

$replacer read-only

$restrictions read-only

$scratch

Methods

__construct()

Parameters

__destruct()

add()

Parameters

Return values

addDirectories()

Parameters

Return values

addDirectory()

Parameters

Return values

addFile()

Parameters

Return values

addFiles()

Parameters

Return values

addLineAfter()

Parameters

Return values

addLineBefore()

Parameters

Return values

addPath()

Parameters

Return values

addPaths()

Parameters

Return values

addUri()

Parameters

Return values

addUris()

Parameters

Return values

copy()

Parameters

Return values

count()

Return values

discover()

Parameters

Return values

get()

Return values

getDestination()

Return values

getErrors()

Return values

getIterator()

Tags

Return values

getPublished()

Return values

getScratch()

Return values

getSource()

Return values

merge()

Parameters

Return values

publish()

Tags

Return values

Publisher extends FileCollection
in package

Application