MuCRMDocs
Site

uploaded_file (MUCRM\engine\support\uploaded_file)

O objeto uploaded_file é retornado pelo método request()->file('key'). Ele encapsula o arquivo enviado via formulário e fornece métodos fluídos para validação, leitura de informações, manipulação de imagem, armazenamento, conversão WebP e upload seguro.

Obtendo Arquivos

Via Request

Ideal dentro de controllers.

$file = request()->file('image');

Via Classe Estática

Ideal para services, helpers e classes externas.

use MUCRM\engine\support\uploaded_file;

$file = uploaded_file::file('image');

Verificando Existência

request()->has_file('banner');

ou

uploaded_file::has('banner');

Métodos Disponíveis

get_client_original_name()

Retorna o nome original do arquivo enviado pelo usuário.

$name = request()->file('image')->get_client_original_name();

get_client_original_extension()

Retorna a extensão em minúsculo.

$ext = request()->file('image')->get_client_original_extension();

get_mime_type_original()

Retorna o MIME Type real do arquivo.

$mime = request()->file('image')->get_mime_type_original();

get_real_path()

Retorna o caminho exato do upload do temp_name.

$path = request()->file('image')->get_real_path();

is_valid_size(int $maxMb)

Valida o tamanho máximo do arquivo em MB.

if (!$file->is_valid_size(2)) {
    return res()->error('Arquivo deve ter no máximo 2MB')->back();
}

is_valid_mime(array $allowed)

Valida o tipo MIME permitido.

$allowed = [
    'image/jpeg',
    'image/png',
    'application/pdf'
];

if (!$file->is_valid_mime($allowed)) {
    return res()->error('Formato não permitido')->back();
}

Métodos de Armazenamento

store(string $path, string $name, array $allowedExts = [...])

Salva o arquivo original mantendo formato. Por padrão aceita apenas: jpg, jpeg, png, gif, webp. Você pode passar extensões extras no terceiro parâmetro.

$file->store('uploads/sliders', 'banner.gif');

Com extensões customizadas:

$file->store('uploads/docs', 'manual.pdf', ['pdf', 'docx', 'txt']);

store_as_webp

Redimensiona, converte para WebP e salva. Ideal para sliders, notícias, avatares, galerias e imagens do site.

$file->store_as_webp(
    'uploads/sliders',
    'banner_01.webp',
    1920,
    1080,
    85
);

store_as_guild_mark_bmp v3

Salva a marca da guild no formato esperado pelo cliente (BMP Wyd). Use o ID da guild já validado no banco do usuário logado.

use MUCRM\engine\support\uploaded_file;

$file = uploaded_file::resolve('logo');
$guildId = 12;

if ($file && $file->store_as_guild_mark_bmp('guilds', $guildId)) {
    // Sucesso — responda para a View ou JSON
}
💡Dica
uploaded_file::resolve('logo') obtém o arquivo do campo logo do request. Valide permissão da guild antes de salvar.

Exemplo Completo no Controller

public function store()
{
    $file = request()->file('banner');

    if ($file) {

        if (
            $file->is_valid_size(5) &&
            $file->is_valid_mime([
                'image/jpeg',
                'image/png'
            ])
        ) {

            $newName = md5(time() . $file->get_client_original_name()) . '.webp';

            $file->store_as_webp(
                'uploads/banners',
                $newName,
                1200,
                400
            );

            Slider::create([
                'path' => $newName
            ]);
        }
    }

    return res()->error('Processado!')->back();
}

Exemplo Inteligente (GIF mantém original)

$file = request()->file('slider');

$newName = md5(time());

if ($file->get_mime_type_original() === 'image/gif') {

    $fileName = $newName . '.gif';

    $file->store('uploads/sliders', $fileName);

} else {

    $fileName = $newName . '.webp';

    $file->store_as_webp(
        'uploads/sliders',
        $fileName,
        1920,
        1080
    );
}

Uso com Nullsafe Operator (PHP 8+)

Se o arquivo não existir, file() retorna null.

request()->file('avatar')?->store_as_webp(
    'uploads/avatar',
    'user.webp',
    300,
    300
);

Boas práticas

  • Sempre valide tamanho e MIME.
  • Use WebP para performance máxima.
  • Preserve GIF animado no formato original.
  • Gere nomes únicos com md5(), uniqid() ou UUID.
  • Nunca confie apenas na extensão do arquivo.
  • Organize uploads por pasta.

Resumo Rápido

$file = request()->file('image');

$file->get_client_original_name();
$file->get_client_original_extension();
$file->get_mime_type_original();

$file->is_valid_size(5);
$file->is_valid_mime(['image/png']);

$file->store('uploads', 'file.zip');

$file->store_as_webp(
    'uploads',
    'image.webp',
    800,
    600,
    85
);