Yükleme Kütüphanesi


    × Bunları biliyor muydunuz?
"Şablon sihirbazında (Wizard) (5.5.60) sürümünden beri döngülerin sonunda kullanılan : sembolünün kullanım zorunluluğu kaldırılmıştır."


Dosya yükleme işlevini yerine getiren sınıftır. Ayrıca çoklu dosya yüklemenize olanak sağlarken dosya işlemleri hakkında veya süreçte oluşan hatalar hakkında da bilgi alabilmenizi sağlar.

 

 

# Kurulum


ZN dağıtımları için kurulum gerekmez.

↓ composer require znframework/package-filesystem

 

 

# Uygulamalar


# Jquery & Ajax & SweetAlert ile Çoklu Dosya Yükleme
# DropzoneJS ile Dosya Yükleme 

 

 

# INI Yapılandırması


Dosya yüklemesi ile ilgili ini ayarlarını yapmak için aşağıdaki yolda yer alan upload ayarları kullanılır.

Dosya: Settings/Ini.php
array $settings = [] php.ini Oturum ayarları listesi.
Dosya: Settings/Htaccess.php
bool $status = false Settings bölümündeki ayarların .htaccess dosyasına kaydedilip kaydedilmeyeceğini belirler. TRUE olması durumda ayarlar .htaccess dosyasına kaydedilir. FALSE olması durumuda sadece php_ini üzerinden yapılandırmaya çalışır.

 

 

# Yöntemler


Upload::mimes(string ...$args) : this
Upload::convertName(mixed $convert = true) : this
Upload::encode(string $hash = 'md5') : this
Upload::encodeLength(int $encodeLength = 8) : this
Upload::prefix(string $prefix) : this
Upload::maxsize(scalar $maxsize = 0) : this
Upload::source(string $source = 'upload') : this
Upload::target(string $target = UPLOADS_DIR) : this
Upload::settings(array $set = []) : this
Upload::start(string $fileName = 'upload', string $rootDir = UPLOADS_DIR) : bool
Upload::isFile(string $inputFileName) : bool
Upload::info(string $info = NULL) : mixed
Upload::error() : mixed
Upload::clean() : void
Upload::progress(string $selector, string $source, callable $callback)

 

 

# Extensions


Hangi uzantılı dosyaların yüklenebilir olduğunu belirtmek için kullanılır.

Parametreler

string ...$extensions Yüklenebilir dosya uzantı türleri.
return this

Kullanımı

Upload::extensions('jpg', 'png', 'gif', 'txt')->start('file');

 

 

# Mimes


Dosya uzantıları o dosyanın gerçek kimliği hakkında bilgi vermez. Bu nedenle hangi tür dosyaların yükleneceğini sınırlamanız gerekir. Bu yöntem ile hangi mime türlerinin yüklenebilir olacağına karar verebilirsiniz.

Parametreler

string ...$mimes Yüklenebilir dosya içerik veri türleri.
return this

Kullanımı

Upload::mimes('image/jpeg', 'image/png')->start('file');

 

 

# ConvertName


Dosya isimlerinde yer alan yabancı veya özel karakterler slug tipine dönüştürülür.

Parametreler

mixed $convert = true Dosya adı slug tipine çevrilsin mi?. Parametre belirtilmezse true kabul edilerek çevirme işlemi yapılır. İsmi kendiniz belirlemek isterseniz bu parametreye string değer verin.
return this

Kullanımı

Upload::mimes('image/jpeg', 'image/png')
      ->convertName()
      ->start('file');

[string $convert]

Kendi belirleyeceğiniz isimlendirmeleri de kullanabilirsiniz.

Upload::mimes('image/jpeg', 'image/png')
      ->convertName('my-file')
      ->start('file');

 

 

# Encode


Yüklenen dosyaya şifreli bir ön ek ekler.

Parametreler

string $hash = 'md5' Ön ek hangi algoritma tarafından kodlanacağını belirtir.
return this

Kullanımı

Upload::mimes('image/jpeg', 'image/png')
      ->encode('sha1')
      ->start('file');
Dikkat: prefix() kullanımı bu yöntemin işlevini devre dışı bırakır.

 

 

# EncodeLength 


Şifrelenen ön ekin uzunluğunu ayarlamak için kullanılır.

Parametreler

int $length = 8 Şifreli ön ekin kaç karakterden oluşacağı belirtilir.
return this

Kullanımı

Upload::mimes('image/jpeg', 'image/png')
      ->encode('sha1')
      ->encodeLength(10)
      ->start('file');

 

 

# Prefix


Yüklenen dosyaya kendi belirleyeceğiniz ön ek eklemek için kullanılır. Bu yöntemin encode() ile beraber kullanılması durumunda encode() işleme alınmaz.

Parametreler

string $prefix Ön ek.
return this

Kullanımı

Upload::mimes('image/jpeg', 'image/png')
      ->encode(false)
      ->prefix(time())
      ->start('file');

 

 

# Maxsize 


Yüklenen dosyanın boyutunun byte cinsinden en fazla kaç olacağını belirtmek için kullanılır. Bu parametreye string veride atayabilirsiniz. Doğrudan bayt miktarı göndermek yerine 20MB, 5KB gibi string verilerde kullanabileceksiniz.

Parametreler

scalar $maxsize = 0 Yüklenen dosyanın maksimum boyutu. Boyut ister byte cinsinden isterseniz string türde belirtilebilir.
return this

Kullanımı

Upload::mimes('image/jpeg', 'image/png')
      ->maxsize(1024 * 1024 * 20) // 20 MB
      ->start('file');

[string $maxsize]

Upload::mimes('image/jpeg', 'image/png')
      ->maxsize('20MB')
      ->start('file');

 

 

# Source


start() yönteminin 1. parametresi ile aynı görevi görür. Input file form nesnesinin name değerini temsil eder. Yani dosyanın hangi kaynaktan yüklendiğidir.

Parametreler

string $name = 'upload' Form::file() nesnesinin name değeri.
return this

Kullanımı

Upload::mimes('image/jpeg', 'image/png')
      ->maxsize(1024 * 1024 * 20) // 20 MB
      ->source('file')
      ->start();

 

 

# Target


start() yönteminin 2. parametresi ile aynı görevi görür. Dosyanın nereye yükleneceğidir. Dosyaların Ön tanımlı olarak yükleneceği dizin her projenin kendi Resources/Uploads/ dizinidir

Parametreler

string $target = UPLOADS_DIR Dosyaların yükleneceği dizin.
return this

Kullanımı

Upload::mimes('image/jpeg', 'image/png')
      ->maxsize(1024 * 1024 * 20) // 20 MB
      ->source('file')
      ->target(FILES_DIR . 'my_uploads/')
      ->start();

Ya da;

Upload::mimes('image/jpeg', 'image/png')
      ->maxsize(1024 * 1024 * 20) // 20 MB
      ->start('file', FILES_DIR . 'my_uploads/');

gibi kullanabilirsiniz.

 

 

# Settings


Yukarıda opsiyonel yöntemlerin yaptığı ayarları dizi olarak yapabilmek için kullanılır.

Parametreler

array $settings Dosya yükleme ayarlarını yapılandırmak içindir.
string $extensions Hangi uzantılı dosyaların yükleneceğini belirlemek için kullanılır. Uzantılar dik çizgi(|) kullanılarak belirtilir.
string $mimes Hangi dosya türlerinin yükleneceğini belirlemek için kullanılır. Uzantılar dik çizgi(|) kullanılarak belirtilir.
string $encode = 'md5' Yüklenecek dosyaya eklenecek şifreli ön ek için hangi şifreleme algoritmasının kullanılacağı belirtilir.
int $encodeLength = 8 Şifre uzunluğu belirtilir.
string $prefix Yüklenecek dosya ön ek koymak için kullanılır.
int $maxsize Yüklenecek dosyanın byte cinsinden maksimum boyutunu belirlemek için kullanılır.
bool $convertName = true Yabancı karakterler dönüştürülsün mü? Bu kullanımın amacı yabancı karakterlerden doğan yükleme sorununun önüne geçmektir.
return this

Kullanımlar

Upload::settings
([
    'encode'     => false,
    'prefix'     => '__prefix__',
    'extensions' => 'jpg|png|gif',
    'maxsize'    => 8096
]);

Yukarıdaki her bir ayar için opsiyonel yöntemde kullanılabilir.

 

 

# Start


Dosya yükleme işlemini başlatır.

Parametreler

string $fileInputName Form input file nesnesinin adı.
string $target = UPLOADS_DIR Dosyaların yükleneceği dizin.
return bool

Kullanımlar

Upload::settings
([
    'encode'     => false,
    'prefix'     => '__prefix__',
    'extensions' => 'jpg|png|gif',
    'maxsize'    => 8096
])->start('upload');

Opsiyonel Yöntemler ile Yapılandırma

Yukarıdaki işlemi opsiyonel seçeneklerle yapmak isterseniz;

Upload::encode(false)
      ->prefix('__prefix__')
      ->extensions('jpg', 'png', 'gif')
      ->maxsize(8*96)
      ->target('DirrentUploadDir')
      ->start('upload');

Yukarıda start('upload') yönteminde kullanılan upload yükleme işlemine konu olan <form input="file" name="upload"> nesnesinin name değeridir.

 

 

# IsFile 


Html [input="file"] nesnesinin değer alıp almadığını kontrol etmek için kullanılır. $_FILES['file']['name'] kullanımı gibidir.

Parametreler

string $inputFileName Html input nesnesinin adı.
return this

Kullanımı

if( Upload::isFile('upload') )
{
    Upload::start('upload');
}

 

 

# Info


Dosya işlemleri sırasında dosya hakkında bilgi almak için kullanılır. Verileri object veri tipinde döndürür. Tek bir bilgi kullanılacaksa parametre olarak bilgi ismi yazılabilir.

Parametreler

string $infoName = NULL Hangi bilginin istendiği.
name Dosya adı.
type Dosya türü.
size Dosya boyutu.
tmpName Dosya temp dizinindeki adı.
error Hata numarası.    
path Dosyanın yüklendiği yol.
encodeName Dosyanın şifreli adı.
return mixed

Kullanımlar

Dosya: Views/UploadExample/main.php
<?php
echo Form::enctype('multipart')->open('form');
echo Form::file('uploadFile');
echo Form::submit('uploadButton');
echo Form::close();
Dosya: Controllers/UploadExample.php
Upload::settings
([
    'encode'     => false,
    'prefix'     => '__prefix__',
    'extensions' => 'jpg|png|gif',
    'maxsize'    => 8096
])->start('uploadFile');

output( Upload::info() );
name       => string 'logosmall.png' ( length = 18 ),
type       => string 'image/png' ( length = 11 ),
size       => integer 129296 ( length = 6 ),
tmpName    => string 'xampp7/tmp/php26E9.tmp' ( length = 27 ),
error      => integer 0 ( length = 1 ),
path       => string 'xampp7/htdocs/zeroneed/Projects/Frontend/Resources/Uploads/__prefix__logosmall.png' ( length = 86 ),
encodeName => string '__prefix__logosmall.png' ( length = 24 )
$info = Upload::info();

echo $info->encodeName;
 __prefix__logosmall.png
Çoklu Dosya Yükleme Bilgisi

Çoklu dosya yükleme durumunda Upload::info() içerisinde yer alan tüm anahtarların değeri her bir yüklenen dosya için dizi türünden bilgi saklar.

$info = Upload::info();

echo $info->encodeName[0];
 __prefix__logosmall.png

Yüklenen dosya bilgilerinin veritabanına kaydedilmesi gerektiği zamanlarda döngü kullanarak kayıt işlemi yaptırabilirsiniz.

$info = Upload::info();

foreach( $info->encodeName as $encodeName )
{
    DB::insert('images', ['path' => $encodeName]);
}

 

 

# Error


Yükleme işleminden sonra herhangi bir hatanın oluşup oluşmadığı hakkında bilgi verir.

Parametreler

return mixed

Kullanımlar

output( Upload::error() );

 

 

# Clean [7.5.0][2022-09-09]


Yüklenen dosyaları geri silmek için kullanılır. Özellikle çoklu yüklemede belirtilen kurallara uymayan dosyaların yüklenememesinden sonra aynı yüklemede yüklenen dosyaların silinmesi için kullanılabilir.

Kullanımlar

if( Upload::error() )
{
    Upload::clean()
}

 

 

# Progress [6.12.0][2021-05-30]


Bu yöntem arka planda javascript kullanarak yüklenen dosyaların toplam boyutu, yüklenen miktar ve yüzde bilgilerinin alınmasını sağlar. Jquery kullanıldığı için bu eklentinin dahil edilmiş olması gerekir.

Parametreler

string $selector Yükleme işlemini başlatacak ilgili butonun erişim seçicisi.
string $source Yükleme işlemini gerçekleştirecek Form::file() nesnesinin erişim seçicisi.
callable $callback(percent, loaded, total)
Gerçekleştirilecek işlemler. Bu parametre 3 değer içerir.
percent Yükleme yüzdesi.
loaded Byte cinsinden yüklenen boyut.
total Byte cinsinden toplam boyut.
return string

Kullanımı

Dosya: Example/upload.wizard.php
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.2.1/jquery.js"></script>

@Form::enctype('multipart')->open()
    @Form::file('upload')
    @Form::submit('button', 'Submit')
@Form::close()

@Upload::progress('input[name=button]', 'input[name=upload]', 
{<
    $('input[name=button]').val('%' + percent);
>})

 

 

# Jquery & Ajax & SweetAlert ile Çoklu Dosya Yükleme


Jquery ile ajax kullanarak dosya yüklemek için aşağıdaki adımları takip edin.

Jquery Form Script'ini Dahil Edin

Sisteminizde javascript etiketleriniz nerede yer alıyorsa aşağıdaki komutu oraya ekleyin. Bu yer genellikle [head] [/head] etiketlerinin arasıdır.

Dosya: Views/sections/head.wizard.php
@style('sweetAlert')
@script('jquery', 'sweetAlert')
Fomu Hazırlayın

Dosya yüklemesi için form elementinin enctype değerini düzenlemeyi unutmayın.

Dosya: Views/Home/main.wizard.php
@Form::id('uploadForm')->enctype('multipart')->open()
@Form::id('file')->file('upload', true)
@Form::onclick('ajaxDoUpload()')->button('uploadButton', 'Do Upload')
@Form::close()
JS Kodlarını Hazırlayın

Form değerlerini ilgili kontrolcüye gönderebilmek için ajax kodlarımızı oluşturuyoruz.

Dosya: Views/sections/footer.wizard.php
<script>
function ajaxDoUpload()
{
    var formData = new FormData($('#uploadForm')[0]); // Attach Form Object
 
    $.ajax
    ({
        url        : '{{ URL::site("Home/upload") }}',
        type       : 'post',
        dataType   : 'json',
        data       : formData,
        processData: false, // REQUIRED !!
        contentType: false, // REQUIRED !!
        success    : function(data)
        {
            if( data.success !== undefined )
            {
                swal("Your Successful Title", data.success, "success");
            }
            else
            {
                swal("Your Error Title", data.error, "error");
            }
        }
    });
}
</script>
Kontrolcüyü Hazırlayın

Aşağıdaki kullanım, amaçlarınıza göre genişletilebilir.

Dosya: Controllers/Home.php
public function upload() : void
{
    Upload::start('upload');

    if( $error = Upload::error() )
    {
        $data['error'] = $error;
    }
    else
    {
        $data['success'] = 'Your success messsage.';
    }

    echo json_encode($data);
}

 

 

# DropzoneJS ile Dosya Yükleme 


DropzoneJS ile ilgili detaylı kullanım için tıklayınız. Dropzone ile dosya yüklemek için aşağıdaki adımları takip edin.

Dropzone Script'ini Dahil Edin

Import kütüphanesini ile DropzoneJS'nin uzaktan linkini dahil edebilirsiniz. Sisteminizde javascript etiketleriniz nerede yer alıyorsa aşağıdaki komutu oraya ekleyin. Bu yer genellikle [head] [/head] etiketlerinin arasıdır.

Dosya: Views/sections/head.wizard.php
@style('dropzone')
@script('dropzone')
Formu Hazırlayın

Dosya yüklemesi için form elementinin enctype değerini düzenlemeyi unutmayın.

Dosya: Views/Home/main.wizard.php
@Form::action('Home/upload')->enctype('multipart')->class('dropzone')->open('form'):
<div class="fallback" id="fallback">
@Form::file('file', true):
</div>
@Form::close():
JS Kodlarını Hazırlayın

Dropzone nesnesinin 2. parametresi extra ayarları içerir. Bu parametrenin kullanımı için DropzoneJS kullanım kılavuzuna göz atın.

Dosya: Views/sections/footer.wizard.php
<script>
var dropzone = new Dropzone("#fallback");
</script>
Kontrolcüyü Hazırlayın

Aşağıdaki kullanım, amaçlarınıza göre genişletilebilir.

Dosya: Controllers/Home.php
public function upload() : void
{
    Upload::mimes('image/jpeg', 'image/png')
          ->prefix(time())
          ->start('file');
}