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.

Table of Contents

• Installation
  • Dependencies
• Service Provider
  • Parameters
  • Services
• Configuration
• Usage
• Development
  • API Documentation
  • Development Dependencies
  • Coding Style
• 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.

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.

• FilePond vanilla installation
• FilePond vanilla documentation
• FilePond available frameworks

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.