README

B2 Spirit is a Laravel package designed to handle file transfers with Backblaze B2 Cloud Storage.

(on a side-note, this project is paused since I don't have time to add other endpoints/fix issues, but I aim at doing so in the future)

Features

Seamless integration with Laravel
Easy file uploads and downloads
Secure file storage with Backblaze B2

Installation

To install the package, use Composer:

composer require noxterr/spirit

Setup migrations

Migrations aren't necessary for this package to work and all the functions and features will work even if you don't publish migration and execute them.

The simply migration will keep a table for logging on your database, which will log every single action that is carried out from this package.

This allows auditing and logging, in order to keep track of every action.

Even if you publish and run migrations, you need to enable the logging flow by adding a key in the .env file.

Step 1: Export the migrations

php artisan vendor:publish --tag="spirit-migrations"

Step 2: Run php artisan migrate to run the migrations.

Step 3: Add key in your .env for migrations

B2_MIGRATION_ENABLED=true # This is either true or false
# (optional)
B2_MIGRATION_LEVEL=`B2_MIGRATION_LEVEL` # This is 'off' | 'minimal' | 'normal' | 'exhaustive' | 'intense' | 'full'

Set your Backblaze B2 credentials in the .env file:

B2_KEY=`YOUR_B2_KEY` # You can put your master key for now. Creating a key with the privileges you need also works
B2_BUCKET_NAME=`YOUR_B2_BUCKET_NAME` # The globally-available name you gave your bucket
B2_BUCKET_ID=`YOUR_B2_BUCKET_ID`
B2_ACCOUNT_ID=`YOUR_B2_ACCOUNT_ID`

Usage

Uploading a File

use Noxterr\Spirit\Spirit;

$spirit = new Spirit();

$uploaded_file = $spirit->uploadFile($file);

Downloading a File

use Noxterr\Spirit\Spirit;

$spirit = new Spirit();

$file = $spirit->downloadFile($file_name);

Handling respones

Every time an action is carried out on Spirit, a response is provided to the user under the form of a so-called ClassReturn.

This is an object that returns standardized data, making it easier to interface with your custom application.

The object is as follows

// In another class
$response = new \ClassReturn();

return $response;

/** This returns
 * {
 *    errcode: 1 | 0,
 *    message: string | null (contains the error information if needed)
 *    data: mixed | null -> contains the data from a response
 * }
*/

With this flow, you can always ensure to check errors like so if ($response->errcode != 0) { Error handling }, so is easy to use.

Versioning and branches

Every branch will be named X.Y.Z to match the version (meaning 2.0.0, 1.2.3 etc...). The latest branch is v.x (meaning 2.x, 3.x and so on).

Tag-wise, a tag that matches the version will be pushed on a new release under the same version schema with v appended upfront (meaning v1.2.4, v2.0.0)

For tags, if a version is, say, 3.x, the corresponding tags can range from v3.0.0 to v3.9.9, higher meaning latest version to require via composer

License

This package is open-sourced software licensed under the MIT license.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Support

For any issues, please open an issue on GitHub.

noxterr / spirit

Maintainers

Details