Merge pull request #196 from uploadcare/develop

Update to REST API 0.7 and lib version to 4.0

Author: rsedykh

.github/workflows/phpunit.yml

@@ -8,7 +8,7 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        php-versions: [ "7.4", "8.0" ]
+        php-versions: [ "7.4", "8.0", "8.1" ]
         phpunit-versions: [ "9" ]
     steps:
       - uses: actions/checkout@v2

.gitignore

@@ -5,3 +5,4 @@
 /tests/.env.local
 /psalm.phar
 .phpunit.result.cache
+.php-cs-fixer.cache

.php_cs.dist .php-cs-fixer.dist.php.php_cs.dist renamed to .php-cs-fixer.dist.php

@@ -24,7 +24,7 @@
     'single_import_per_statement' => false,
     'concat_space' => ['spacing' => 'one'],
     'array_syntax' => ['syntax' => 'short'],
-    'no_superfluous_phpdoc_tags' => false,
+    'no_superfluous_phpdoc_tags' => true,
     'blank_line_after_opening_tag' => false,
     'linebreak_after_opening_tag' => false,
     'global_namespace_import' => [
@@ -34,11 +34,19 @@
     ],
     'phpdoc_separation' => true,
     'yoda_style' => false,
+    'native_function_invocation' => [
+        'exclude' => [],
+        'include' => ['@internal'],
+        'scope' => 'all',
+        'strict' => false,
+    ],
+    'types_spaces' => ['space' => 'single'],
 ];
 
 $config = new PhpCsFixer\Config();
 
 return $config
     ->setRiskyAllowed(true)
     ->setRules($rules)
-    ->setFinder($finder);
+    ->setFinder($finder)
+;

CHANGELOG.md

@@ -5,6 +5,26 @@ The format is based now on [Keep a
 Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to
 [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [4.0.0]
+### Removed
+- PHP 7.1 support (now minimal version is 7.4, PHP 8.0 is also supported)
+- `FileInfoInterface::getImageInfo()`, `FileInfoInterface::getVideoInfo()`, `FileInfoInterface::getRekognitionInfo()` — see `FileInfoInterface::getContentInfo()`
+### Added 
+- Support for [REST API 0.7](https://uploadcare.com/api-refs/rest-api/v0.7.0/)
+- `FileInfoInterface::getContentInfo()`: returns `ContentInfoInterface` with `getMime()` (information about MimeType), `getImage` (`ImageInfoInterface` in case of an image) and `getVideo` (`VideoInfoInterface` in case of a video) methods;
+- `FileInfoInterface::getMetadata()` method returns file associated metadata array-accessible object;
+- Addons (`AddonsApiInterface`): execute and check status of an add-on application:
+  - `requestAwsRecognition($id)`: execute AWS Rekognition Add-On for a given target to detect labels in an image
+  - `checkAwsRecognition(string $id)`: check the status of an Add-On execution request that had been started using the Execute Add-On operation
+  - `requestAntivirusScan($id, bool $purge = false)`: execute ClamAV virus checking Add-On for a given target
+  - `checkAntivirusScan(string $id)`: check the status of an Add-On execution request that had been started using the Execute Add-On operation
+  - `requestRemoveBackground($id, ?RemoveBackgroundRequestInterface $backgroundRequest = null)`: execute remove.bg background image removal Add-On for a given target
+  - `checkRemoveBackground(string $id)`: check the status of an Add-On execution request that had been started using the Execute Add-On operation
+- Application data `FileInfoInterface::getAppdata()`: method returns `AppDataInterface` with information about addon-applications and associated data:
+  - `AwsRecognitionLabelsInterface`: information from previously executed `requestAwsRecognition` of image;
+  - `ClamAvVirusScanInterface`: information from [ClamAV](https://www.clamav.net/) antivirus scan
+  - `RemoveBgInterface`: data from previously executed `requestRemoveBackground` [remove.bg](https://remove.bg/) addon
+
 ## [3.2.4]
 ### Added
 - Allow to use guzzlehttp/psr7:^2.

README.md

@@ -14,6 +14,7 @@ Uploadcare PHP integration handles uploads and further operations with files by
 * [Usage](#usage)
   * [Uploading files](#uploading-files)
   * [File operations](#file-operations)
+  * [Addons operations](#addons-operations)
   * [Group operations](#group-operations)
   * [Project operations](#project-operations)
   * [Webhooks](#webhooks)
@@ -24,7 +25,7 @@ Uploadcare PHP integration handles uploads and further operations with files by
 
 ## Requirements
 
-- `php7.1+`
+- `php7.4+` or `php8.0+`
 - `php-curl`
 - `php-json`
 
@@ -36,7 +37,7 @@ Prior to installing `uploadcare-php` get the [Composer](https://getcomposer.org)
 
 ```json
 "require": {
-    "uploadcare/uploadcare-php": "^3.0"
+    "uploadcare/uploadcare-php": "^4.0"
 }
 ```
 
@@ -114,21 +115,18 @@ $configuration = \Uploadcare\Configuration::create($_ENV['UPLOADCARE_PUBLIC_KEY'
 $uploader = (new \Uploadcare\Api($configuration))->uploader();
 ```
 
-First of all, files can be uploaded **from URL**. The following code returns an instance of `Uploadcare\File`,
+First of all, files can be uploaded **from URL**. The following code returns a token to check file upload status,
 
 ```php
 $url = 'https://httpbin.org/image/jpeg';
-$result = $uploader->fromUrl($url, 'image/jpeg'); // If success, $result will contain instance of Uploadcare\File class (see below)
-
-echo \sprintf("File from URL %s uploaded successfully \n", $url);
-echo \sprintf("Uploaded file ID: %s\n", $result);
+$result = $uploader->fromUrl($url, 'image/jpeg'); // If success, $result will be string to check upload status (see below)
 ```
 
 Another way of uploading files is by using **a path**,
 
 ```php
 $path = __DIR__ . '/squirrel.jpg';
-$result = $uploader->fromPath($path, 'image/jpeg');  // In success $result will contains uploaded Uploadcare\File class
+$result = $uploader->fromPath($path, 'image/jpeg');  // In success $result will contain uploaded Uploadcare\File class
 ```
 
 It’s also relevant when using file pointers,
@@ -145,6 +143,25 @@ $path = __DIR__ . '/squirrel.jpg';
 $result = $uploader->fromContent(\file_get_contents($path), 'image/jpeg');
 ```
 
+Check upload file status:
+
+```php
+$url = 'https://httpbin.org/image/jpeg';
+$result = $uploader->fromUrl($url, 'image/jpeg'); 
+$status = $uploader->checkStatus($result); // Will be 'waiting', 'progress', 'success', 'error' or 'unknown'
+```
+
+#### File metadata
+
+Every upload method can set a [file metadata](https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/File-metadata). For example:
+
+```php
+$path = __DIR__ . '/squirrel.jpg';
+$result = $uploader->fromPath($path, 'image/jpeg', null, '1', ['type' => 'animal', 'kind' => 'squirrel']);
+```
+
+You will see this values in a `metadata` object of `Uploadcare\File` response.
+
 ### Multipart upload
 
 If you have a large file (more than 100Mb / 10485760 bytes), the uploader will automatically process it with a [multipart upload](https://uploadcare.com/api-refs/upload-api/#operation/multipartFileUploadStart). It'll take more time to upload, and also we don’t recommend it for a web environment.
@@ -205,7 +222,7 @@ After that, you can access to file operation methods:
     - `$makePublic` — `true` to make copied files available via public links, `false` to reverse the behavior.
     - `$pattern` — The parameter is used to specify file names Uploadcare passes to a custom storage. In case when the parameter is omitted, we use a pattern of your custom storage. Use any combination of allowed values.
 
-See the [API documentation](https://uploadcare.com/api-refs/rest-api/v0.6.0/#tag/File) for more details.
+See the [API documentation](https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/File) for more details.
 
 ### `Uploadcare\FileCollection` class
 
@@ -226,6 +243,74 @@ This class implements `FileInfoInterface` and has additional methods for file op
 
 As you can see, additional methods help you to call API methods without direct API calls.
 
+## Addons operations
+
+Uploadcare provide a few additional operations with images.
+
+### [Object Recognition](https://uploadcare.com/docs/intelligence/object-recognition/)
+
+To call object recognition from library:
+
+```php
+$configuration = \Uploadcare\Configuration::create($_ENV['UPLOADCARE_PUBLIC_KEY'], $_ENV['UPLOADCARE_SECRET_KEY']);
+
+$api = new \Uploadcare\Api($configuration);
+/** @var \Uploadcare\Interfaces\File\FileInfoInterface $file */
+$file = $api->file()->listFiles()->getResults()->first();
+
+# Request recognition, get token to check status
+$token = $api->addons()->requestAwsRecognition($file);
+while (($status = $api->addons()->checkAwsRecognition($token)) !== 'done') {
+    \usleep(1000);
+    if ($status === 'error') {
+        throw new \Exception('Error in process');
+    }
+}
+
+$recognitionData = $api->file()->fileInfo($file->getUuid())->getAppdata()->getAwsRekognitionDetectLabels(); // Instance of \Uploadcare\Interfaces\File\AppData\AwsRecognitionLabelsInterface
+```
+
+### [Remove background](https://uploadcare.com/docs/remove-bg/)
+
+Remove background from image:
+
+```php
+$configuration = \Uploadcare\Configuration::create($_ENV['UPLOADCARE_PUBLIC_KEY'], $_ENV['UPLOADCARE_SECRET_KEY']);
+
+$api = new \Uploadcare\Api($configuration);
+/** @var \Uploadcare\Interfaces\File\FileInfoInterface $file */
+$file = $api->file()->listFiles()->getResults()->first();
+
+# Request recognition, get token to check status
+$token = $api->addons()->requestRemoveBackground($file);
+while (($status = $api->addons()->checkRemoveBackground($token)) !== 'done') {
+    \usleep(1000);
+    if ($status === 'error') {
+        throw new \Exception('Error in process');
+    }
+}
+
+$removeBackgroundData = $api->file()->fileInfo($file->getUuid())->getAppdata()->getRemoveBg(); // Instance of \Uploadcare\Interfaces\File\AppData\RemoveBgInterface
+```
+
+### [Antivirus scan](https://www.clamav.net/)
+
+```php
+$configuration = \Uploadcare\Configuration::create($_ENV['UPLOADCARE_PUBLIC_KEY'], $_ENV['UPLOADCARE_SECRET_KEY']);
+$api = new \Uploadcare\Api($configuration);
+/** @var \Uploadcare\Interfaces\File\FileInfoInterface $file */
+$file = $api->file()->listFiles()->getResults()->first();
+
+# Request antivirus scan and get token:
+$token = $api->addons()->requestAntivirusScan($file);
+while (($status = $api->addons()->checkAntivirusScan($token)) !== 'done') {
+    \usleep(1000);
+    if ($status === 'error') {
+        throw new \Exception('Error in process');
+    }
+}
+```
+
 ## Group operations
 
 For any type of group operation you need to create an `Uploadcare\Api` instance with a configuration object and call the `group()` method:
@@ -318,7 +403,7 @@ The default arguments and examples are:
 - `$store = true` —  The conversion results will go to your default storage.
 - `$pageNumber = 1` — Specifies pages to convert in multi-page documents.
 
-After that, you can covert your file:
+After that, you can convert your file:
 
 ```php
 $config = \Uploadcare\Configuration::create($_ENV['UPLOADCARE_PUBLIC_KEY'], $_ENV['UPLOADCARE_SECRET_KEY']);

composer.json

@@ -24,20 +24,21 @@
   },
   "minimum-stability": "stable",
   "require": {
-    "php": ">=7.1 || >=8.0",
+    "php": ">=7.4 || >=8.0",
     "ext-curl": "*",
     "ext-json": "*",
-    "guzzlehttp/guzzle": "^6.5||^7",
-    "guzzlehttp/psr7": "^1.6||^2",
-    "symfony/polyfill-uuid": "^1.17"
+    "guzzlehttp/guzzle": "^7.5",
+    "guzzlehttp/psr7": "^2.4",
+    "symfony/polyfill-php80": "^1.26",
+    "symfony/polyfill-uuid": "^1.26"
   },
   "require-dev": {
-    "fakerphp/faker": "^1.9",
-    "friendsofphp/php-cs-fixer": "^2.16",
-    "phpunit/phpunit": "^5.7||^7||^9",
-    "symfony/dotenv": "^3.4",
-    "symfony/var-dumper": "^3.4||^5",
-    "vimeo/psalm": "^4.7"
+    "fakerphp/faker": "^1.20",
+    "friendsofphp/php-cs-fixer": "^3.11",
+    "phpunit/phpunit": "^9.5",
+    "symfony/dotenv": "^5.4",
+    "symfony/var-dumper": "^5.4",
+    "vimeo/psalm": "^4.27"
   },
   "autoload": {
     "psr-4": {
@@ -54,6 +55,9 @@
     "preferred-install": {
       "*": "dist"
     },
-    "sort-packages": true
+    "sort-packages": true,
+    "allow-plugins": {
+      "composer/package-versions-deprecated": true
+    }
   }
 }

php-7.1.Dockerfile php-7.4.Dockerfilephp-7.1.Dockerfile renamed to php-7.4.Dockerfile

@@ -1,11 +1,11 @@
 FROM composer:latest as composer
-FROM php:7.1-fpm-alpine as php
+FROM php:7.4-fpm-alpine as php
 
 RUN apk add --no-cache git
 
 RUN set -xe \
     && apk add --no-cache --virtual .phpize-deps $PHPIZE_DEPS \
-    && pecl install xdebug-2.9.8 \
+    && pecl install xdebug \
     && docker-php-ext-enable xdebug \
     && apk del --no-network .phpize-deps
 

phpunit.xml

@@ -1,16 +1,15 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/5.7/phpunit.xsd"
-         bootstrap="vendor/autoload.php"
-         backupGlobals="false"
-         verbose="true">
+    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.5/phpunit.xsd"
+    bootstrap="vendor/autoload.php"
+    colors="true"
+    backupGlobals="false" verbose="true">
+    <coverage processUncoveredFiles="true">
+        <include>
+            <directory suffix=".php">src</directory>
+        </include>
+    </coverage>
     <testsuite name="default">
         <directory suffix="Test.php">tests</directory>
     </testsuite>
-
-    <filter>
-        <whitelist processUncoveredFilesFromWhitelist="true">
-            <directory suffix=".php">src</directory>
-        </whitelist>
-    </filter>
 </phpunit>

psalm.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0"?>
 <psalm
-    errorLevel="3"
+    errorLevel="2"
     resolveFromConfigFile="true"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns="https://getpsalm.org/schema/config"