Download the PHP package / without Composer

Filer Client

This is the client you should use for consuming the Filer service.

The client can use two kinds of transports to send requests:

• Asynchronous transport implemented by BeanstalkProxyTransport
• Synchronous transport implemented by BasicTransport

BeanstalkProxyTransport delegate the API consumption to workers by sending file properties to a Beanstalkd queue.

BasicTransport use the classic HTTP layer to send files.

If asynchronous transport is set, it will act as default transport. Synchronous transport will be a fallback in case when asynchronous transport fails.

All examples in this document will use BeanstalkProxyTransport and BasicTransport.

Installation

Filer Client needs PHP 5.5 or higher.

Add this requirement to your composer.json: "fei/filer-client": : "^1.0"

Or execute composer.phar require fei/filer-client in your terminal.

If you want use the asynchronous functionality of the Filer client (and we know you want), you need an instance of Beanstalkd which running properly and an instance of api-client-worker.php which will consume the Beanstalk's pipe and forward messages payload to the Filer API:

Beanstalkd configuration

Running Beanstalkd is very simple. However, you must pay attention to the z option which set the maximum job (or message) size in bytes. So, if you want transfer 100 Mo files to Filer API, you should consider at least a value of 16O Mo for the z parameter.

Run api-client-worker.php

You could see below an example of running api-client-worker.php:

You can control the api-client-worker.php process by using Supervisor.

Entities and classes

File entity

In addition to traditional ID and CreatedAt fields, File Entity has *six important properties:

• $uuid (Universal Unique Identifier) is a unique id corresponding to a file. Its format is based on 36 characters as defined in RFC4122 prefixed by a backend id and separated by a :. Example: bck1:f6461366-a414-4b98-a76d-d7b190252e74
• filename is a string indicating the file's filename.
• revision is an integer indicating the file's current revision.
• category is an integer defining in which database the file will be stored in.
• contentType defines the content type of the File object.
• data contains the file's content.
• file is an SplFileObject instance. (see https://secure.php.net/manual/en/class.splfileobject.php for more details)
• contexts is an ArrayCollection instance where each element is a Context entity

Basic usage

In order to consume File method, you have to define a new Filer instance and set transport type (Async and Sync):

Filer client instance will first attempt to transfer the messages with Beanstalkd, if the process fail then the client will try to send File payload directly to the right API endpoint.

There are several methods in Filer class, all listed in the following table:

$uuid (Universal Unique Identifier) is a unique id corresponding to a file. (see File entity part)

Client option

Only one option is available which can be passed to the constructor or Filer::setOptions(array $options) methods:

Note: All the examples below are also available in examples directory.

Search the files

You can search the files directly from the client with Filer::search($builder)

• $builder must be a SearchBuilder instance

You can create your searches using the SearchBuilder to make the search easier to use.

As you can see mutiple methods are available like filename and multiple operators methods too like :

• like : to use the LIKE operator
• equal : to use the = operator
• beginsWith : to use the LIKE operator and the string has to start by the value specified
• endsWith : to use the LIKE operator and the string has to end by the value specified

Note that you can search on multiple categories by adding multiple categories filter :

Note that you can filter on contexts. By default if you have multiple filter for the contexts, an "AND" condition will be processed. You can choose to do an "OR" condition by making the following filter :

You can also search a file by giving an uuid. If you do this king of search you don't need to filter by categories but you still can if you want.

Here is an example on how to search a file with it's uuid :

Upload a new file

You can upload a file instance with Filer::upload($file, $flags):

• $file must be a File instance
• $flags can be null or a Filer constant:
  • Filer::ASYNC_UPLOAD: prepare the upload without waiting for API response
  • Filer::NEW_REVISION: create a new revision for a specific uuid (which must obviously be declared in $file)

The function will return null or a string describing the new file path.

Example

An other way to create a File instance is to use the static method Filer::embed($path) which allows you to create a file instance using a local file path:

Retrieve a file

You can retrieve a file instance with Filer::retrieve($uuid). The only necessary parameter is a valid file uuid.

This method returns a File instance or null if the file was not found.

Example

Delete a file

You can delete a file with Filer::delete($uuid). The only necessary parameter is a valid file uuid.

Example

Truncate a file

The Filer::truncate($uuid, $keep = 0) method allows you to remove every revisions of a file, except a determined number of revisions.

Example

Save

Filer::save($uuid, $path, $as = null) method is a way to retrieve and save a local copy of a remote File.

Example

Serve a file

With the method Filer::serve($uuid, $flag = Filer::FORCE_DOWNLOAD) you can serve a file to user agents and force the download.

If you don't want to download the file and show it, you can call the method like this: Filer::serve($uuid, Filer::FORCE_INLINE)

Example

Upload large files by chunk

From the version 1.1.0 of this client it is possible tu upload large file by chunk. In order to do this, ypu have to use the Filer::uploadByChunk(File $file, callable $fulfilled = null, callable $rejected = null) method.

Example

$fulfilled callback will be executed each time a chunk is transmitted successfully. Otherwise $rejected callback will be executed each time a chunk is not transmitted successfully.

By default, $rejected is equal to:

You could set the chunk size and the Upload concurrency with respectively the options OPTION_CHUNK_SIZE and OPTION_CHUNK_UPLOAD_CONCURRENCY.