README

A Charcoal service provider for FilePond.

FilePond is a JavaScript library that can upload anything you throw at it, optimizes images for faster uploads, and offers a great, accessible, silky smooth user experience.

This contrib act in fact as an upload server to go along with FilePond.

Installation
- Dependencies
Service Provider
- Parameters
- Services
Configuration
Usage
Development
Credits
License

Installation

The preferred (and only supported) method is with Composer:

$ composer require locomotivemtl/charcoal-contrib-filepond

Then add the module to your project's module list like so:

{
    "modules": {
        "charcoal/file-pond/file-pond": {}
    }
}

Dependencies

Required

PHP 5.6+: PHP 7 is recommended.
ext-fileinfo: "*",
league/flysystem ^1.0,
locomotivemtl/charcoal-app >= 0.7

Service Provider

Charcoal\FilePond\ServiceProvider\FilePondServiceProvider

The service provider is automatically instantiated by the module.

Services

FilePondService.php FilePondService can be invoked with a server config ident to bind it to a server when needed :

$action = new RequestAction([
    'logger'          => $container['logger'],
    'filePondService' => $container['file-pond/service']($serverIdent),
]);

FilePondConfig.php

Configuration

The configuration for FilePond can be found here : FilePondConfig.php.

It uses the config file file-pond.json as default configset and can be overridden in your project's config.

getServer($ident) and getServers() can be called on the config to retrieve server configuration(s) : ServerConfig.php

The config defines a list of servers :

A server is a combination of an endpoint mapped with a filesystem and information regarding file paths.

Server options.

Option	Description	Default value
route	The server endpoint url for the front-end app. Feeds the server option of FilePond.js	/file-pond
filesystem_ident	Which Filesystem to use. See charcoal-app.	private
upload_path	The definitive upload path root for files once the submission is completed. This path can be overridden in the submission action. The Helper FilePondAwareTrait will attempt to save the upload using the property's upload_path	uploads/file-pond
transfer_dir	The temporary file-pond folder root. Used while processing front-end file upload. Files from this directory will be transferred to there final location after the submission is completed.	tmp/file-pond

Usage

Overrides the Module Config as needed by copying the file-pond.json structure in your project's config file as so:

{
    "contrib": {
        "file-pond": {
            "config": {
                "servers": {
                    "default": {
                        "route": "/file-pond",
                        "filesystem_ident": "private",
                        "upload_path": "uploads/file-pond",
                        "transfer_dir": "tmp/file-pond"
                    },
                    "s3": {
                        "route": "/file-pond/s3",
                        "filesystem_ident": "s3",
                        "upload_path": "uploads/file-pond",
                        "transfer_dir": "tmp/file-pond"
                    }
                }
            }
        }
    }
}

Set a route to give to the FilePond.js front-end framework. A slim route will automatically be created using the desired pattern. Once that is done, configure the front-end file-pond module using the correct FilePond documentation.

The key part of this process is that when the form is submitted, the server handles the transferring of previously uploaded files to their final paths. This allows to move uploads to folders that contains a user specific id and conceals the real path mapping of the server for security reasons.

You can use the FilePondAwareTrait on the action controller to handle filepond transfers. First set the required dependencies like that:

<?php

// From 'charcoal-contrib-filepond'
use Charcoal\FilePond\Service\Helper\FilePondAwareTrait;

/**
 * Create a new instructor.
 */
class SomeAction extends AbstractAction
{
    use FilePondAwareTrait;

    /**
     * Inject dependencies from a DI Container.
     *
     * @param Container $container A Pimple DI service container.
     * @return void
     */
    public function setDependencies(Container $container)
    {
        parent::setDependencies($container);

        $this->setFilePondService($container['file-pond/service']('private'));
    }
}

Then you can use the handleTransfer() method to facilitate the transfer upload process.

handleTransfer() for reference :

/**
 * Attempts to handle the transfer of uploads given the proper parameters.
 * If possible, it will try to :
 * - fetch the upload path from the property.
 * - fetch the filesystem based on the public access of the property.
 * - Pass it through the best processor depending on wether their were ids passed or not.
 *
 * @param string|array|null             $ids        The uploaded files ids. Let to null to force $_FILES and $_POST.
 * @param string|PropertyInterface|null $property   The property ident or a property.
 * @param ModelInterface|string|null    $context    The context object as model or class ident.
 * @param string|null                   $pathSuffix Path suffix.
 * @return array
 */
protected function handleTransfer(
    $ids = null,
    $property = null,
    $context = null,
    $pathSuffix = null
)

Example of usage :

/** Transfer uploaded files */
$files = $this->handleTransfer(
    $submissionData['someProp'],
    'some_prop',
    $someModel,
    $someModel->property('id')->autoGenerate()
);

Development

To install the development environment:

$ composer install

To run the scripts (phplint, phpcs, and phpunit):

$ composer test

API Documentation

The auto-generated phpDocumentor API documentation is available at:
https://locomotivemtl.github.io/charcoal-contrib-filepond/docs/master/
The auto-generated apigen API documentation is available at:
https://codedoc.pub/locomotivemtl/charcoal-contrib-filepond/master/

Development Dependencies

[php-coveralls/php-coveralls][phpcov]
[phpunit/phpunit][phpunit]
[squizlabs/php_codesniffer][phpcs]

Coding Style

The charcoal-contrib-filepond module follows the Charcoal coding-style:

PSR-1
PSR-2
PSR-4, autoloading is therefore provided by Composer.
phpDocumentor comments.
phpcs.xml.dist and .editorconfig for coding standards.

Coding style validation / enforcement can be performed with composer phpcs. An auto-fixer is also available with composer phpcbf.

Credits

Locomotive

License

Charcoal is licensed under the MIT license. See LICENSE for details.

locomotivemtl / charcoal-contrib-filepond

Maintainers

Details