jcdevvv/jc-storage-php-sdk

SDK PHP para integrar com a jc storage.

dev-main 2026-01-19 20:12 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.0

Suggests

• illuminate/support: Required for Laravel integration (^10.0|^11.0|^12.0)

MIT

• josuerx12

README

SDK PHP para integração com o serviço JC Storage - uma solução de armazenamento de arquivos na nuvem.

Requisitos

• PHP 8.1 ou superior
• Composer
• Extensão cURL habilitada

Instalação

composer require jcdev/jc-storage-php-sdk

Configuração

PHP Puro

<?php

require_once 'vendor/autoload.php';

use Jcdev\JcStorage\Client;

$client = new Client(
    accessKey: 'sua-access-key',
    secretKey: 'sua-secret-key'
);

Laravel

O pacote possui auto-discovery, então o ServiceProvider será registrado automaticamente.

1. Publique o arquivo de configuração:

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

2. Adicione as credenciais no arquivo .env:

JCSTORAGE_ACCESS_KEY=sua-access-key
JCSTORAGE_SECRET_KEY=sua-secret-key

3. (Opcional) Adicione o alias da Facade no config/app.php:

'aliases' => [
    // ...
    'JcStorage' => Jcdev\JcStorage\Laravel\Facades\JcStorage::class,
],

Uso

Upload de Arquivo

PHP Puro

<?php

use Jcdev\JcStorage\Client;
use Jcdev\JcStorage\Exceptions\StorageError;

$client = new Client('sua-access-key', 'sua-secret-key');

try {
    // Upload a partir de um arquivo local
    $fileContent = file_get_contents('/caminho/para/arquivo.jpg');
    
    $result = $client->storage()->upload([
        'bucket'    => 'meu-bucket',
        'buffer'    => $fileContent,
        'filename'  => 'foto-perfil.jpg',
        'mimeType'  => 'image/jpeg',
        'isPrivate' => false, // opcional, default: false
    ]);

    echo "Arquivo enviado com sucesso!\n";
    echo "URL: " . $result['url'] . "\n";
    echo "ID: " . $result['file']['id'] . "\n";

} catch (StorageError $e) {
    echo "Erro: " . $e->getMessage() . "\n";
    echo "Status Code: " . $e->statusCode . "\n";
}

Laravel (usando Facade)

<?php

use Jcdev\JcStorage\Laravel\Facades\JcStorage;
use Jcdev\JcStorage\Exceptions\StorageError;

// Em um Controller
public function upload(Request $request)
{
    $request->validate([
        'file' => 'required|file|max:10240', // 10MB max
    ]);

    try {
        $file = $request->file('file');
        
        $result = JcStorage::storage()->upload([
            'bucket'    => 'meu-bucket',
            'buffer'    => file_get_contents($file->getRealPath()),
            'filename'  => $file->getClientOriginalName(),
            'mimeType'  => $file->getMimeType(),
            'isPrivate' => false,
        ]);

        return response()->json([
            'success' => true,
            'url'     => $result['url'],
            'file'    => $result['file'],
        ]);

    } catch (StorageError $e) {
        return response()->json([
            'success' => false,
            'error'   => $e->getMessage(),
        ], $e->statusCode);
    }
}

Laravel (usando Dependency Injection)

<?php

use Jcdev\JcStorage\Client;
use Jcdev\JcStorage\Exceptions\StorageError;

class FileController extends Controller
{
    public function __construct(
        private readonly Client $jcStorage
    ) {}

    public function upload(Request $request)
    {
        $file = $request->file('file');
        
        $result = $this->jcStorage->storage()->upload([
            'bucket'    => 'meu-bucket',
            'buffer'    => file_get_contents($file->getRealPath()),
            'filename'  => $file->getClientOriginalName(),
            'mimeType'  => $file->getMimeType(),
            'isPrivate' => true,
        ]);

        return response()->json($result);
    }
}

Deletar Arquivo

PHP Puro

<?php

use Jcdev\JcStorage\Client;
use Jcdev\JcStorage\Exceptions\StorageError;

$client = new Client('sua-access-key', 'sua-secret-key');

try {
    $client->storage()->delete('file-id-aqui');
    echo "Arquivo deletado com sucesso!\n";
} catch (StorageError $e) {
    echo "Erro ao deletar: " . $e->getMessage() . "\n";
}

Laravel

<?php

use Jcdev\JcStorage\Laravel\Facades\JcStorage;

// Deletar arquivo
JcStorage::storage()->delete($fileId);

Obter URL Temporária para Arquivo Privado

Arquivos marcados como privados precisam de uma URL assinada para serem acessados.

PHP Puro

<?php

use Jcdev\JcStorage\Client;
use Jcdev\JcStorage\Exceptions\StorageError;

$client = new Client('sua-access-key', 'sua-secret-key');

try {
    $result = $client->storage()->getPrivateFileUrl('file-id-aqui');
    
    echo "URL temporária: " . $result['url'] . "\n";
    echo "Expira em: " . $result['expires_at'] . "\n";
    
} catch (StorageError $e) {
    echo "Erro: " . $e->getMessage() . "\n";
}

Laravel

<?php

use Jcdev\JcStorage\Laravel\Facades\JcStorage;

$result = JcStorage::storage()->getPrivateFileUrl($fileId);

return response()->json([
    'url'        => $result['url'],
    'expires_at' => $result['expires_at'],
]);

Tratamento de Erros

O SDK lança a exceção StorageError quando ocorre um erro na API:

<?php

use Jcdev\JcStorage\Exceptions\StorageError;

try {
    // Operação que pode falhar...
} catch (StorageError $e) {
    // Mensagem de erro
    $message = $e->getMessage();
    
    // Código de status HTTP
    $statusCode = $e->statusCode;
    
    // Resposta completa da API (se disponível)
    $response = $e->response;
}

API Reference

Client

Método	Descrição
storage()	Retorna a instância do StorageService
http()	Retorna o cliente Guzzle HTTP
request($method, $uri, $options)	Executa uma requisição HTTP genérica

StorageService

Método	Parâmetros	Retorno	Descrição
upload($data)	array{bucket, buffer, filename, mimeType, isPrivate?}	array{file, url}	Faz upload de um arquivo
delete($fileId)	string	void	Deleta um arquivo pelo ID
getPrivateFileUrl($fileId)	string	array{url, expires_at}	Gera URL temporária para arquivo privado

Parâmetros do Upload

Parâmetro	Tipo	Obrigatório	Descrição
bucket	string	Sim	Nome do bucket onde o arquivo será armazenado
buffer	string	Sim	Conteúdo binário do arquivo
filename	string	Sim	Nome do arquivo (com ou sem extensão)
mimeType	string	Sim	Tipo MIME do arquivo (ex: image/jpeg)
isPrivate	bool	Não	Se true, arquivo será privado. Default: false

Exemplos Práticos

Upload de Imagem com Redimensionamento (Laravel + Intervention Image)

<?php

use Intervention\Image\Facades\Image;
use Jcdev\JcStorage\Laravel\Facades\JcStorage;

public function uploadAvatar(Request $request)
{
    $request->validate(['avatar' => 'required|image|max:5120']);

    $image = Image::make($request->file('avatar'))
        ->fit(200, 200)
        ->encode('jpg', 80);

    $result = JcStorage::storage()->upload([
        'bucket'    => 'avatars',
        'buffer'    => (string) $image,
        'filename'  => 'avatar-' . auth()->id() . '.jpg',
        'mimeType'  => 'image/jpeg',
        'isPrivate' => false,
    ]);

    auth()->user()->update(['avatar_url' => $result['url']]);

    return back()->with('success', 'Avatar atualizado!');
}

Upload de PDF em PHP Puro

<?php

require 'vendor/autoload.php';

use Jcdev\JcStorage\Client;

$client = new Client('sua-access-key', 'sua-secret-key');

if ($_SERVER['REQUEST_METHOD'] === 'POST' && isset($_FILES['documento'])) {
    $file = $_FILES['documento'];
    
    $result = $client->storage()->upload([
        'bucket'    => 'documentos',
        'buffer'    => file_get_contents($file['tmp_name']),
        'filename'  => $file['name'],
        'mimeType'  => $file['type'],
        'isPrivate' => true,
    ]);

    echo json_encode(['success' => true, 'file' => $result]);
}

Licença

Este pacote é open-source e está licenciado sob a MIT License.

Autor

• Josué - josuerx12 - [e-mail]

Contribuindo

Contribuições são bem-vindas! Por favor, abra uma issue ou envie um pull request.

1. Fork o projeto
2. Crie sua feature branch (git checkout -b feature/nova-feature)
3. Commit suas mudanças (git commit -m 'Adiciona nova feature')
4. Push para a branch (git push origin feature/nova-feature)
5. Abra um Pull Request