digital-blueprint/relay-blob-library

PHP helper library for relay-blob

dbp relay blob library

GitHub | Packagist | Changelog

PHP helper library for interaction with the relay-blob-bundle.

Installation

composer require dbp/relay-blob-library

Usage

use Dbp\Relay\BlobLibrary\Api\BlobApi;
use Dbp\Relay\BlobLibrary\Api\BlobApiError;

// The blob base url is the url of your API server where the relay-blob-bundle is installed
$blobBaseUrl = 'https://api.your.server';

// See https://github.com/digital-blueprint/relay-blob-bundle#configuration for more information about the blob bucket id and key
$blobBucketId = 'your-bucket-id';
$blobKey = 'your-blob-key';

// Create a new BlobApi instance
$blobApi = new BlobApi($blobBaseUrl, $blobBucketId, $blobKey);

$prefix = 'my-prefix';
$fileName = 'my-file-name.pdf';
$fileData = 'my-binary-file-data';

// oauth specific variables
// replace with your own config

$oauthIDPUrl = 'https://your.oauth.server'; // oauthIDP url including realm
$clientID = 'your-client-id';
$clientSecret = 'your-client-secret';

// if needed, get an OAuth2 token
try {
    $blobApi->setOAuth2Token($oauthIDPUrl, $clientID, $clientSecret);
} catch (BlobApiError $e) {
    // Handle error, print $e->getMessage() for more information
}

// Upload a file to the blob storage and get the identifier
try {
    $identifier = $blobApi->uploadFile($prefix, $fileName, $fileData);
} catch (BlobApiError $e) {
    // Handle error
    var_dump($e->getMessage());
    var_dump($e->getErrorId());
    var_dump($e->getErrorDetails());
}

// Download a file from the blob storage by identifier and get the content url
try {
    // The content url is a data url and looks for example like this:
    // data:application/pdf;base64,JVBERi0xLjUKJbXtrvsKNCAwIG9iago....= 
    $contentUrl = $blobApi->downloadFileAsContentUrlByIdentifier($identifier);
} catch (BlobApiError $e) {
    // Handle error, print $e->getMessage() for more information
}

// Delete a file from the blob storage by identifier
try {
    $blobApi->deleteFileByIdentifier($identifier);
} catch (BlobApiError $e) {
    // Handle error, print $e->getMessage() for more information
}

// Delete all files from the blob storage by prefix
try {
    $blobApi->deleteFilesByPrefix($prefix);
} catch (BlobApiError $e) {
    // Handle error, print $e->getMessage() for more information
}

• For more usage examples, see examples
• For more information about the API, see api.md
• For information about error codes, see error-codes.md

relay-blob-library's Issues

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Awaiting Schedule

These updates are awaiting their schedule. Click on a checkbox to get an update now.

• chore(deps): lock file maintenance

Detected dependencies

composer

composer.json

• php >=8.1
• guzzlehttp/guzzle ^7.0
• web-token/jwt-library ^3.3
• friendsofphp/php-cs-fixer ^3.50
• phpstan/phpstan ^1.10.59
• phpstan/phpstan-phpunit ^1.3.16
• phpstan/phpstan-symfony ^1.3.7
• phpunit/phpunit ^9.6.17
• symfony/browser-kit ^5.4.35
• symfony/http-client ^5.4.36
• symfony/phpunit-bridge ^5.4.36
• vimeo/psalm ^5.22.2

github-actions

.github/workflows/test.yml

• shivammathur/setup-php v2
• actions/checkout v4
• actions/cache v4
• shivammathur/setup-php v2
• actions/checkout v4
• actions/cache v4

---

• Check this box to trigger a request for Renovate to run again on this repository

Enhance error handling

The Error class that is currently used for the Blob Backend API (Blob Library) is more or less a clone of ApiError (but without the HttpException parent class). This means the API user needs to know the internal JSON schema of the Error class to get the error properties out of the Error::getMessage(), which is not intuitive, error-prone, and needs extra documentation.

Todo

• Rename and move Helpers/Error to Api/BlobApiError (or the like)
• create a constructor accepting a message string, an errorCode string and an errorDetails array, which calls the parent (\Exception) constructor
• drop the JSON encoding of the error data in the exception's message and you use normal member varibles for errorCode and errorDetails
• create getters for errorCode and errorDetails
• move Error::decodeErrorId to the BlobApi, make it private and rename it to something like BlogApi::getErrorIdFromApiError
• create public constants in the BlobApiError for all errorIds currently used with Error (e.g. 'blob-library:delete-file-timeout' -> BlobApiError::DELETE_FILE_TIMEOUT_ERROR_ID) and pass them to the constructor of BlogApiError instead of the string literals
• adapt the whole library and all tests and examples to use BlobApiError with the new methods
• Create missing tests and error code documentation for \Dbp\Relay\BlobLibrary\Api\BlobApi::putFileByIdentifier
  • Documentation
  • Tests
• adapt all current usages of BlobApi in Dispatch