README

Documentation

Requirements
Installation
Instantiate
Amazon Aws S3
Global Config
INPUT HTML STRUCTURE
Response Data
- Get Message
- Get Status
- Get Class
- First
- Get
- Form
- Unlink
Usage
- Name
- Driver
- BaseDir
- Generate
- Folder
- Filter
- Structure
- Size
- Limit
- Mime
- Width
- Height
- Validate
- Save
- Resize
- WaterMark
- Compress
- Get External Image Size
- Get Uploaded Image Size
- Get Mime Type
- Not Empty
- Is Empty
- Has Error
- Is Completed
- Mime Types
Useful links

Requirements

>= php 8.0+

Installation

Prior to installing support package get the Composer dependency manager for PHP because it'll simplify installation.

composer require tamedevelopers/file

Instantiate

Step 1 — Composer Instantiate class using:

require_once __DIR__ . '/vendor/autoload.php';

use Tamedevelopers\File\File;

$file = new File();

Example 2

require_once __DIR__ . '/vendor/autoload.php';

$file = new Tamedevelopers\File\File();

or -- Helpers Function

$file = TameFile();

Amazon Aws S3

To use s3 first require composer require aws/aws-sdk-php
By default Aws load entire SDK we won't be needing
- Copy the below code into your root composer.json and then run composer update in terminal.

"scripts": {
    "pre-autoload-dump": "Aws\\Script\\Composer\\Composer::removeUnusedServices"
},
"extra": {
    "aws/aws-sdk-php": [
        "Ec2",
        "CloudWatch"
    ]
}

Global Config

Configure The Global Config, so you don't have to always include default settings
- Define as named argument

config_file(
    message: [
        '401'   => 'Select file to upload',
        '402'   => 'File upload is greater than allowed size of:',
        '403'   => 'Maximum file upload exceeded. Limit is:',
        '404'   => 'Uploaded file format not allowed. Allowed formats:',
        '405'   => 'Image dimension allowed is:',
        '405x'  => 'Image dimension should be greater than or equal to:',
        '200'   => 'File uploaded successfully:',
        'kb'    => 'kb',
        'mb'    => 'mb',
        'gb'    => 'gb',
        'and'   => 'and',
        'width' => 'width',
        'height'=> 'height',
        'files' => 'files',
        'file'  => 'file',
    ],
    config: [
        'limit'         => 1,
        'mime'          => 'image', // video|audio|file|image|zip|pdf|xls|doc|general_image|general_media|general_file
        'size'          => '2mb',
        'baseDir'       => 'public',
        'driver'        => 'local',
        'structure'     => 'default', // default|year|month|day
        'generate'      => true, // will always generate a unique() name for each uploaded file
    ],
    class: [
        'error'     => 'bg-danger',
        'success'   => 'bg-success',
    ]
);

or -- using file class method Global Config

(new File)->globalConfig(
    message: [], 
    config: [],
    class: []
);

INPUT HTML STRUCTURE

<input type="file" name="avatar">

or -- For Multiple Data

<input type="file" name="avatar[]" multiple>

Response Data

How to retrieve data

Get Message

This will return error message

$file = File::name('html_input_name');

$file->getMessage();

$file->getMessage('new Message');

Get Status

This will return error status code

$file = File::name('html_input_name');

$file->getStatus();

Get Class

This will only return msg, if there's an error or success

$file = File::name('html_input_name');

$file->getClass();

First

This will get the first uploaded data
- [optional] You can pass the mode as string name | path|url

->save(function($response){

    $response->first();
});

or

$upload = File::name('avatar')
                ->save();

$upload->first('url);

Get

This will get all uploaded data
- Returns an index array of all uploaded data, [name, path, url]
- [optional] You can pass the mode as string name | path|url

->save(function($response){

    $response->get();
});

or

$upload = File::name('avatar')
            ->save();

$upload->get('name);

Form

Return form request data
- This will return validator package object Validator

->save(function($response){

    $response->form();
});

Unlink

Accepts two param as string. This method uses the base path automatically.
- [mandatory] $fileToUnlink Path to file, you want to unlink.
- [optional] $checkFile. This will check if $fileToUnlink is not same, before.

->save(function($response){

    $userAvatar;

    $response->unlink("public/images/{$userAvatar}", "avatar.svg");

    <!-- the above will only unlink when value is not avatar.svg -->
});

Usage

Name

Takes one param string as input name
- Static method by default

File::name('html_input_name');

Driver

More drivers are to be added in the future
- By default driver is set to local

File::name('avatar')
    ->driver('s3');

using driver if project is not in any Frameworks

use Tamedevelopers\Support\Env;

// if your project is not on on core php, then you'll need to load env.
// this will create env dummy data and as well load the .env file.
// once data has been created, you can remove the `Env::createOrIgnore();`


Env::createOrIgnore();
Env::load();

File::name('avatar')
    ->driver('s3');

BaseDir

Takes one param string as base directory name
- This will override the global configuration settings (Domain and Server Path will be set)

File::name('avatar')
    ->baseDir('newBaseDirectory');

Generate

Takes one param bool

File::name('avatar')
        ->generate(false);

Folder

Takes one param string as folder_path to save file

File::name('avatar')
    ->folder('upload/user');

Filter

Takes index or closed array index
- Remove error status code you do not want to validate
- You cannot remove Error 200

File::name('avatar')
    ->filter(401, 402);

or

File::name('avatar')
    ->filter([401, 402, 405]);

Structure

Takes one param string as structure type
- Best used for Media\|Blog\|Newsletter Websites.

Default
- Year
  - Month
    - Day

File::name('avatar')
    ->structure('month');

Size

Takes one param string | int
- size in int | kb | mb | gb

File::name('avatar')
    ->size('1.5mb'); // will be converted to:  1.5 * (1024 * 1024) = 1572864

or

File::name('avatar')
    ->size(2097152); // = 2097152|2mb

Limit

Takes one param string | int
- Default limit is set to 1 upload

File::name('avatar')
    ->limit(2);

Mime

Takes one param string as mime type
- Goto Mime Types to see list

File::name('avatar')
    ->mime('image');

Width

Takes two param string | int and bool
- 1st param is string | int. width size
- 2nd param is bool. This allow to check if size should be === or >= size of uploaded image. Default is true

$file = File::name('avatar')
        ->width(700, false);

dd(
    $file
);

Height

Same as width method

File::name('avatar')
    ->width(700)
    ->height(400);

Validate

[optional] Method can be use, to return error message.
- Takes an [optional] param as a callable\|closure function.

File::name('banner')
    ->folder('upload/banner')
    ->validate(function($response){

        // perform any other needed task in here
        echo $response->getMessage();
        return;
    });

Save

Takes an [optional] param as a callable\|closure function.
- Calling this [method] will automatically save the data.

File::name('banner')
    ->folder('upload/banner')
    ->save(function($response){

        // perform any other needed task in here
    });

or

$file = File::name('banner')
            ->folder('upload/banner')
            ->save();

dd(
    $file->get(),
    $file->first(),
);

Resize

Takes two param as size int width and height
- Returns an instance of self

File::name()
    ->folder('upload/banner')
    ->save(function($response){

        // perform resize
        // width, height
        $response->resize(400, 400);
    });

WaterMark

Takes three param watermarkSource | position | padding
- [mandatory] $watermarkSource
- Returns an instance of self
- Padding is applied evenly on all position apart from center

File::name('avatar')
    ->folder('upload/banner')
    ->save(function($response){

        // perform watermark
        $response->watermark('watermark.png', 'center', 50);
    });

Compress

Returns an instance of self

File::name('avatar')
    ->folder('upload/banner')
    ->save(function($response){

        // perform compressor
        $response->compress();

        // you can perform method chaining as well
        $response->resize(200, 450)
                    ->watermark('watermark.png', 'center')
                    ->compress();
        
    });

Get External Image Size

Takes one param as string
- Return an array | null

File::getImageSize('full_source_path')

[
  ["height"]    => int(4209)
  ["width"]     => int(3368)
]

Get Uploaded Image Size

Takes one param as string
- Return an array | null

File::imageSize('name_of_uploaded_file')

[
  ["height"]    => int(4209)
  ["width"]     => int(3368)
]

Get Mime Type

Takes one param as string
- Return string | bool. false on error.

File::getMimeType('full_source_path')

Not Empty

Takes one param as string. Input file name
- Return bool true | false

File::notEmpty('avatar');
File::isNotEmpty('avatar');
File::has('avatar');

Is Empty

Same as not empty

File::isEmpty('avatar')

Has Error

Returns true or false. Check if there's an error in the upload

$file = File::name('avatar')

if($file->hasError()){

}

Is Completed

Returns true or false. Check if upload has been completed

$file = File::name('avatar')

if($file->isCompleted()){

}

Mime Types

File::name('invoiceDescription')
    ->mime('zip') 
    ->save();

Useful Links

@author Fredrick Peterson (Tame Developers)
If you love this PHP Library, you can Buy Tame Developers a coffee

tamedevelopers / file

Maintainers

Details

README

Documentation

Requirements

Installation

Instantiate

Amazon Aws S3

Global Config

INPUT HTML STRUCTURE

Response Data

Get Message

Get Status

Get Class

First

Get

Form

Unlink

Usage

Name

Driver

BaseDir

Generate

Folder

Filter

Structure

Size

Limit

Mime

Width

Height

Validate

Save

Resize

WaterMark

Compress

Get External Image Size

Get Uploaded Image Size

Get Mime Type

Not Empty

Is Empty

Has Error

Is Completed

Mime Types

Useful Links