Forem: Danilo Correa

Compactar arquivos direto no S3 com PHP

Danilo Correa — Sat, 30 Dec 2023 15:00:56 +0000

Olá, pessoal! Tudo bem? Neste artigo, abordarei um assunto que parece simples à primeira vista, mas muitas vezes passa despercebido na forma como o implementamos em nosso código. Antes de começar, quero ressaltar que não há uma abordagem certa ou errada. No entanto, é possível antecipar alguns problemas que podem surgir no futuro.

Imagine o seguinte cenário: você possui uma coleção de arquivos no S3 e sua aplicação precisa compactar esses arquivos. Existem várias maneiras de implementar essa lógica, e se você está começando na área de desenvolvimento, não se preocupe. Comece com o cenário mais simples e, com o tempo, aprimore o seu código.

A seguir, vou descrever a Versão 1 do nosso cenário mais simples e, em seguida, a Versão 2 com algumas melhorias.

Versão 1

Como mencionei, imagine que você tenha uma lista de 10 ou mais arquivos no S3, e sua aplicação ou script precisa criar um arquivo zip com todos esses arquivos. Para esse cenário, apresentarei os passos de forma simplificada. Compartilhe nos comentários se você utiliza algo semelhante em seu trabalho.

Baixar cada arquivo do S3 de forma síncrona.
Salvar cada arquivo em um diretório do nosso sistema de arquivos.
Compactar todos os arquivos em um zip e salvar em nosso sistema de arquivos.
Carregar (upload) o arquivo zip para o S3.

Este é um fluxo comum que funciona bem. Não há nada de errado aqui, mas podemos melhorar muitos aspectos.

Versão 2

Agora, a brincadeira começa a ficar interessante! Na Versão 2 do nosso script, podemos aprimorar basicamente o seguinte: todos os arquivos podem ser baixados de forma assíncrona, permitindo que nosso script não espere um arquivo ser baixado totalmente para iniciar o próximo. Além disso, em vez de criar um arquivo zip no sistema de arquivos local, podemos criar um arquivo zip diretamente no S3. Isso mesmo! Dessa forma, podemos adicionar o conteúdo baixado de forma assíncrona ao zip que já está no S3, eliminando a necessidade de salvar algo em nosso sistema de arquivos.

Baixar o conteúdo de cada arquivo de forma assíncrona.
Criar um arquivo zip diretamente no S3 usando o SDK da AWS.
Para cada arquivo baixado de forma assíncrona, adicionar o conteúdo ao zip.
Quando tudo estiver concluído, fechar o arquivo.

Parece fácil quando explicado assim, não é? Não é tão simples na prática, mas também não é algo impossível. Vamos ver como fazer isso em PHP, certo?

Para facilitar, criei um repositório (clique aqui) no GitHub com alguns scripts prontos. Você pode clonar o repositório em sua máquina e executar em um ambiente local usando Docker ou conectar-se ao seu próprio ambiente AWS.

Preparando ambiente

Para começar, faça o clone do repositório e instale todas as dependências.

git clone git@github.com:dcorrea777/zipfile-s3.git

Após clonar o repositório, instale todas as dependências do projeto e ajuste as variáveis de ambiente, se necessário, no arquivo .env.

# Instalando os pacotes
composer install

# Criando um arquivo .env a partir do .env.example
cp .env.example .env

Abra o arquivo .env e ajuste os valores de acordo com o seu ambiente. As variáveis de ambiente incluem configurações para o serviço que simula o S3 localmente, informações do bucket local e credenciais da AWS.

# Serviço que simula o S3 em seu ambiente local
STORAGE_ENDPOINT="http://localhost:9000" 
# Aqui você escolhe qual tipo de driver você quer usar (local, s3)
STORAGE_DRIVER="local"
# Nome do bucket que é criado no ambiente local
STORAGE_NAME="zip" 
AWS_REGION="us-east-1"
# Credenciais da AWS
STORAGE_ACCESS_KEY="fake"
STORAGE_SECRET_KEY="fake"

Após instalar os pacotes e ajustar as variáveis do seu arquivo .env, vamos executar o docker-compose.yml para subir o serviço do minio. Basicamente o minio é um s3 rondando localhost, com isso podemos se conectar usando o proprio SDK da AWS para fazer nossos testes.

# Subir o serviço do minio
docker-compose up -d

# Verificar se o serviço esta sendo executado
docker-compose ps

Após subir o container do minio, você precisará fazer algumas configurações locais. Acesse o endereço http://localhost:9001 e faça login com as credenciais que estão no arquivo docker-compose.yml.

Exemplo

MINIO_ROOT_USER=admin
MINIO_ROOT_PASSWORD=supersecret

Depois de fazer login, você precisa gerar uma credencial de acesso em seu ambiente local, então vá em: Access Keys (Menu lateral na esquerda) >> Create access keys (Botão na direita) e clique em Create, use essas credenciais no seu arquivo .env.

# .env 
STORAGE_ACCESS_KEY="COLOQUE AQUI SUA ACCESS KEY"
STORAGE_SECRET_KEY="COLOQUE AQUI SUA SECRET KEY"

Para ambiente local, eu criei um arquivo upload-to-s3.php que gera 10 arquivos .txt com o tamanho de 2GB usando um comando do Linux. Lembrando que o docker-compose.yml apenas contém o serviço do minio. Estou partindo do princípio de que você tem o PHP instalado na sua máquina. Caso não tenha, eu escrevi outro artigo sobre como instalar o PHP na sua máquina usando o ASDF.

php upload-to-s3.php

Basicamente esse script gera os arquivos e os carrega no minio ou S3. Após executar o script, você pode acessar o minio e verificar se os arquivos existem no bucket zip.

Mão na massa!

Agora vamos para o que interessa. Antes de você executar o arquivo zip.php, vou explicar cada arquivo e pasta e no final você pode executar para testar, ok? Antes de falar do arquivo zip.php, que é o arquivo principal, vou comentar sobre a pasta config e seus arquivos.

Config > storage.php

Na pasta config, temos alguns arquivos de configuração para auxiliar na organização de nosso projeto. O arquivo storage.php basicamente é um arquivo de configuração, onde você escolhe se quer que seu código execute no minio ou no próprio S3 da AWS. Esse arquivo é carregado em nosso container de dependência.

Config > container.php

Como o nome já diz, é nosso arquivo de container de dependência. Todas as instâncias do nosso projeto estão aqui. Eu sei que a gente só tem uma, mas isso deixa o código mais organizado hahaha. Enfim, aqui estamos usando o pacote php-di para nosso container de dependência.

Config > bootstrap.php

E, por fim, nosso arquivo bootstrap.php instancia nosso container de dependência e retorna a própria instância. Além disso, carrega as variáveis de ambiente usando o pacote phpdotenv.

Zip.php

O nosso arquivo zip.php, que está na raiz do projeto, é onde contém todo o código que gera o arquivo zip no S3.

$container      = require_once __DIR__ . '/config/bootstrap.php';
$storage        = $container->get(S3ClientInterface::class);
$objectsToZip   = $container->get('files');

Aqui carregamos nosso container de dependência e pegamos a instância do AWS S3. Depois, carregamos todos os nomes de arquivos que fizemos upload no script upload-to-s3.php.

$storage->registerStreamWrapper();
$zipStream = fopen("s3://zip/example.zip", 'w');

Agora vamos prestar bastante atenção, porque aqui é onde acontece o pulo do gato hahah. A primeira linha basicamente cria um wrapper de todas as funções de arquivo do PHP, dessa forma você pode usar as próprias funções built-in do PHP para interagir com o S3. Basicamente, o fopen da segunda linha está criando um arquivo zip diretamente no S3 e não no sistema de arquivos local. Caso você tenha interesse em entender mais sobre isso, siga a documentação da própria AWS: S3 Stream Wrapper.

https://docs.aws.amazon.com/sdk-for-php/v3/developer-guide/s3-stream-wrapper.html

$zip = new ZipStream(
    outputStream: $zipStream,
    sendHttpHeaders: true,
);

No código acima, estamos criando uma instância do nosso zip usando a biblioteca maennchen/zipstream-php. Aqui é apenas uma instância, e perceba que estamos passando o stream do nosso arquivo zip que foi criado no S3 para ela como parâmetro.

$fulfilled = function (ResultInterface $result, $item, PromiseInterface $aggregatePromise) use ($zip, $objectsToZip) {
    dump("Downloaded file: " . $objectsToZip[$item]);
    $zip->addFileFromPsr7Stream(
        fileName: $objectsToZip[$item],
        stream: $result->get('Body'),
    );
    dump("Added in zip: " . $objectsToZip[$item]);
};

$before = function (CommandInterface $cmd, $iterKey) use ($objectsToZip) {
    dump('Starting download: ' . $cmd->toArray()['Key']);
};

Aqui estamos criando duas callbacks que serão executadas como eventos quando o processo do SDK da AWS for executado. Basicamente, estamos utilizando a classe CommandPool da AWS para executar de forma assíncrona vários comandos. Essas callbacks são executadas em determinada ação do nosso processo.

A callback $before é acionada quando o processo de carregar o arquivo é iniciado. No nosso exemplo, vamos executar o método GetObject, então toda vez que o método GetObject for executado, essa callback é acionada.

A callback $fulfilled é acionada quando um arquivo é carregado (Download for concluído). Toda vez que um arquivo for carregado, estou adicionando o conteúdo via stream $result->get('Body'), para o método $zip->addFileFromPsr7Stream(stream: $result->get('Body')) da nossa instância do zip. Com isso, toda vez que um arquivo é carregado, o mesmo já é adicionado no zip que já está no S3. Coisa linda, não é?

$commands = [];
foreach ($objectsToZip as $objectKey) {
    $commands[] = $storage->getCommand('getObject', [
        'Bucket'    => 'zip',
        'Key'       => $objectKey,
    ]);
}

Nesse trecho, precisamos montar uma lista de comandos que vão ser passados para um Pool de Comandos no SDK da AWS. Com isso, podemos executar vários processos de forma assíncrona. Veja que estou criando um Pool de Comandos GetObject e passando o nome do bucket e o nome do arquivo que quero baixar.

$pool = new CommandPool($storage, $commands, ['fulfilled' => $fulfilled, 'before' => $before]);
$promise = $pool->promise();
$promise->wait();
$zip->finish();

fclose($zipStream);

E, por fim, criamos uma instância de CommandPool. Para o objeto CommandPool, você precisa passar a instância do serviço que será executado (que é o S3 no nosso caso). Depois, você passa uma lista de comandos que serão executados, que no nosso caso é o getObject. E então, você tem uma lista onde define vários tipos de eventos que serão acionados. Por exemplo, você tem fulfilled, que é uma callback que será executada após cada comando ser finalizado; você tem o before, que é uma callback que é acionada antes de cada comando. Para ver todos os tipos de eventos que são suportados, acesse esta documentação:

https://docs.aws.amazon.com/sdk-for-php/v3/developer-guide/guide_commands.html

Após criar a instância do CommandPool, nós executamos o método $promise->wait(). Com isso, a lista de comandos é executada de forma assíncrona e o processo do PHP é bloqueado. Quando todos os comandos forem executados, o processo é desbloqueado e, por fim, a instância do zip é finalizada $zip->finish() e o arquivo no S3 é fechado fclose($zipStream).

Agora, execute o script zip.php em sua máquina e verifique se tudo ocorreu como o esperado. Caso ocorra algum erro ou tenha alguma dúvida, deixe-me saber nos comentários. Outro ponto que não comentei ao longo deste artigo é que todo conteúdo baixado e compactado é processado via stream. Isso permite que você execute esse processo em arquivos grandes, utilizando pouca memória em PHP. Como prova disso, execute o arquivo com o seguinte comando:

php -d memory_limit=128M zip.php

Estamos executando nosso script com apenas 128MB, mesmo lidando com arquivos que têm 2GB cada. Legal, não é?"

Conclusão

Partindo de um cenário simples em que executamos tudo de forma síncrona, esse segundo cenário trouxe-nos muitas melhorias. Agora podemos ter um script que pode ser executado na metade do tempo, sem a necessidade de armazenar nada em disco. Este é um caso de uso que implementei na empresa em que trabalhava. Todo esse processo era executado de forma assíncrona usando Lambda, Eventbridge e, é claro, PHP.

Ao executar isso em um ambiente Lambda, podemos enfrentar algumas limitações em relação ao tempo de execução e espaço em disco. No entanto, como no nosso segundo cenário não utilizamos o disco para baixar os arquivos, não enfrentamos mais esse problema.

Bom, acho que é isso, pessoal. Se gostou do artigo, não esqueça de compartilhar e deixar seu comentário =)

Criando seu ambiente com ASDF

Danilo Correa — Fri, 29 Dec 2023 17:20:00 +0000

Fala, galera, beleza? Neste artigo, vamos criar um ambiente utilizando uma ferramenta super poderosa chamada ASDF. Esta é uma ferramenta extremamente útil que utilizo no meu dia a dia. Basicamente, você consegue gerenciar múltiplas versões de aplicativos ou runtimes na sua máquina. Imagine que você está trabalhando no desenvolvimento de uma aplicação usando a nova versão do PHP 8.3, e também precisa fazer a manutenção daquele legadinho gostoso (quem nunca, né?). Com o ASDF, você consegue ter várias versões do PHP instaladas na sua máquina, e não apenas o PHP. Você pode ter Node.js, Docker Composer, .NET Core, Python, Terraform, AWS CLI, e muito mais.

O que é o ASDF ?
Vantagens
Mão na massa!
Instalando dependências para o ASDF
Instalando o ASDF
Instalando PHP 8.1, 8.2 e 8.3
Conclusão

O que é o ASDF?

ASDF é um gerenciador de versão de ferramentas. Todas as definições de versão estão contidas em um arquivo .tool-versions que você pode adicionar ao seu projeto Git para compartilhar com sua equipe, garantindo que todos estejam na mesma versão.

A maneira antiga de trabalhar exigia vários gerenciadores (nvm, n, rben, e phpbrew) de versão CLI, cada um com sua API, arquivos de configuração e implementação (por exemplo, manipulação de $PATH, variáveis de ambiente, etc.). ASDF fornece uma interface única e um arquivo de configuração para simplificar os fluxos de desenvolvimento e pode ser estendido a todas as ferramentas e runtimes por meio de uma interface simples.

Vantagens

ASDF garante que as equipes usem exatamente as mesmas versões de ferramentas, com suporte para muitas ferramentas por meio de um sistema de plugin e a simplicidade e familiaridade de ser um único script shell.

Utilizar apenas uma ferramenta para gerenciar as versões
Plugins escritos pela comunidade
Arquivo de configuração para gerenciar versões a partir de um diretório

Mão na massa!

Neste artigo, vou preparar um ambiente de desenvolvimento do zero utilizando o ASDF. Bora lá então! Para nosso ambiente, vamos instalar as seguintes ferramentas:

PHP 8.3
PHP 8.2
PHP 8.1

Instalando dependências do ASDF

Para este ambiente, vamos seguir a instalação via Linux. Para instalar o ASDF, acesse a página oficial da documentação: https://asdf-vm.com/

Antes de começar, precisamos instalar as dependências para o ASDF. https://asdf-vm.com/guide/getting-started.html#_1-install-dependencies

sudo apt-get install curl git

Instalando ASDF

A instalação do ASDF é bastante simples, utilizando o comando git clone.

Nota: O comando abaixo está usando a versão v0.13.1. Talvez esta versão esteja desatualizada; acesse o seguinte link e veja qual é a versão mais recente: https://asdf-vm.com/guide/getting-started.html#official-download

git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.13.1

Se você utiliza algum shell como zsh, fish e PowerShell, siga as configurações corretas para cada shell https://asdf-vm.com/guide/getting-started.html#_3-install-asdf

Após a instalação do ASDF, você pode executar o seguinte comando para verificar se tudo ocorreu bem na instalação.

asdf --version #v0.13.1

Agora que temos o ASDF instalado em nosso ambiente, precisamos entender como ele funciona.

Basicamente, você precisa adicionar os plugins das ferramentas que você deseja instalar. Neste cenário, queremos instalar o PHP, então precisamos procurar um plugin do ASDF para o PHP, e assim por diante para outras ferramentas ou linguagens de programação.

Instalando PHP 8.1, 8.2, 8.3

Para instalar o PHP, vamos utilizar o asdf-php, que é um plugin do ASDF para o PHP. https://github.com/asdf-community/asdf-php

Antes de tudo, precisamos registrar esse plugin em nosso ASDF com o seguinte comando:

asdf plugin-add php https://github.com/asdf-community/asdf-php.git

Após adicionar como plugin, precisamos instalar algumas dependências em nosso sistema operacional. No próprio repositório do plugin asdf-php, o autor fala sobre as dependências que precisam ser instaladas antes.

Nota: Essas dependências são do PHP e não do ASDF, pois o ASDF compila o PHP na sua máquina. Para facilitar, vou listá-las aqui.

sudo apt-get install -y \
    autoconf \
    bison \
    build-essential \
    gettext \
    libgd-dev \
    libcurl4-openssl-dev \
    libedit-dev \
    libicu-dev \
    libjpeg-dev \
    libmysqlclient-dev \
    libonig-dev \
    libpng-dev \
    libpq-dev \
    libreadline-dev \
    libsqlite3-dev \
    libssl-dev \
    libxml2-dev \
    libzip-dev \
    openssl \
    pkg-config \
    re2c \
    zlib1g-dev

Depois que terminar a instalação de todas as dependências, podemos instalar o PHP em nossa máquina. Para verificar quais versões existem, execute o seguinte comando.

asdf list all php

O comando acima retornará uma lista de todas as versões disponíveis no PHP. O interessante é que ele também retorna as versões que estão em desenvolvimento, permitindo testar recursos em desenvolvimento. Para começar, vamos instalar a versão 8.1.26, então execute o seguinte comando.

asdf install php 8.1.26

A instalação pode demorar um pouco, pois o PHP será compilado na sua máquina. Além disso, é importante observar que o gerenciador de pacotes Composer e o PECL também serão instalados em cada versão.

Agora, precisamos repetir o processo para as outras versões do PHP. Vamos lá:

asdf install php 8.2.13

asdf install php 8.3.0

Quando a instalação da última versão terminar, precisamos configurar qual será a versão padrão instalada em nosso ambiente. Para isso, execute o seguinte comando.

asdf global php 8.3.0

Com esse comando, definimos a versão padrão do PHP em nosso ambiente. Após executar o comando acima, você pode executar o php -v em qualquer lugar do seu sistema operacional, obtendo a seguinte saída.

PHP 8.3.0 (cli) (built: Dec 17 2023 11:09:15) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.3.0, Copyright (c) Zend Technologies

Agora, a cereja do bolo: vamos criar em nosso sistema de arquivo três pastas, imaginando que cada pasta é um projeto que você está trabalhando, e cada projeto precisa executar em uma versão diferente do PHP.

Vamos acessar a raiz do nosso usuário e criar uma pasta Code. Dentro dessa pasta, vamos criar as pastas para cada projeto.

# Acessar o diretório raiz do nosso usuário
cd ~

# Criar a pasta Code
mkdir Code

# Acessar a pasta Code
cd Code

# Criar as pastas de cada projeto
mkdir projeto-1
mkdir projeto-2
mkdir projeto-3

Depois de criar todas as pastas de todos os projetos, vamos acessar cada pasta e configurar nossa versão do PHP desejada.

# Acessar o projeto-1
cd ~/Code/projeto-1

# Configurar a versão 8.1.26 para o projeto-1
asdf local php 8.1.26

# Verificar a versão do PHP
php -v 

# Saída
PHP 8.1.26 (cli) (built: Dec 17 2023 11:09:15) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.3.0, Copyright (c) Zend Technologies

# Acessar o projeto-2
cd ~/Code/projeto-2

# Configurar a versão 8.2.13 para o projeto-2
asdf local php 8.2.13

# Verificar a versão do PHP
php -v 

# Saída
PHP 8.2.13 (cli) (built: Dec 17 2023 11:09:15) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.3.0, Copyright (c) Zend Technologies

Como você pode ver, ao executar o comando php -v, ele retorna uma versão específica para a pasta e, ao executar de outra pasta qualquer, retorna a versão padrão do PHP (8.3.0). Dessa forma, podemos configurar uma versão para cada pasta específica.

Conclusão

ASDF é uma ferramenta fantástica. Sempre que preciso instalar algum componente no meu SO, eu verifico se existe algum plugin ASDF. Lembrando que existem muitos plugins escritos para o ASDF, com certeza há algum para sua linguagem favorita. Adicionei um repositório Git que centraliza uma lista de plugins para o ASDF: https://github.com/asdf-vm/asdf-plugins.

Obrigado, galera!!! Qualquer dúvida ou crítica é muito bem-vinda; fiquem à vontade para adicionar comentários.