, (*1)
Filestack PHP
, (*2)
This is the official PHP SDK for Filestack - API and content management system that makes it easy to add powerful file uploading and transformation capabilities to any web or mobile application., (*3)
Requirements
Resources
Installing
Install filestack with composer, either run, (*4)
$ composer require --prefer-dist filestack/filestack-php
Usage
Filestack library gives you access to three useful classes:, (*5)
-
FilestackClient - for easy file upload (creates Filelink objects)
-
Filelink - for file handling (downloading, converting etc.)
-
FileSecurity - for applying policy and signature values to your API calls
Uploading files
First, you need to create an instance of FilestackClient, (*6)
use Filestack\FilestackClient;
$client = new FilestackClient('YOUR_API_KEY');
Call the upload() function, (*7)
$filelink = $client->upload('/path/to/file');
Storage
Amazon S3 is used to store your files by default. If you wish to use a different one, you can pass in additional parameter 'location' when making upload() and store calls, (*8)
$client = new FilestackClient('YOUR_API_KEY');
$extras = [
'Location' => 'dropbox',
'Filename' => 'somefilename.jpg',
];
$filepath = '/path/to/file';
$filelink = $client->upload($filepath);
# get metadata of file
$metadata = $client->getMetaData($filelink->handle, $fields);
# get content of a file
$content = $client->getContent($filelink->handle);
# download a file
$destination = '/path/to/file';
$result = $client->download($filelink->handle, $destination);
# overwrite a file
$filelink2 = $client->overwrite('/path/to/file', $filelink->handle);
Manipulating files
Filelink objects can be created in two ways:, (*9)
- by uploading a file using FilestackClient
- by initializing Filelink with file handle and api_key
First method was shown above, the second method is also very easy and will create objects representing files that were already uploaded., (*10)
use Filestack\filelink;
$filelink = new Filelink('some-file-handle', 'YOUR_API_KEY');
# transforming an image
$transformed_filelink = $filelink
->circle()
->blur(['amount' => '20'])
->save();
# get metadata
$metadata = $filelink->getMetaData();
# get content of a file
$content = $filelink->getContent();
$filepath = '/path/to/file';
# download a file
$filelink->download($filepath);
# overwrite remote file with local file
$filelink->overwrite($filepath);
# delete remote file
$filelink->delete();
Tagging files and detecting safe for work content
use Filestack\FilestackClient;
use Filestack\FilestackSecurity;
$security = new FilestackSecurity('YOUR_SECURITY_SECRET');
$client = new FilestackClient('YOUR_API_KEY', $security);
$file_handle = 'some-file-handle';
# get tags with client
$result_json = $client->getTags($file_handle);
# get tags with filelink
$filelink = new Filelink($file_handle, 'YOUR_API_KEY', $security);
$json_result = $filelink->getTags();
# get safe for work flag with client
$result_json = $client->getSafeForWork($file_handle);
# get safe for work flag with filelink
$json_result = $filelink->getSafeForWork();
For more examples, see the examples/ folder in this project., (*11)
Intelligent Ingestion
The Intelligent Ingestion feature allows user to upload a file in chunks of
not precised size. This creates a more stable upload flow that ensures the
file being uploaded will eventually complete successfully, regardless of
network latency or timeout errors., (*12)
However, the upload process may be slower than the normal upload flow for
large files, as there are errors are retried using the exponential backoff
retry strategy., (*13)
Lastly, this feature has to be turned on for the apikey being used. To turn
on this feature please contact Filestack at support@filestack.com., (*14)
$client = new FilestackClient('YOUR_API_KEY');
$filelink = $client->upload('/path/to/file', ['intelligent' => true]);
Versioning
Filestack PHP SDK follows the Semantic Versioning., (*15)
Code Standard
- PSR-2 coding standard (http://www.php-fig.org/psr/psr-2/)
- PSR-4 autoloading standard (http://www.php-fig.org/psr/psr-4/)
- phpDoc documentation comments standard (https://www.phpdoc.org/docs/latest/getting-started/your-first-set-of-documentation.html)
Testing
- To run tests, from the project root director, run
vendor/bin/phpunit
- To generate coverage report, run following command (will generage html files under
directory coverage/)
vendor/bin/phpunit --coverage-xml=coverage
- To run PHPMD for CodeClimate checks
vendor/bin/phpmd filestack xml phpmd-rules.xml > logs/phpmd-report-filestack.xml
vendor/bin/phpmd tests xml phpmd-rules.xml > logs/phpmd-report-tests.xml
Generating documentation
To get project metrics use phar file for https://github.com/sebastianbergmann/phploc, (*16)
./phploc.phar --log-xml=phploc.xml .
To generate documentation use phar file from https://github.com/theseer/phpdox, (*17)
./phpdox.phar
Issues
If you have problems, please create a Github Issue., (*18)
Contributing
Please see CONTRIBUTING.md for details., (*19)
Credits
Thank you to all the contributors., (*20)
Wallogit.com
