paperclip
Version 6.1.0
O clipe de papel está obsoleto .
Para novos projetos, recomendamos o ActiveStorage do próprio Rails.
Para projetos existentes, consulte e contribua com o guia de migração, disponível em inglês, em espanhol, e como um vídeo gravado na RailsConf 2019. Você também pode preferir um tutorial de migração alternativo usado pelo Doorkeeper.
Alternativamente, para projetos existentes, Kreeti está mantendo o kt-paperclip, um fork contínuo do Paperclip.
Deixaremos as questões abertas apenas como um fórum de discussão. Não garantimos uma resposta nossa nas questões. Todos os relatórios de bugs devem ir para o kt-paperclip.
Não aceitamos mais solicitações pull, exceto solicitações pull no guia de migração. Todas as outras solicitações pull serão fechadas sem mesclagem.
masterVerifique a documentação da versão do clipe de papel que você está usando: https://github.com/thoughtbot/paperclip/releases
Requisitos
Ruby e Rails
Processador de imagem
file
Instalação
Início rápido
Modelos
Migrações
Editar e novas visualizações
Editar e novas visualizações com formulário simples
Controlador
Ver ajudantes
Verificando a existência de um arquivo
Excluindo um anexo
Uso
Validações
Internacionalização (I18n)
Validações de segurança
Padrões
Migrações
Adicionar coluna de anexo a uma tabela
Definição de esquema
Sintaxe antiga
Armazenar
Compreendendo o armazenamento
Adaptadores IO
Pós-processamento
Processadores de anexos personalizados
Eventos
Ofuscação de URI
Soma de verificação/impressão digital
Preservação de arquivo para exclusão reversível
Configuração Dinâmica
Estilos Dinâmicos:
Processadores Dinâmicos:
Registro
Implantação
Estilos de anexo
Teste
Contribuindo
Licença
Sobre o thinkbot
Paperclip foi concebido como uma biblioteca fácil de anexar arquivos para ActiveRecord. A intenção por trás disso era manter a configuração o mais fácil possível e tratar os arquivos da forma mais parecida possível com outros atributos. Isso significa que eles não são salvos em seus locais finais no disco, nem são excluídos se definidos como nulos, até que ActiveRecord::Base#save seja chamado. Gerencia validações com base no tamanho e presença, se necessário. Ele pode transformar a imagem atribuída em miniaturas, se necessário, e os pré-requisitos são tão simples quanto instalar o ImageMagick (que, para a maioria dos sistemas modernos baseados em Unix, é tão fácil quanto instalar os pacotes certos). Os arquivos anexados são salvos no sistema de arquivos e referenciados no navegador por uma especificação de fácil compreensão, que possui padrões úteis e sensatos.
Consulte a documentação de has_attached_file em Paperclip::ClassMethods para opções mais detalhadas.
O RDoc completo está online.
Paperclip agora requer versão Ruby >= 2.1 e versão Rails >= 4.2 (somente se você for usar Paperclip com Ruby on Rails).
O ImageMagick deve estar instalado e o Paperclip deve ter acesso a ele. Para garantir que isso aconteça, na linha de comando, execute which convert (um dos utilitários do ImageMagick). Isso lhe dará o caminho onde esse utilitário está instalado. Por exemplo, pode retornar /usr/local/bin/convert .
Em seguida, no arquivo de configuração do seu ambiente, informe o Paperclip para procurar lá, adicionando esse diretório ao seu caminho.
No modo de desenvolvimento, você pode adicionar esta linha a config/environments/development.rb) :
Paperclip.options[:command_path] = "/usr/local/bin/"
Se você estiver no Mac OS X, execute o seguinte com o Homebrew:
brew install imagemagick
Se você estiver lidando com uploads de PDF ou executando o conjunto de testes, também precisará instalar o GhostScript. No Mac OS X, você também pode instalar usando o Homebrew:
brew install gs
Se você estiver no Ubuntu (ou em qualquer distribuição Linux baseada no Debian), você desejará executar o seguinte com o apt-get:
sudo apt-get install imagemagick -y
file O comando file Unix é necessário para verificação do tipo de conteúdo. Este utilitário não está disponível no Windows, mas vem com o Ruby Devkit, portanto, os usuários do Windows devem certificar-se de que o devkit esteja instalado e adicionado ao sistema PATH .
Instalação manual
Se você estiver usando o Windows 7+ como ambiente de desenvolvimento, pode ser necessário instalar o aplicativo file.exe manualmente. O sistema file spoofing no Paperclip 4+ depende disso; se não estiver funcionando, você receberá Validation failed: Upload file has an extension that does not match its contents. erros.
Para instalar manualmente, você deve fazer o seguinte:
Baixe e instale
filedeste URL
Para testar, você pode usar a imagem abaixo:
Em seguida, você precisa integrar com seu ambiente - de preferência através da variável PATH ou alterando seu arquivo config/environments/development.rb
CAMINHO
1. Click "Start" 2. On "Computer", right-click and select "Properties" 3. In Properties, select "Advanced System Settings" 4. Click the "Environment Variables" button 5. Locate the "PATH" var - at the end, add the path to your newly installed `file.exe` (typically `C:Program Files (x86)GnuWin32bin`) 6. Restart any CMD shells you have open & see if it works
OU
Ambiente
1. Open `config/environments/development.rb` 2. Add the following line: `Paperclip.options[:command_path] = 'C:Program Files (x86)GnuWin32bin'` 3. Restart your Rails server
Qualquer um desses métodos dará à configuração do Rails acesso à funcionalidade file.exe , fornecendo assim a capacidade de verificar o conteúdo de um arquivo (corrigindo o problema de falsificação)
O Paperclip é distribuído como uma joia, e é assim que deve ser usado no seu aplicativo.
Inclua a gema em seu Gemfile:
gem "clipe de papel", "~> 6.0.0"
Ou, se quiser obter o mais recente, você pode obter o master no repositório principal de clipes de papel:
gem "clip de papel", git: "git://github.com/thoughtbot/paperclip.git"
Se você estiver tentando usar recursos que não parecem estar na última gem lançada, mas são mencionados neste README, então você provavelmente precisará especificar o branch master se quiser usá-los. Este README provavelmente está à frente da versão lançada mais recente se você estiver lendo no GitHub.
Para uso não-Rails:
class ModuleName < ActiveRecord::Base inclui Paperclip::Glue ...fim
class Usuário < ActiveRecord::Base has_attached_file :avatar, estilos: { médio: "300x300>", polegar: "100x100>" }, default_url: "/images/:style/missing.png" valida_attachment_content_type :avatar, content_type: / Aimagem/.*z/end Supondo que você tenha uma tabela users , adicione uma coluna avatar à tabela users :
class AddAvatarColumnsToUsers < ActiveRecord::Migration def up add_attachment :users, :avatar end def down remove_attachment :users, :avatar endend
(Ou você pode usar o gerador de migração Rails: rails generate paperclip user avatar )
Certifique-se de ter métodos correspondentes em seu controlador:
<%= form_for @user, url: users_path, html: { multipart: true } do |form| %> <%= form.file_field :avatar %> <%= form.submit %><% end %><%= simple_form_for @user, url: users_path do |form| %> <%= form.input :avatar, as: :file %> <%= form.submit %><% end %>
def create @user = User.create(user_params)endprivate# Use strong_parameters para lista de permissões de atributos# Certifique-se de atualizar seus métodos de controlador create() e update().def user_params params.require(:user).permit(:avatar)end
Adicione-os à visualização onde deseja que suas imagens sejam exibidas:
<%= image_tag @user.avatar.url %><%= image_tag @user.avatar.url(:medium) %><%= image_tag @user.avatar.url(:thumb) %>
Existem dois métodos para verificar se existe um arquivo:
file? e present? verifica se o campo _file_name está preenchido
exists? verifica se o arquivo existe (realizará uma conexão TCP se armazenado na nuvem)
Tenha isso em mente se estiver verificando se os arquivos estão presentes em um loop. A primeira versão tem desempenho significativamente melhor, mas possui semântica diferente.
Defina o atributo como nil e salve.
@user.avatar = [email protected]
O básico do Paperclip é bastante simples: declare que seu modelo possui um anexo com o método has_attached_file e dê um nome a ele.
O Paperclip agrupará até quatro atributos (todos prefixados com o nome do anexo, para que você possa ter vários anexos por modelo, se desejar) e fornecerá a eles um front-end amigável. Esses atributos são:
<attachment>_file_name
<attachment>_file_size
<attachment>_content_type
<attachment>_updated_at
Por padrão, apenas <attachment>_file_name é necessário para que o Paperclip funcione. Você precisará adicionar <attachment>_content_type caso queira usar a validação de tipo de conteúdo.
Mais informações sobre as opções passadas para has_attached_file estão disponíveis na documentação do Paperclip::ClassMethods .
Para validações, o Paperclip apresenta vários validadores para validar seu anexo:
AttachmentContentTypeValidator
AttachmentPresenceValidator
AttachmentSizeValidator
Exemplo de uso:
valida: avatar, attachment_presence: truevalidates_with AttachmentPresenceValidator, atributos:: avatarvalidates_with AttachmentSizeValidator, atributos:: avatar, less_than: 1.megabytes
Os validadores também podem ser definidos usando o antigo estilo auxiliar:
validates_attachment_presence
validates_attachment_content_type
validates_attachment_size
Exemplo de uso:
valida_attachment_presence:avatar
Por último, você também pode definir múltiplas validações em um único anexo usando validates_attachment :
valida_attachment:avatar, presença: verdadeiro, content_type: "image/jpeg", tamanho: {in: 0..10.kilobytes}NOTA: O pós-processamento nem será iniciado se o anexo não for válido de acordo com as validações. Seus retornos de chamada e processadores só serão chamados com anexos válidos.
class Mensagem <ActiveRecord::Base has_attached_file:asset, estilos: {thumb: "100x100#"} before_post_process:skip_for_audio def skip_for_audio
! %w(audio/ogg application/ogg).include?(asset_content_type) endendSe você tiver outras validações que dependam da ordem de atribuição, a ação recomendada é impedir a atribuição do anexo até mais tarde e, em seguida, atribuir manualmente:
class Book < ActiveRecord::Base has_attached_file :document, estilos: { miniatura: "60x60#" } valida_attachment :document, content_type: "application/pdf" valida_something_else # Outras validações que entram em conflito com Paperclip'sendclass BooksController < ApplicationController def create @book = Book.new(book_params) @book.document = params[:book][:document] @book.save respond_with @book end private def book_params params.require(:book).permit(:title, :author) endendUma observação sobre validações e segurança de content_type
Você deve garantir que os arquivos sejam validados apenas para os tipos MIME que você deseja suportar explicitamente. Caso contrário, você poderá estar sujeito a ataques XSS se um usuário fizer upload de um arquivo com uma carga HTML maliciosa.
Se você estiver interessado apenas em imagens, restrinja seus content_types permitidos aos de imagem:
valida_attachment :avatar, content_type: ["imagem/jpeg", "imagem/gif", "imagem/png"]
Paperclip::ContentTypeDetector tentará corresponder a extensão de um arquivo a um content_type inferido, independentemente do conteúdo real do arquivo.
Para usar ou adicionar arquivos de localidade em diferentes idiomas, verifique o projeto https://github.com/thoughtbot/paperclip-i18n.
Graças a um relatório de Egor Homakov, tomamos medidas para evitar que as pessoas falsifiquem Content-Types e obtenham dados que você não esperava em seu servidor.
NOTA: A partir da versão 4.0.0, todos os anexos são obrigados a incluir uma validação content_type, uma validação file_name ou declarar explicitamente que eles não terão nenhum deles. O Paperclip gerará um erro se você não fizer isso.
class ActiveRecord::Base has_attached_file :avatar # Valida o tipo de conteúdo valids_attachment_content_type :avatar, content_type: /Aimage/ # Valida o nome do arquivo valids_attachment_file_name :avatar, matches: [/pngz/, /jpe?gz/] # Explicitamente não faça validar do_not_validate_attachment_file_type:avatarend
Isso mantém o Paperclip seguro por padrão e evita que pessoas tentem mexer no seu sistema de arquivos.
NOTA: Também a partir da versão 4.0.0, o Paperclip possui outra validação que não pode ser desativada. Esta validação impedirá a falsificação do tipo de conteúdo. Ou seja, fazer upload de um documento PHP (por exemplo) como parte das tags EXIF de um JPEG bem formado. Esta verificação é limitada ao tipo de mídia (a primeira parte do tipo MIME, portanto, 'texto' em text/plain ). Isso impedirá que documentos HTML sejam carregados como JPEGs, mas não impedirá que GIFs sejam carregados com uma extensão .jpg . Esta validação apenas adicionará erros de validação ao formulário. Isso não fará com que erros sejam gerados.
Às vezes, isso pode causar erros de validação falsos em aplicativos que usam extensões de arquivo personalizadas. Nesses casos, você pode querer adicionar sua extensão personalizada à lista de mapeamentos de tipo de conteúdo criando config/initializers/paperclip.rb :
# Permitir ".foo" como extensão para arquivos com o tipo MIME "text/plain".Paperclip.options[:content_type_mappings] = { foo: %w(text/plain)} Os padrões globais para todos os seus anexos do Paperclip podem ser definidos alterando o Hash Paperclip::Attachment.default_options. Isso pode ser útil para definir suas configurações de armazenamento padrão por exemplo, para que você não precise defini-las em cada definição de has_attached_file .
Se você estiver usando Rails, você pode definir um Hash com opções padrão em config/application.rb ou em qualquer um dos arquivos config/environments/*.rb em config.paperclip_defaults. Eles serão mesclados em Paperclip::Attachment.default_options conforme seu aplicativo Rails for inicializado. Um exemplo:
módulo Classe YourApp Application < Rails::Application # Outro código... config.paperclip_defaults = { storage: :fog, fog_credentials: { provedor: "Local", local_root: "#{Rails.root}/public"}, fog_directory: "", fog_host: "localhost"} endend Outra opção é modificar diretamente o Hash Paperclip::Attachment.default_options - este método funciona para aplicativos não-Rails ou é uma opção se você preferir colocar as configurações padrão do Paperclip em um inicializador.
Um exemplo de inicializador Rails seria mais ou menos assim:
Clipe de papel::Attachment.default_options[:storage] = :fogPaperclip::Attachment.default_options[:fog_credentials] = {provedor: "Local", local_root: "#{Rails.root}/public"}Paperclip::Attachment.default_options[ :fog_directory] = ""Paperclip::Attachment.default_options[:fog_host] = "http://localhost:3000"Paperclip define vários métodos de migração que podem ser usados para criar as colunas necessárias em seu modelo. Existem dois tipos de métodos auxiliares para ajudar nisso, como segue:
O auxiliar attachment pode ser usado ao criar uma tabela:
class CreateUsersWithAttachments < ActiveRecord::Migration def up create_table :users do |t| t.attachment :avatar end end # Isso pressupõe que você esteja usando apenas a tabela de usuários para anexo de clipe de papel. Solte com cuidado! def down drop_table: usuários endend
Você também pode usar o método change , em vez da combinação up / down acima, conforme mostrado abaixo:
class CreateUsersWithAttachments < ActiveRecord::Migration def change create_table :users do |t| t.attachment:avatar fim fim
Alternativamente, os métodos add_attachment e remove_attachment podem ser usados para adicionar novas colunas Paperclip a uma tabela existente:
class AddAttachmentColumnsToUsers < ActiveRecord::Migration def up add_attachment :users, :avatar end def down remove_attachment :users, :avatar endend
Ou você pode fazer isso com o método change :
class AddAttachmentColumnsToUsers < ActiveRecord::Migration def change add_attachment :users, :avatar endend
A sintaxe vintage (como t.has_attached_file e drop_attached_file ) ainda é suportada no Paperclip 3.x, mas é aconselhável atualizar esses arquivos de migração para usar esta nova sintaxe.
O clipe de papel vem com 3 adaptadores de armazenamento:
Armazenamento de arquivos
Armazenamento S3 (via aws-sdk-s3 )
Armazenamento de nevoeiro
Se quiser usar o Paperclip com outro armazenamento, você pode instalar estas joias junto com o Paperclip:
clipe de papel-azul
armazenamento de clipe de papel azul
caixa de depósito de clipes de papel
Os arquivos atribuídos como anexos são, por padrão, colocados no diretório especificado pela opção :path para has_attached_file . Por padrão, esse local é :rails_root/public/system/:class/:attachment/:id_partition/:style/:filename . Esse local foi escolhido porque, em implantações padrão do Capistrano, o diretório public/system pode ter um link simbólico ao diretório compartilhado do aplicativo, o que significa que ele sobrevive entre as implantações. Por exemplo, usando esse :path , você pode ter um arquivo em
/data/myapp/releases/20081229172410/public/system/users/avatar/000/000/013/small/my_pic.png
NOTA : Esta é uma alteração em relação às versões anteriores do Paperclip, mas no geral é uma escolha mais segura para o armazenamento de arquivos padrão.
Você também pode optar por armazenar seus arquivos usando o serviço S3 da Amazon. Para fazer isso, inclua a gem aws-sdk-s3 em seu Gemfile:
gema 'aws-sdk-s3'
E então você pode especificar usando S3 de has_attached_file . Você pode encontrar mais informações sobre como configurar e usar o armazenamento S3 na documentação Paperclip::Storage::S3 .
Os arquivos no sistema de arquivos local (e no diretório público do aplicativo Rails) estarão disponíveis na Internet em geral. Caso necessite de controle de acesso, é possível colocar seus arquivos em um local diferente. Você precisará alterar as opções :path e :url para garantir que os arquivos não estejam disponíveis ao público. Tanto :path quanto :url permitem o mesmo conjunto de variáveis interpoladas.
Quando um arquivo é carregado ou anexado, ele pode estar em uma de algumas formas de entrada diferentes, desde o objeto UploadedFile do Rails até um StringIO, um Tempfile ou até mesmo uma simples String que é uma URL que aponta para uma imagem.
O Paperclip aceitará, por padrão, muitas dessas fontes. Também é capaz de lidar ainda mais com um pouco de configuração. Os adaptadores IO que lidam com imagens de fontes não locais não estão habilitados por padrão. Eles podem ser habilitados adicionando uma linha semelhante à seguinte em config/initializers/paperclip.rb :
Clipe de papel::DataUriAdapter.register
É melhor ativar um adaptador de carregamento remoto apenas se necessário. Caso contrário, há uma chance de alguém obter informações sobre a estrutura interna da sua rede usando-a como um vetor.
Os seguintes adaptadores não são carregados por padrão:
Paperclip::UriAdapter - que aceita uma instância URI .
Paperclip::HttpUrlProxyAdapter - que aceita uma string http .
Paperclip::DataUriAdapter - que aceita uma string data: codificada em Base64.
Paperclip suporta uma seleção extensível de pós-processadores. Quando você define um conjunto de estilos para um anexo, por padrão espera-se que esses "estilos" sejam na verdade "miniaturas". Eles são processados por Paperclip::Thumbnail . Por motivos de compatibilidade com versões anteriores, você pode passar uma única string de geometria ou um array contendo uma geometria e um formato para o qual o arquivo será convertido, assim:
has_attached_file :avatar, estilos: { polegar: ["32x32#", :png] } Isso converterá o estilo “polegar” em um quadrado de 32x32 no formato PNG, independentemente do que foi carregado. Se o formato não for especificado, ele será mantido o mesmo (por exemplo, JPGs permanecerão JPGs). Paperclip::Thumbnail usa ImageMagick para processar imagens; A documentação de geometria do ImageMagick contém mais informações sobre os formatos de estilo aceitos.
Para um controle mais refinado do processo de conversão, source_file_options e convert_options podem ser usados para passar sinalizadores e configurações diretamente para a poderosa ferramenta Convert do ImageMagick, documentada aqui. Por exemplo:
has_attached_file: imagem, estilos: { regular: ['800x800>',: png]},
source_file_options: { regular: "-densidade 96 -profundidade 8 -qualidade 85" }, convert_options: { regular: "-posterize 3"}ImageMagick suporta uma série de variáveis de ambiente para controlar seus limites de recursos. Por exemplo, você pode impor limites de memória ou de tempo de execução definindo as seguintes variáveis no ambiente de processo do seu aplicativo:
MAGICK_MEMORY_LIMIT=128MiB
MAGICK_MAP_LIMIT=64MiB
MAGICK_TIME_LIMIT=30
Para obter uma lista completa de variáveis e descrição, consulte a documentação de recursos do ImageMagick.
Você pode escrever seus próprios processadores de anexos personalizados para realizar tarefas como adicionar marcas d'água, compactar imagens ou criptografar arquivos. Processadores personalizados devem ser definidos dentro do módulo Paperclip , herdar de Paperclip::Processor (consulte lib/paperclip/processor.rb ) e implementar um método make que retorne um File . Todos os arquivos nos diretórios lib/paperclip e lib/paperclip_processors do seu aplicativo Rails serão carregados automaticamente pelo Paperclip. Os processadores são especificados usando a opção :processors para has_attached_file :
has_attached_file:scan, estilos: {texto: {qualidade::melhor}}, processadores: [:ocr] Isso carregaria a classe hipotética Paperclip::Ocr e passaria para ela o hash de opções { quality: :better } , junto com o arquivo enviado.
Vários processadores podem ser especificados e serão invocados na ordem em que são definidos no array :processors . Cada processador sucessivo recebe o resultado do processador anterior. Todos os processadores recebem os mesmos parâmetros, que são definidos no hash :styles . Por exemplo, supondo que tivéssemos esta definição:
has_attached_file:scan, estilos: {texto: {qualidade::melhor}}, processadores: [:rotator,:ocr] Tanto o processador :rotator quanto o processador :ocr receberiam as opções { quality: :better } . Se um processador receber uma opção que não reconhece, espera-se que ele a ignore.
NOTA: Como os processadores operam transformando o anexo original em estilos, nenhum processador será executado se não houver estilos definidos.
Se você estiver interessado em armazenar em cache a largura, altura e tamanho da sua miniatura no banco de dados, dê uma olhada na meta gem do clipe de papel.
Além disso, se você estiver interessado em gerar a miniatura dinamicamente, você pode querer dar uma olhada na gem attachment_on_the_fly.
O gerador de miniaturas do Paperclip (veja lib/paperclip/thumbnail.rb ) é implementado como um processador e pode ser uma boa referência para escrever seus próprios processadores.
Antes e depois da etapa de Pós-processamento, o Paperclip retorna ao modelo com alguns retornos de chamada, permitindo que o modelo altere ou cancele a etapa de processamento. Os retornos de chamada são before_post_process e after_post_process (que são chamados antes e depois do processamento de cada anexo) e os específicos do anexo before_<attachment>_post_process e after_<attachment>_post_process . Os retornos de chamada devem ser o mais próximo possível dos retornos de chamada normais do ActiveRecord, portanto, se você retornar false (especificamente - retornar nil não é o mesmo) em um before_filter , a etapa de pós-processamento será interrompida. Retornar false em um after_filter não interromperá nada, mas você poderá acessar o modelo e o anexo, se necessário.
NOTA: O pós-processamento nem será iniciado se o anexo não for válido de acordo com as validações. Seus retornos de chamada e processadores só serão chamados com anexos válidos.
class Mensagem <ActiveRecord::Base has_attached_file:asset, estilos: {thumb: "100x100#"} before_post_process:skip_for_audio def skip_for_audio
! %w(audio/ogg application/ogg).include?(asset_content_type) endend Paperclip tem uma interpolação chamada :hash para ofuscar nomes de arquivos disponíveis publicamente.
Exemplo de uso:
has_attached_file:avatar, {url: "/system/:hash.:extension", hash_secret: "longSecretString"} A interpolação :hash será substituída por um hash exclusivo composto de tudo o que estiver especificado em :hash_data . O valor padrão para :hash_data é ":class/:attachment/:id/:style/:updated_at" .
:hash_secret é obrigatório - uma exceção será gerada se :hash for usado sem :hash_secret presente.
Para saber mais sobre esse recurso, leia a explicação do próprio autor
Uma soma de verificação do arquivo original atribuído será colocada no modelo se ele possuir um atributo denominado impressão digital. Seguindo o exemplo de migração de modelo de usuário acima, a migração seria semelhante a esta:
class AddAvatarFingerprintColumnToUser < ActiveRecord::Migration def up add_column :users, :avatar_fingerprint, :string end def down remove_column :users, :avatar_fingerprint endend
O algoritmo pode ser especificado usando uma opção de configuração; o padrão é MD5 para compatibilidade com versões anteriores do Paperclip 5 e versões anteriores.
has_attached_file: algum_attachment, adaptador_options: { hash_digest: Digest::SHA256} Execute CLASS=User ATTACHMENT=avatar rake paperclip:refresh:fingerprints depois de alterar o resumo nos anexos existentes para atualizar as impressões digitais no banco de dados.
Está disponível uma opção para preservar anexos para funcionar bem com modelos excluídos de forma reversível. (acts_as_paranoid, paranóia, etc.)
has_attached_file: algum_attachment, { preserve_files: true,} Isso impedirá que some_attachment seja eliminado quando o modelo for destruído, portanto, ele ainda existirá quando o objeto for restaurado posteriormente.
Objetos que podem ser chamados (lambdas, Procs) podem ser usados em vários locais para configuração dinâmica em todo o Paperclip. Essa estratégia existe em vários componentes da biblioteca, mas é mais significativa nas possibilidades de permitir que estilos e processadores personalizados sejam aplicados a instâncias de modelo específicas, em vez de aplicar estilos e processadores definidos em todas as instâncias.
Imagine um modelo de usuário que tivesse estilos diferentes com base na função do usuário. Talvez alguns usuários sejam chefes (por exemplo, uma instância do modelo User responde a #boss? ) e mereçam uma miniatura de avatar maior do que os usuários normais. A configuração para determinar quais parâmetros de estilo devem ser usados com base na função do usuário pode ser a seguinte, onde um chefe receberá uma miniatura 300x300 caso contrário, uma miniatura 100x100 será criada.
class Usuário < ActiveRecord::Base has_attached_file :avatar, estilos: lambda { |attachment| { polegar: (attachment.instance.boss? ? "300x300>" : "100x100>") } }fim Outro exemplo inventado é um modelo de usuário que sabe quais processadores de arquivos devem ser aplicados a ele (além do processador thumbnail implícito invocado quando :styles são definidos). Talvez tenhamos disponível um processador de marca d'água e ele só seja usado nos avatares de alguns modelos. A configuração para isso pode ser onde a instância é consultada para saber quais processadores devem ser aplicados a ela. Presumivelmente, alguns usuários podem retornar [:thumbnail, :watermark] para seus processadores, onde um processador watermark definido é invocado após o processador thumbnail já definido pelo Paperclip.
class Usuário < ActiveRecord::Base has_attached_file :avatar, processadores: lambda { |instance| instância.processadores} attr_accessor:processadoresendPor padrão, o Paperclip gera o registro de acordo com o nível do seu registrador. Se você deseja desabilitar o log (por exemplo, durante o teste), adicione isto na configuração do seu ambiente:
Seu::Application.configure faça... Paperclip.options[:log] = false...end
Mais informações nos rdocs
Para fazer com que Capistrano crie um link simbólico para o diretório public/system para que os anexos sobrevivam a novas implantações, defina a opção linked_dirs em seu arquivo config/deploy.rb :
definir :linked_dirs, fetch(:linked_dirs, []).push('public/system') O Paperclip está ciente dos novos estilos de anexo que você adicionou em implantações anteriores. A única coisa que você deve fazer após cada implantação é chamar rake paperclip:refresh:missing_styles . Ele armazenará os estilos de anexo atuais em RAILS_ROOT/public/system/paperclip_attachments.yml por padrão. Você pode alterá-lo:
Paperclip.registered_attachments_styles_path = '/tmp/config/paperclip_attachments.yml'
Aqui está um exemplo para Capistrano:
namespace :paperclip do desc "construir estilos de clipe de papel ausentes" tarefa :build_missing_styles fazer em funções(:app) fazer dentro de release_path fazer com rails_env: fetch(:rails_env) fazer executar :rake, "paperclip:refresh:missing_styles" end end end endendafter( "implantar:compile_assets", "clip de papel:build_missing_styles")
Agora você não precisa se lembrar de atualizar as miniaturas na produção sempre que adicionar um novo estilo. Infelizmente, isso não funciona com estilos dinâmicos - apenas os ignora.
Se você já possui um aplicativo funcional e não deseja que rake paperclip:refresh:missing_styles atualize imagens antigas, você precisa informar ao Paperclip sobre os estilos existentes. Basta criar um arquivo paperclip_attachments.yml manualmente. Por exemplo:
class Usuário < ActiveRecord::Base has_attached_file :avatar, estilos: { polegar: 'x100', croppable: '600x600>', big: '1000x1000>' }endclass Livro < ActiveRecord::Base has_attached_file :cover, estilos: { small: 'x100', grande: '1000x1000>' } has_attached_file: amostra, estilos: { polegar: 'x100'} fim Então em RAILS_ROOT/public/system/paperclip_attachments.yml :
---:Usuário: :avatar: - :dedão -: recortável - :grande:Livro: :capa: - :pequeno - :grande :amostra: - :dedão
Paperclip fornece matchers compatíveis com rspec para testar anexos. Consulte a documentação em Paperclip::Sholda::Matchers para obter mais informações.
Testes Paralelos
Devido ao path padrão para armazenamento do Paperclip, se você tentar executar testes em paralelo, poderá descobrir que os arquivos serão substituídos porque o mesmo caminho está sendo calculado para eles em cada processo de teste. Embora essa correção funcione para parallel_tests, um conceito semelhante deve ser usado para qualquer outro mecanismo para execução de testes simultaneamente.
if ENV['PARALLEL_TEST_GROUPS'] Paperclip::Attachment.default_options[:path] = ":rails_root/public/system/:rails_env/#{ENV['TEST_ENV_NUMBER'].to_i}/:class/:attachment/:id_partition/ :nome do arquivo"else Paperclip::Attachment.default_options[:path] = ":rails_root/public/system/:rails_env/:class/:attachment/:id_partition/:filename"fim A parte importante aqui é a inclusão de ENV['TEST_ENV_NUMBER'] , ou um mecanismo semelhante para qualquer biblioteca de testes paralelos que você usar.
Testes de Integração
O uso de testes de integração com o FactoryBot pode salvar várias cópias dos seus arquivos de teste no aplicativo. Para evitar isso, especifique um caminho personalizado em config/environments/test.rb assim:
Paperclip::Attachment.default_options[:path] = "#{Rails.root}/spec/test_files/:class/:id_partition/:style.:extension" Em seguida, certifique-se de excluir esse diretório após a execução do conjunto de testes, adicionando-o a spec_helper.rb .
config.after(:suite) do FileUtils.rm_rf(Dir["#{Rails.root}/spec/test_files/"])endExemplo de configuração de teste com Factory Bot
FactoryBot.define do factory :user do avatar { File.new("#{Rails.root}/spec/support/fixtures/image.jpg") } endendSe você gostaria de contribuir com um recurso ou correção de bug: Obrigado! Para garantir que sua correção/recurso tenha grandes chances de ser incluída, leia as seguintes diretrizes:
Poste uma solicitação pull.
Certifique-se de que haja testes! Não aceitaremos nenhum patch que não tenha sido testado. É raro que testes explícitos não sejam necessários. Se você tiver dúvidas sobre como escrever testes para clipe de papel, abra um problema no GitHub.
Consulte CONTRIBUTING.md para obter mais detalhes sobre como contribuir e executar testes.
Obrigado a todos os colaboradores!
O clipe de papel é protegido por direitos autorais © 2008-2017 thinkingbot, inc. É software livre e pode ser redistribuído sob os termos especificados no arquivo MIT-LICENSE.
Paperclip é mantido e financiado pela Thoughtbot. Os nomes e logotipos do Thoughtbot são marcas registradas da Thoughtbot, Inc.
Amamos software de código aberto! Veja nossos outros projetos ou contrate-nos para projetar, desenvolver e expandir seu produto.
