README

Transparent, protocol independent, local and remote file system operations.

Abstract virtual-file-system-like behavior across local file systems and remote protocols. With a syntax analogue to FTP-clients (put, get) depage-fs makes PHP stream wrappers easily accessible and provides a unified user interface.

Usage follows a local-remote paradigm where 'local' means the actual current working directory and 'remote' can be another local directory or a directory on a remote system.

depage-fs virtually tracks the remote working directory (cd, pwd). Once the remote path is set, it prevents any operations in parent directories.

Requirements

PHP 8.3 or later. The ftp(s) protocol needs the curl extension, the ssh protocol the ssh2 extension.

Features

List of operations

pwd, ls, lsDir, lsFiles, exists, fileInfo, cd, mkdir, rm, mv, get, put, getString, putString

Protocols

local, ftp(s), ssh (authentication by password or key)

Example

File transfer, local to remote

$fs = Fs::factory('ftp://user:pass@host/');

$fs->mkdir('new/path');
$fs->cd('new/path');
$fs->put('file.zip');

First, get the SSH fingerprint...

$fs = Fs::factory('ssh://host');
$print = $fs->getFingerprint();

then connect with SSH key

$params = array(
    'user'              => 'user',
    'pass'              => 'pass',
    'privateKeyFile'    => '.ssh/id_rsa',
    'fingerprint'       => $print,
    'tmp'               => '.'
);

$fs = Fs::factory('ssh://host', $params);
$fs->get('/home/user/file.zip');

Notes on usage

depage-fs error handler converts any file system operation errors/warnings to exceptions. The problem causing them may be in a location different to the one stated in the exception.
!!! Important in FTPS !!! If the server does not support SSL, then the connection falls back to regular unencrypted FTP. Currently there is no way to make sure the connection is encrypted. Susceptible to MITM attacks!
SSH keys need to be PEM-formatted (base64).
SSH keys can be strings or files. However, internally php requires key files (for some strange reason, both public and private). The files are automatically generated (and subsequently deleted) in a temporary directory specified by the 'tmp'-parameter.

Testing

The test suite needs an ssh server and an ftp server as remote targets.

Locally this runs in docker: a phpunit runner container and a mock server container (vsftpd + sshd), connected through a docker network. Requires docker with the compose plugin.

make -C Tests test        # build images, start mock server, run phpunit
make -C Tests server      # only start the mock server (for debugging)
make -C Tests clean       # remove containers, volumes and test artifacts

On CI (GitHub Actions) the same services are provisioned directly on the runner by Tests/ci/setup-services.sh (no docker), which allows testing a matrix of php versions (8.3, 8.4, 8.5) in parallel.

Only Tests/FtpCurlErrorTest.php and the local tests run without those servers:

vendor/bin/phpunit --configuration Tests/PHPUnit.xml --filter FtpCurlErrorTest

PHP compatibility

phpcs.xml.dist checks the code against the PHPCompatibility standard for the php range depage-fs supports (keep testVersion in sync with the php requirement in composer.json):

vendor/bin/phpcs -p         # checks the range from phpcs.xml.dist

Tests/PHPUnit.xml sets failOnDeprecation, so a php deprecation (e.g. one introduced by a new php version in the matrix) fails the test run instead of only being counted in the summary.

depage / fs

Package info

Security

Statistics