README

A simple File upload Laravel package with ClamAV anti-virus scan. This library was built riding on an existing clamav php library kissit/php-clamav-scan.

REQUIREMENTS

PHP 8.0+
Laravel 9+
Clamav

STEPS TO INSTALL

composer require ikechukwukalu/clamavfileupload

php artisan vendor:publish --tag=cfu-config

CLAMD_SOCK="/var/run/clamav/clamd.sock"
CLAMD_SOCK_LEN=20000
CLAMD_IP=null
CLAMD_PORT=3310
FILE_UPLOAD_INPUT=file
FILE_UPLOAD_DISK=public
FILE_UPLOAD_LOG_SCAN_DATA=false
HASHED=false
VISIBLE=true

php artisan vendor:publish --tag=cfu-migrations
php artisan migrate

CLAMAV SCAN FILE UPLOAD

use Ikechukwukalu\Clamavfileupload\Facades\Services\FileUpload;


FileUpload::uploadFiles($request); //returns bool|FileUploadModel|EloquentCollection

/**
 * Default settings
 *
 * 'name' => null // This is different from file name
 * 'input' => config('clamavfileupload.input', 'file')
 * 'folder' => null
 * 'hashed' => config('clamavfileupload.hashed', false)
 * 'visible' => config('clamavfileupload.visible', true)
 * 'disk' => config('clamavfileupload.disk', 'local')
 *
 *
 */

/**
 * You can also overwrite the default settings with custom settings
 */
$settings = [
    'folder' => 'pdfs'
];

$fileUpload = new FileUpload;
$fileUpload::uploadFiles($request, $settings); //returns bool|FileUploadModel|EloquentCollection

/**
 * Access last scan results
 */
$fileUpload::getScanData()

/**
 * Check if upload was successful
 */
if (!$fileUpload::isSuccessful()) {
    echo $fileUpload::getErrorMessage();
}

/**
 * Make sure to save the $ref UUID so as to be
 * able to retrieve the uploaded file(s) from the database.
 */
$fileUpload::getRef()

/**
 * Soft delete files
 */

/**
 * @param string $ref
 * @return bool
 */
FileUpload::deleteAll($ref);

/**
 * @param array $ids
 * @param string $ref
 * @return bool
 */
FileUpload::deleteMultiple($ids, $ref);

/**
 * @param int $id
 * @param string $ref
 * @return bool
 */
FileUpload::deleteOne($id, $ref);


/**
 * Permanently delete files from the database and disk
 */

/**
 * @param string $ref
 * @return bool
 */
FileUpload::forceDeleteAll($ref);

/**
 * @param array $ids
 * @param string $ref
 * @return bool
 */
FileUpload::forceDeleteMultiple($ids, $ref);

/**
 * @param int $id
 * @param string $ref
 * @return bool
 */
FileUpload::forceDeleteOne($id, $ref);

QUEUED CLAMAV SCAN FILE UPLOAD

This process stores the file in a tmp directory and sets up a queue for the clamav scan and uploads the tmp files to their designated directory. At the end of the process temp files would have been removed from the tmp directory.

To use Redis set REDIS_CLIENT=predis and QUEUE_CONNECTION=redis within your .env file.
php artisan queue:work

use Ikechukwukalu\Clamavfileupload\Facades\Services\QueuedFileUpload;


QueuedFileUpload::uploadFiles($request); //returns bool|FileUploadModel|EloquentCollection

/**
 * Default settings
 *
 * 'name' => null // This is different from file name
 * 'input' => config('clamavfileupload.input', 'file')
 * 'folder' => null
 * 'hashed' => config('clamavfileupload.hashed', false)
 * 'visible' => config('clamavfileupload.visible', true)
 * 'disk' => config('clamavfileupload.disk', 'local')
 *
 *
 */

/**
 * You can also overwrite the default settings with custom settings
 */
$settings = [
    'folder' => 'pdfs'
];

$fileUpload = new QueuedFileUpload;
$fileUpload::uploadFiles($request, $settings); //returns bool|FileUploadModel|EloquentCollection

/**
 * Make sure to save the $ref UUID so as to be
 * able to retrieve the uploaded file(s) from the database.
 */
$fileUpload::getRef()

/**
 * Soft delete files
 */

/**
 * @param string $ref
 * @return bool
 */
QueuedFileUpload::deleteAll($ref);

/**
 * @param array $ids
 * @param string $ref
 * @return bool
 */
QueuedFileUpload::deleteMultiple($ids, $ref);

/**
 * @param int $id
 * @param string $ref
 * @return bool
 */
QueuedFileUpload::deleteOne($id, $ref);


/**
 * Permanently delete files from the database and disk
 */

/**
 * @param string $ref
 * @return bool
 */
QueuedFileUpload::forceDeleteAll($ref);

/**
 * @param array $ids
 * @param string $ref
 * @return bool
 */
QueuedFileUpload::forceDeleteMultiple($ids, $ref);

/**
 * @param int $id
 * @param string $ref
 * @return bool
 */
QueuedFileUpload::forceDeleteOne($id, $ref);

NO CLAMAV SCAN FILE UPLOAD

use Ikechukwukalu\Clamavfileupload\Facades\Services\NoClamavFileUpload;


NoClamavFileUpload::uploadFiles($request); //returns bool|FileUploadModel|EloquentCollection

/**
 * Default settings
 *
 * 'name' => null // This is different from file name
 * 'input' => config('clamavfileupload.input', 'file')
 * 'folder' => null
 * 'hashed' => config('clamavfileupload.hashed', false)
 * 'visible' => config('clamavfileupload.visible', true)
 * 'disk' => config('clamavfileupload.disk', 'local')
 *
 *
 */

/**
 * You can also overwrite the default settings with custom settings
 */
$settings = [
    'folder' => 'pdfs'
];

$fileUpload = new NoClamavFileUpload;
$fileUpload::uploadFiles($request, $settings); //returns bool|FileUploadModel|EloquentCollection

/**
 * Check if upload was successful
 */
if (!$fileUpload::isSuccessful()) {
    echo $fileUpload::getErrorMessage();
}

/**
 * Make sure to save the $ref UUID so as to be
 * able to retrieve the uploaded file(s) from the database.
 */
$fileUpload::getRef()

/**
 * Soft delete files
 */

/**
 * @param string $ref
 * @return bool
 */
NoClamavFileUpload::deleteAll($ref);

/**
 * @param array $ids
 * @param string $ref
 * @return bool
 */
NoClamavFileUpload::deleteMultiple($ids, $ref);

/**
 * @param int $id
 * @param string $ref
 * @return bool
 */
NoClamavFileUpload::deleteOne($id, $ref);


/**
 * Permanently delete files from the database and disk
 */

/**
 * @param string $ref
 * @return bool
 */
NoClamavFileUpload::forceDeleteAll($ref);

/**
 * @param array $ids
 * @param string $ref
 * @return bool
 */
NoClamavFileUpload::forceDeleteMultiple($ids, $ref);

/**
 * @param int $id
 * @param string $ref
 * @return bool
 */
NoClamavFileUpload::forceDeleteOne($id, $ref);

HASH

If the HASHED param within your .env is set to true the file_name, path and url fields will be encrypted before they are saved into the DB. The stored file will also be encrypted.

It might be helpful to extend the Model file Ikechukwukalu\Clamavfileupload\Models\FileUpload and add the following code:

use Illuminate\Support\Facades\Crypt;

    protected function getFileNameAttribute($value)
    {
        if ($this->hashed) {
            return Crypt::decryptString($value);
        }

        return $value;
    }

    protected function getPathAttribute($value)
    {
        if ($this->hashed) {
            return Crypt::decryptString($value);
        }

        return $value;
    }


    protected function getRelativePathAttribute($value)
    {
        if ($this->hashed) {
            return Crypt::decryptString($value);
        }

        return $value;
    }

    protected function getUrlAttribute($value)
    {
        if ($this->hashed) {
            return Crypt::decryptString($value);
        }

        return $value;
    }

Sample codes to view and download encrypted file:

use Illuminate\Http\Request;
use Ikechukwukalu\Clamavfileupload\Models\FileUpload as FileUploadModel;
use Symfony\Component\HttpFoundation\StreamedResponse;

Route::get('/download/hashed/file/{id}', function (Request $request, $id): StreamedResponse {
    $file = FileUploadModel::where('id', $id)->first()

    return response()->streamDownload(function () use($file) {
        echo Crypt::decrypt(Storage::disk($file->disk)->get($file->relative_path));
    }, "{$file->name}{$file->extension}");
});

Route::get('/view/hashed/file/{id}', function (Request $request, $id) {
    $file = FileUploadModel::where('id', $id)->first();
    $decrypted = Crypt::decrypt(Storage::disk($file->disk)->get($file->relative_path));

    header("Content-type: {$file->mime_type}");
    echo $decrypted;
});

EVENTS

/**
 * Dispatches when FileUpload::uploadFiles()
 * is called.
 *
 */
\Ikechukwukalu\Clamavfileupload\Events\ClamavFileScan::class

/**
 * Dispatches when QueuedFileUpload::uploadFiles()
 * is called.
 *
 * @param  array  $tmpFiles
 * @param  array  $settings
 * @param  string  $ref
 */
\Ikechukwukalu\Clamavfileupload\Events\ClamavQueuedFileScan::class

/**
 * Dispatches when all files scanned are safe.
 *
 * @param  array  $scanData
 */
\Ikechukwukalu\Clamavfileupload\Events\FileScanPass::class

/**
 * Dispatches when a file scanned has a problem.
 *
 * @param  array  $scanData
 */
\Ikechukwukalu\Clamavfileupload\Events\FileScanFail::class

/**
 * Dispatches when files have been stored and saved into the Database.
 *
 * @param  FileUploadModel|EloquentCollection $files
 * @param  string  $ref
 */
\Ikechukwukalu\Clamavfileupload\Events\SavedFilesIntoDB::class

/**
 * Dispatches when clamav is not running.
 *
 */
\Ikechukwukalu\Clamavfileupload\Events\ClamavIsNotRunning::class

/**
 * Dispatches when file soft delete fails.
 *
 * @param  array  $data
 */
\Ikechukwukalu\Clamavfileupload\Events\FileDeleteFail::class

/**
 * Dispatches when file soft delete passes.
 *
 * @param  array  $data
 */
\Ikechukwukalu\Clamavfileupload\Events\FileDeletePass::class

/**
 * Dispatches when permanent file delete from database and disk fails.
 *
 * @param  array  $data
 */
\Ikechukwukalu\Clamavfileupload\Events\FileForceDeleteFail::class

/**
 * Dispatches when permanent file delete from database and disk passes.
 *
 * @param  array  $data
 */
\Ikechukwukalu\Clamavfileupload\Events\FileForceDeletePass::class

/**
 * Dispatches when a QueuedFileUpload::deleteAll($ref) is called.
 *
 * @param  string  $ref
 */
\Ikechukwukalu\Clamavfileupload\Events\QueuedDeleteAll::class

/**
 * Dispatches when a QueuedFileUpload::deleteMultiple($ids, $ref) is called.
 *
 * @param  string  $ref
 * @param  array  $ids
 */
\Ikechukwukalu\Clamavfileupload\Events\QueuedDeleteMultiple::class

/**
 * Dispatches when a QueuedFileUpload::deleteOne($id, $ref) is called.
 *
 * @param  string  $ref
 * @param  int|string  $id
 */
\Ikechukwukalu\Clamavfileupload\Events\QueuedDeleteOne::class

/**
 * Dispatches when a QueuedFileUpload::forceDeleteAll($ref) is called.
 *
 * @param  string  $ref
 */
\Ikechukwukalu\Clamavfileupload\Events\QueuedForceDeleteAll::class

/**
 * Dispatches when a QueuedFileUpload::forceDeleteMultiple($ids, $ref) is called.
 *
 * @param  string  $ref
 * @param  array  $ids
 */
\Ikechukwukalu\Clamavfileupload\Events\QueuedForceDeleteMultiple::class

/**
 * Dispatches when a QueuedFileUpload::forceDeleteOne($id, $ref) is called.
 *
 * @param  string  $ref
 * @param  int|string  $id
 */
\Ikechukwukalu\Clamavfileupload\Events\QueuedForceDeleteOne::class

NOTE

When a single file scanned fails, the process is ended and every uploaded file is removed.
Every batch of uploaded files has a $ref UUID assigned to them.
When using s3 disk, files are first stored in a tmp directory using the local disk where they will be scanned before being uploaded to the s3 bucket
Always add custom s3 disks to the s3_disk array within the configurations file.
Model file Ikechukwukalu\Clamavfileupload\Models\FileUpload

protected $fillable = [
    'ref',
    'name',
    'file_name',
    'size',
    'extension',
    'disk',
    'mime_type',
    'path',
    'url',
    'folder',
    'hashed',
];

PUBLISH LANG

php artisan vendor:publish --tag=cfu-lang

LICENSE

The CFU package is an open-sourced software licensed under the MIT license.

ikechukwukalu / clamavfileupload

Maintainers

Details