FolderShare REST Release Notes

New features:

Date/time stamps on files are always preserved on upload and download.

Previously, the -p option was required to preserve date/time stamps.

The upload and download -u option is now a synonym for --sync.

Previously, the --sync option was a synonym for -pu. But with -p no longer needed, --sync and -u are now equivalent.

A "/" is no longer required at the start of all remote paths.

Remote paths without a leading "/" automatically refer to the user's home folder.

Upload and download progress messages show more detail on file sizes.

Previously file sizes were converted to KB, MB, GB, or TB and truncated to a whole number. Now a single digit after the decimal is included.

Bugs fixed:

Upload and download are confused by file/folder names using special characters, such as *, +, (, or ).

Fixed. File/folder names were inadvertantly passed to a function that treated special characters as part of a regular expression.

Upload sync always uploads image files, even when they haven't changed, but it properly skips non-image files that haven't changed.

Fixed. Uploaded images were not properly detected on sync and were therefore re-uploaded.

Upload sync uploads into FOLDER the first time, then into FOLDER/FOLDER for all further runs.

Fixed. Upload did not correctly detect and re-use a named remote FOLDER during non-first upload syncs.

Removed features:

The upload and download -p option is deprecated.

Previously, the -p option was required to preserve date/time stamps. This is now the default behavior and the option is no longer needed.

New features:

On module install, the module checks that PHP ZIP support is installed.

The module may use ZIP to uncompress downloaded multi-file content.

On module install, the module checks that FolderShare 1.3 is installed.

The module requires the 8.x-1.3 version of FolderShare due to API changes.

Bugs fixed:

Functions deprecated in Drupal 8.8 should not be called.

Fixed.

New features:

REST resource API calls to FolderShare updated to use new methods.

The FolderShare module renamed some file-handling APIs to use more consistent and descriptive naming. This module has been updated to use the new APIs.

"no overwrite" forms of file upload now supported.

The "new-rootfile-no-overwrite" and "new-file-no-overwrite" REST protocol messages create new files without overwriting existing files. The new files have a unique sequence number attached (e.g. "myfile-1.txt", "myfile-2.txt").

Last modified date passed on file upload and folder create.

The file and folder upload REST protocol messages now support a "Last-modified" HTTP header that contains the last modified date to use for the newly created file or folder. This may be used to keep local and remote content in sync by tracking modification dates.

Bugs fixed:

Domain names and port numbers are not being validated.

Invalid domain names and port numbers could be entered, such as by entering "http://example.com" instead of "example.com". Because the domain name was not validated, this erroneous syntax floated down into the underlying CURL where it cause changes in the way CURL issued requests. Domain names and port numbers are now validated and erroneous syntax generates an error.

Download to a new file fails with a creation error.

Local file path parsing and testing was incorrect and failed when a download was supposed to create an explicitly named destination file. This has been fixed.

Download file paths handled oddly.

Remote and local file path parsing was not robust. This has been improved.

Error messages not written to STDERR.

Error messages are now written to STDERR.

Paths are not being normalized on the client.

File paths that contain multiple adjacent "/"s or a trailing "/" are not normalized. While they can be handled on the server, normalizing them (and validating their structure) on the client allows for a faster turn-around when the user has entered something incorrectly.

Upload file paths handled oddly.

Remote and local file path parsing was not robust. This has been improved.

User names and passwords not being validated.

User names and passwords have a required length and structure for Drupal. Rather than send malformed user names and passwords to the server and await its error response, these are now validated in the client to have the right structure. Only if correctly formatted are they sent to the server, which could still reject them for being an unknown user name or bad password.

Changes:

FolderShareConnect::download() now has a $flags argument to control downloading.

The method downloads the indicated file or folder. The optional $flags argument is a bitmask that selects special download behaviors. Those behaviors control overwriting of existing local files, setting downloaded files and folders to use the remote item's timestamp, and updating local files only if remote files are newer. See the API documentation for more details.

FolderShareConnect::download() now downloads folders one descendant at a time.

Previously, downloading a remote folder caused that folder to be ZIPped and then downloaded. This could take a long time or fail when remote files and folders were large and it prevented the new update behaviorthat downloads files only if they have changed. The new download gets files and folders as needed, recursing through remote folders. The downloaded content is not ZIPped.

FolderShareConnect::download() and FolderShareConnect::upload() rewritten to have more robust local and remote file path handling.

Upload and download follow the similar semantics of a Linux/BSD/macOS cp command, so they support a variety of local and remote file path forms. This has been rewritten to improve its robustness and the variety of forms allowed.

FolderShareConnect::getFileOrFolder() now has a $recurse argument to recurse through folders.

The original method returned information about a single remote file or folder. This behavior remains when the new $recurse argument is FALSE. When TRUE, the method recurses downwards through folders and returns the indicated item and all its descendants in an array.

FolderShareConnect::upload() now has a $flags argument to control downloading.

The method uploads the indicated file or folder. The optional $flags argument is a bitmask that selects special upload behaviors. Those behaviors control overwriting of existing remote files, setting uploaded files and folders to use the local item's timestamp, and updating remote files only if local files are newer. See the API documentation for more details.

Client API packaged into a ZIP file.

The client API files are included in the module distribution. Previously they were individual PHP files in a "src" directory. This was confusing because the files are not needed except when building custom clients. These files are now packaged into a ZIP file.

New features:

All Linux/BSD/macOS command-like functionality moved to the new FolderShareCommands class

The functions to implement each of the client's Linux/BSD/macOS-like commands have been moved out of main's global name space and into the new FolderShareCommands class as public static methods.

All arguments for remote paths with "path" in the name have been renamed to use "uri".

Remote file or folder paths are URIs that may include a scheme ("personal" or "private") and user name or ID prefix. To reflect this, all arguments that refer to remote paths and used "path" in the argument name have been renamed with "uri" as the name. The functionality remains the same.

REST client splitPath() moved to FolderShareConnect::parseUri()

The function to parse remote file or folder URIs has been renamed and moved out of main's global name space and into the FolderShareConnect class as a public static method.

REST client normalizePath() and normalizePaths() moved to FolderShareConnect::normalizeUri() and FolderShareConnect:normalizeUris()

The functions to normalize remote file or folder URIs by removing redundant slashes have moved out of main's global name space and into the FolderShareConnect class as a public static methods.

Bugs fixed:

ls -t should sort by modification time with most recent first, but it has the reverse order.

Sorting has been fixed.

ls -R (recursive list) skips some folders.

Recursion accidentally overwrote an internal list of what subfolders to continue onwards and list. This truncated the recursion and skipped some folders.

Changes:

sync command renamed to wait.

The command waits for remote copies or moves to complete, so it has been renamed.

New features:

chown (change owner) command added.

For administrator users, the command changes the ownership of a file or folder.

download -n added.

The "-n" option prevents a download from overwriting an existing local file. Instead it will automatically add a unique sequence number. For example, if file "A.txt" is downloaded but there is already a local file with that name, the download will go into "A-2.txt".

download -p added.

The "-p" option preserves timestamps by setting the modification and access time of downloaded files and folders to match the modification time on the remote item. Without the option, downloaded files and folders have the current date as the modification time. This optional has the same affect as on the Linux/BSD/macOS cp command.

download -u added.

The "-u" option updates local files only if the remote file is newer or if the local file or folder does not exist. This should be used together with the "-p" option to insure that local files have comparable timestamps. This optional has the same affect as on the Linux/BSD/macOS cp command.

download -v shows download progress.

Previously, the "-v" option only printed the name of each file as it was downloaded. While this behavior remains, the size of the downloaded item and the number of bytes and percentage downloaded so far is included and updated during the download to show progress.

download --sync added.

The "--sync" option is a synonym for "-p" and "-u" together.

ls -1 added.

The "-1" option forces the file/folder list output to be in a single column. This is useful when the output must be parsed by a script. This optional has the same affect as on the Linux/BSD/macOS ls command.

ls -f added.

The "-f" option causes listed items to be output unsorted. This optional has the same affect as on the Linux/BSD/macOS ls command.

ls -h added.

The "-h" option causes shows sizes with KB/MB/GB suffixes. This optional has the same affect as on the Linux/BSD/macOS ls command.

ls -r added.

The "-r" option reverses the sort order. This optional has the same affect as on the Linux/BSD/macOS ls command.

mkdir -p added.

The "-p" causes all missing directories on a file path to be created automatically. For example "mkdir -p /a/b/c" will create "a" if it isn't there, then "b", then "c". This optional has the same affect as on the Linux/BSD/macOS mkdir command.

upload -n added.

The "-n" option prevents a upload from overwriting an existing remote file. Instead it will automatically add a unique sequence number. For example, if file "A.txt" is uploaded but there is already a remote file with that name, the upload will go into "A-2.txt".

upload -p added.

The "-p" option preserves timestamps by setting the modification time of uploaded files and folders to match the modification time on the local item. Without the option, uploaded files and folders have the current date as the modification time. This optional has the same affect as on the Linux/BSD/macOS cp command.

upload -u added.

The "-u" option updates remote files only if the local file is newer or if the remote file or folder does not exist. This should be used together with the "-p" option to insure that remote files have comparable timestamps. This optional has the same affect as on the Linux/BSD/macOS cp command.

upload -v shows upload progress.

Previously, the "-v" option only printed the name of each file as it was uploaded. While this behavior remains, the size of the uploaded item and the number of bytes and percentage uploaded so far is included and updated during the upload to show progress.

upload --sync added.

The "--sync" option is a synonym for "-p" and "-u" together.

Bugs fixed:

Move or copy of item into its own parent deletes it.

Fixed. Moving an item into its own parent is not a valid move or copy and it now reports an error.

New features:

REST web services moved to new "FolderShare REST" module.

Optional REST web services have been moved out of the FolderShare module and into this support module. This enables REST services to be updated on a schedule separate from that of the primary module.

REST web services command-line client moved into module.

The separately-distributed command-line client "foldershare" has been moved into the module release in the "client" directory. See the module's help page for examples of its use.

Module has a dedicated help page.

The module has its own REST-focused help page.

Removed features:

REST plugin reset to defaults button removed.

While REST features were in the FolderShare module, a "Restore" button on the administrator settings page would reset the REST plugin configuration to defaults. With the move to a new REST-focused module, there is no longer an administrator settings page. The REST plugin configuration is also so straight-forward that a "Restore" button seems superflous. Default REST plugin settings are discussed in the module's help page.

New features:

Client "ls -l" column width for permission too narrow.

Permission text is one of "public", "private", "personal", "shared with you", or "shared by you". The column width was 7 characters, and is now dynamic to accomodate the widest permission text.

Client "ls -l" column width for account name too narrow.

Account name text can be as little as one character, or as long as 60 characters. The column width was 8 characters, and is now dynamic to accomodate the widest account name.

Bugs fixed:

Client refers to undefined CURLE_REMOTE_ACCESS_DENIED.

The name is defined by libcurl, but not by the PHP CuRL package. Use of the name has been removed.

Client fails if server module does not have the same module version number.

A new protocol version number has been added that is separate from the module version number. The client checks that the server's protocol version is supported during client-server handshake.

Client does not print an account name in "ls -l" if an item is owned by anonymous.

Drupal's anonymous account is special and it actually has no account name. So, technically, printing an empty account name is correct. But not useful. The client now prints the anonymous user's display name (usually "Anonymous") when the account name is empty.

Client prints some error messages with HTML tags.

Error messages created on the server sometimes include HTML tags because the error messages are intended for display by a browser. For REST, these same messages are returned to the client. The client now strips HTML tags from error messages before printing them.