paperclip
Version 6.1.0
Le trombone est obsolète .
Pour les nouveaux projets, nous recommandons le propre ActiveStorage de Rails.
Pour les projets existants, veuillez consulter et contribuer au guide de migration, disponible en anglais, en espagnol et sous forme de vidéo enregistrée à RailsConf 2019. Vous pouvez également préférer un didacticiel de migration alternatif utilisé par Doorkeeper.
Alternativement, pour les projets existants, Kreeti maintient kt-paperclip, un fork en cours de Paperclip.
Nous laisserons les problèmes ouverts uniquement sous forme de forum de discussion. Nous ne garantissons pas une réponse de notre part dans les problèmes. Tous les rapports de bogues doivent être envoyés à kt-paperclip.
Nous n'acceptons plus les pull request, à l'exception des pull request contre le guide de migration. Toutes les autres demandes de tirage seront fermées sans fusion.
masterVeuillez consulter la documentation de la version du trombone que vous utilisez : https://github.com/thoughtbot/paperclip/releases
Exigences
Rubis et Rails
Processeur d'images
file
Installation
Démarrage rapide
Modèles
Migrations
Modifier et nouvelles vues
Modifier et créer de nouvelles vues avec un formulaire simple
Contrôleur
Afficher les assistants
Vérifier qu'un fichier existe
Supprimer une pièce jointe
Usage
Validations
Internationalisation (I18n)
Validations de sécurité
Valeurs par défaut
Migrations
Ajouter une colonne de pièce jointe à un tableau
Définition du schéma
Syntaxe vintage
Stockage
Comprendre le stockage
Adaptateurs E/S
Post-traitement
Processeurs de pièces jointes personnalisés
Événements
Obscurcissement de l'URI
Somme de contrôle/empreinte digitale
Conservation des fichiers pour la suppression logicielle
Configuration dynamique
Styles dynamiques :
Processeurs dynamiques :
Enregistrement
Déploiement
Styles de pièces jointes
Essai
Contribuer
Licence
À propos de Thinkbot
Paperclip est conçu comme une bibliothèque de pièces jointes simple pour ActiveRecord. L'intention derrière cela était de garder la configuration aussi simple que possible et de traiter les fichiers autant que possible comme d'autres attributs. Cela signifie qu'ils ne sont pas enregistrés dans leurs emplacements finaux sur le disque, et qu'ils ne sont pas non plus supprimés s'ils sont définis sur zéro, jusqu'à ce qu'ActiveRecord::Base#save soit appelé. Il gère les validations basées sur la taille et la présence, si nécessaire. Il peut transformer l'image qui lui est attribuée en vignettes si nécessaire, et les conditions préalables sont aussi simples que d'installer ImageMagick (ce qui, pour la plupart des systèmes Unix modernes, est aussi simple que d'installer les bons packages). Les fichiers joints sont enregistrés dans le système de fichiers et référencés dans le navigateur par une spécification facilement compréhensible, qui a des valeurs par défaut raisonnables et utiles.
Consultez la documentation de has_attached_file dans Paperclip::ClassMethods pour des options plus détaillées.
Le RDoc complet est en ligne.
Paperclip nécessite désormais la version Ruby >= 2.1 et la version Rails >= 4.2 (uniquement si vous comptez utiliser Paperclip avec Ruby on Rails).
ImageMagick doit être installé et Paperclip doit y avoir accès. Pour vous assurer que c'est le cas, sur votre ligne de commande, exécutez which convert (l'un des utilitaires ImageMagick). Cela vous donnera le chemin où cet utilitaire est installé. Par exemple, il pourrait renvoyer /usr/local/bin/convert .
Ensuite, dans le fichier de configuration de votre environnement, faites savoir à Paperclip d'y chercher en ajoutant ce répertoire à son chemin.
En mode développement, vous pouvez ajouter cette ligne à config/environments/development.rb) :
Paperclip.options[:command_path] = "/usr/local/bin/"
Si vous utilisez Mac OS X, vous souhaiterez exécuter ce qui suit avec Homebrew :
brew install imagemagick
Si vous effectuez des téléchargements de PDF ou exécutez la suite de tests, vous devrez également installer GhostScript. Sur Mac OS X, vous pouvez également l'installer en utilisant Homebrew :
brew install gs
Si vous utilisez Ubuntu (ou toute distribution Linux basée sur Debian), vous souhaiterez exécuter ce qui suit avec apt-get :
sudo apt-get install imagemagick -y
file La commande file Unix est requise pour la vérification du type de contenu. Cet utilitaire n'est pas disponible sous Windows, mais est fourni avec Ruby Devkit, les utilisateurs de Windows doivent donc s'assurer que le devkit est installé et ajouté au système PATH .
Installation manuelle
Si vous utilisez Windows 7+ comme environnement de développement, vous devrez peut-être installer l'application file.exe manuellement. Le système file spoofing de Paperclip 4+ repose sur cela ; si cela ne fonctionne pas, vous recevrez Validation failed: Upload file has an extension that does not match its contents. erreurs.
Pour installer manuellement, vous devez effectuer les opérations suivantes :
Téléchargez et installez
fileà partir de cette URL
Pour tester, vous pouvez utiliser l'image ci-dessous :
Ensuite, vous devez intégrer votre environnement - de préférence via la variable PATH , ou en modifiant votre fichier config/environments/development.rb
CHEMIN
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
Environnement
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
L'une ou l'autre de ces méthodes donnera à votre configuration Rails l'accès à la fonctionnalité file.exe , offrant ainsi la possibilité de vérifier le contenu d'un fichier (résolvant le problème d'usurpation d'identité)
Paperclip est distribué comme un joyau, c'est ainsi qu'il doit être utilisé dans votre application.
Incluez la gemme dans votre Gemfile :
gemme "trombone", "~> 6.0.0"
Ou, si vous souhaitez obtenir la dernière version, vous pouvez obtenir le master à partir du référentiel principal de trombones :
gem "paperclip", git: "git://github.com/thoughtbot/paperclip.git"
Si vous essayez d'utiliser des fonctionnalités qui ne semblent pas figurer dans la dernière gemme publiée, mais qui sont mentionnées dans ce README, vous devrez probablement spécifier la branche principale si vous souhaitez les utiliser. Ce README est probablement en avance sur la dernière version publiée si vous le lisez sur GitHub.
Pour une utilisation non-Rails :
class ModuleName < ActiveRecord :: Base include Paperclip :: Glue ...fin
Utilisateur de classe < ActiveRecord::Base has_attached_file :avatar, styles : { medium : "300x300>", thumb : "100x100>" }, default_url : "/images/:style/missing.png" validates_attachment_content_type :avatar, content_type : / Aimage/.*z/fin En supposant que vous disposez d'une table users , ajoutez une colonne avatar à la table users :
class AddAvatarColumnsToUsers < ActiveRecord::Migration def up add_attachment :users, :avatar end def down remove_attachment :users, :avatar endend
(Ou vous pouvez utiliser le générateur de migration Rails : rails generate paperclip user avatar )
Assurez-vous que vous disposez des méthodes correspondantes dans votre contrôleur :
<%= form_for @user, url : user_path, html : { multipart : true } do |form| %> <%= form.file_field :avatar %> <%= form.submit %><% end %><%= simple_form_for @user, url : user_path do |form| %> <%= form.input :avatar, as: :file %> <%= form.submit %><% end %>
def create @user = User.create(user_params)endprivate# Utilisez strong_parameters pour la liste blanche des attributs# Assurez-vous de mettre à jour vos méthodes de contrôleur create() et update().def user_params params.require(:user).permit(:avatar)end
Ajoutez-les à la vue dans laquelle vous souhaitez afficher vos images :
<%= image_tag @user.avatar.url %><%= image_tag @user.avatar.url(:medium) %><%= image_tag @user.avatar.url(:thumb) %>
Il existe deux méthodes pour vérifier si un fichier existe :
file? et present? vérifie si le champ _file_name est renseigné
exists? vérifie si le fichier existe (effectuera une connexion TCP s'il est stocké dans le cloud)
Gardez cela à l'esprit si vous vérifiez si les fichiers sont présents dans une boucle. La première version est nettement plus performante, mais a une sémantique différente.
Définissez l’attribut sur nil et enregistrez.
@user.avatar = [email protected]
Les bases de Paperclip sont assez simples : Déclarez que votre modèle possède une pièce jointe avec la méthode has_attached_file , et donnez-lui un nom.
Paperclip encapsulera jusqu'à quatre attributs (tous préfixés par le nom de cette pièce jointe, vous pouvez donc avoir plusieurs pièces jointes par modèle si vous le souhaitez) et leur donnera une interface conviviale. Ces attributs sont :
Par défaut, seul
Plus d'informations sur les options transmises à has_attached_file sont disponibles dans la documentation de Paperclip::ClassMethods .
Pour les validations, Paperclip introduit plusieurs validateurs pour valider votre pièce jointe :
AttachmentContentTypeValidator
AttachmentPresenceValidator
AttachmentSizeValidator
Exemple d'utilisation :
valide :avatar, attachment_presence : truevalidates_with AttachmentPresenceValidator, attributs : avatarvalidates_with AttachmentSizeValidator, attributs : avatar, less_than : 1.megabytes
Les validateurs peuvent également être définis en utilisant l'ancien style d'assistance :
validates_attachment_presence
validates_attachment_content_type
validates_attachment_size
Exemple d'utilisation :
validates_attachment_presence :avatar
Enfin, vous pouvez également définir plusieurs validations sur une seule pièce jointe en utilisant validates_attachment :
validates_attachment :avatar, présence : true, content_type : "image/jpeg", taille : { po : 0..10.kilobytes }REMARQUE : Le post-traitement ne démarrera même pas si la pièce jointe n'est pas valide selon les validations. Vos rappels et processeurs ne seront appelés qu’avec des pièces jointes valides.
class Message < ActiveRecord::Base has_attached_file :asset, styles: { thumb: "100x100#" } before_post_process :skip_for_audio def skip_for_audio
! %w(audio/ogg application/ogg).include?(asset_content_type) finSi vous disposez d'autres validations qui dépendent de l'ordre d'affectation, la marche à suivre recommandée consiste à empêcher l'affectation de la pièce jointe jusqu'à après, puis à l'attribuer manuellement :
class Book < ActiveRecord::Base has_attached_file :document, styles: { thumbnail: "60x60#" } validates_attachment :document, content_type: "application/pdf" validates_something_else # Autres validations en conflit avec Paperclip'sendclass BooksController < ApplicationController def create @book = Livre.new(book_params) @book.document = params[:book][:document] @book.save répond_with @book end private def book_params params.require(:book).permit(:title, :author) endendUne note sur les validations et la sécurité content_type
Vous devez vous assurer que vous validez les fichiers comme étant uniquement les types MIME que vous souhaitez explicitement prendre en charge. Si vous ne le faites pas, vous pourriez être exposé aux attaques XSS si un utilisateur télécharge un fichier avec une charge utile HTML malveillante.
Si vous n'êtes intéressé que par les images, limitez vos content_types autorisés à ceux image-y :
validates_attachment :avatar, content_type : ["image/jpeg", "image/gif", "image/png"]
Paperclip::ContentTypeDetector tentera de faire correspondre l'extension d'un fichier à un content_type déduit, quel que soit le contenu réel du fichier.
Pour utiliser ou ajouter des fichiers de paramètres régionaux dans différentes langues, consultez le projet https://github.com/thoughtbot/paperclip-i18n.
Grâce à un rapport d'Egor Homakov, nous avons pris des mesures pour empêcher les gens d'usurper les types de contenu et d'obtenir des données inattendues sur votre serveur.
REMARQUE : à partir de la version 4.0.0, toutes les pièces jointes doivent inclure une validation content_type, une validation file_name, ou indiquer explicitement qu'elles n'en auront pas non plus. Paperclip générera une erreur si vous ne le faites pas.
class ActiveRecord::Base has_attached_file :avatar # Valider le type de contenu validates_attachment_content_type :avatar, content_type: /Aimage/ # Valider le nom de fichier validates_attachment_file_name :avatar, matches: [/pngz/, /jpe?gz/] # Ne pas le faire explicitement valider do_not_validate_attachment_file_type :avatarend
Cela maintient Paperclip sécurisé par défaut et empêchera les gens d'essayer de jouer avec votre système de fichiers.
REMARQUE : à partir de la version 4.0.0 également, Paperclip dispose d'une autre validation qui ne peut pas être désactivée. Cette validation empêchera l’usurpation du type de contenu. C'est-à-dire télécharger un document PHP (par exemple) dans le cadre des balises EXIF d'un JPEG bien formé. Cette vérification est limitée au type de média (la première partie du type MIME, donc 'text' dans text/plain ). Cela empêchera le téléchargement de documents HTML au format JPEG, mais n'empêchera pas le téléchargement de fichiers GIF avec une extension .jpg . Cette validation ajoutera uniquement des erreurs de validation au formulaire. Cela n’entraînera pas de génération d’erreurs.
Cela peut parfois provoquer de fausses erreurs de validation dans les applications qui utilisent des extensions de fichiers personnalisées. Dans ces cas, vous souhaiterez peut-être ajouter votre extension personnalisée à la liste des mappages de types de contenu en créant config/initializers/paperclip.rb :
# Autoriser ".foo" comme extension pour les fichiers de type MIME "text/plain".Paperclip.options[:content_type_mappings] = { foo: %w(text/plain)} Les valeurs par défaut globales pour toutes vos pièces jointes Paperclip peuvent être définies en modifiant le hachage Paperclip::Attachment.default_options. Cela peut être utile pour définir vos paramètres de stockage par défaut par exemple afin que vous n'ayez pas à les définir dans chaque définition has_attached_file .
Si vous utilisez Rails, vous pouvez définir un hachage avec les options par défaut dans config/application.rb ou dans l'un des fichiers config/environments/*.rb sur config.paperclip_defaults. Ceux-ci seront fusionnés dans Paperclip::Attachment.default_options au démarrage de votre application Rails. Un exemple :
module YourApp class Application < Rails::Application # Autre code... config.paperclip_defaults = { stockage : :fog, fog_credentials : { fournisseur : "Local", local_root : "#{Rails.root}/public"}, fog_directory : "", fog_host : "localhost"} fin Une autre option consiste à modifier directement le hachage Paperclip::Attachment.default_options - cette méthode fonctionne pour les applications non-Rails ou est une option si vous préférez placer les paramètres par défaut de Paperclip dans un initialiseur.
Un exemple d'initialiseur Rails ressemblerait à ceci :
Paperclip::Attachment.default_options[:storage] = :fogPaperclip::Attachment.default_options[:fog_credentials] = { fournisseur : "Local", local_root: "#{Rails.root}/public"}Paperclip::Attachment.default_options[ :fog_directory] = ""Paperclip::Attachment.default_options[:fog_host] = "http://localhost:3000"Paperclip définit plusieurs méthodes de migration qui peuvent être utilisées pour créer les colonnes nécessaires dans votre modèle. Il existe deux types de méthodes d'assistance pour vous aider, comme suit :
L'assistant attachment peut être utilisé lors de la création d'un tableau :
class CreateUsersWithAttachments < ActiveRecord::Migration def up create_table :les utilisateurs font |t| t.attachment :avatar end end # Cela suppose que vous utilisez uniquement la table des utilisateurs pour la pièce jointe Paperclip. Déposez avec précaution ! def down drop_table : fin des utilisateurs
Vous pouvez également utiliser la méthode change , au lieu de la combinaison up / down ci-dessus, comme indiqué ci-dessous :
class CreateUsersWithAttachments < ActiveRecord::Migration def change create_table :les utilisateurs font |t| t.attachment :avatar end endend
Alternativement, les méthodes add_attachment et remove_attachment peuvent être utilisées pour ajouter de nouvelles colonnes Paperclip à une table existante :
class AddAttachmentColumnsToUsers < ActiveRecord::Migration def up add_attachment :users, :avatar end def down remove_attachment :users, :avatar endend
Ou vous pouvez le faire avec la méthode change :
class AddAttachmentColumnsToUsers < ActiveRecord::Migration def change add_attachment :users, :avatar endend
La syntaxe vintage (telle que t.has_attached_file et drop_attached_file ) est toujours prise en charge dans Paperclip 3.x, mais il est conseillé de mettre à jour ces fichiers de migration pour utiliser cette nouvelle syntaxe.
Paperclip est livré avec 3 adaptateurs de stockage :
Stockage de fichiers
Stockage S3 (via aws-sdk-s3 )
Stockage du brouillard
Si vous souhaitez utiliser Paperclip avec un autre stockage, vous pouvez installer ces joyaux avec Paperclip :
trombone-azur
trombone-azur-stockage
trombone-dropbox
Les fichiers affectés en tant que pièces jointes sont, par défaut, placés dans le répertoire spécifié par l'option :path de has_attached_file . Par défaut, cet emplacement est :rails_root/public/system/:class/:attachment/:id_partition/:style/:filename . Cet emplacement a été choisi car, sur les déploiements Capistrano standard, le répertoire public/system peut être lié symboliquement au répertoire partagé de l'application, ce qui signifie qu'il survit entre les déploiements. Par exemple, en utilisant ce :path , vous pouvez avoir un fichier à l'adresse
/data/myapp/releases/20081229172410/public/system/users/avatar/000/000/013/small/my_pic.png
REMARQUE : il s'agit d'un changement par rapport aux versions précédentes de Paperclip, mais il s'agit globalement d'un choix plus sûr pour le magasin de fichiers par défaut.
Vous pouvez également choisir de stocker vos fichiers à l'aide du service S3 d'Amazon. Pour ce faire, incluez la gem aws-sdk-s3 dans votre Gemfile :
gemme 'aws-sdk-s3'
Et puis vous pouvez spécifier en utilisant S3 à partir de has_attached_file . Vous pouvez trouver plus d'informations sur la configuration et l'utilisation du stockage S3 dans la documentation Paperclip::Storage::S3 .
Les fichiers sur le système de fichiers local (et dans le répertoire public de l'application Rails) seront disponibles sur Internet dans son ensemble. Si vous avez besoin d'un contrôle d'accès, il est possible de placer vos fichiers dans un emplacement différent. Vous devrez modifier les options :path et :url afin de vous assurer que les fichiers ne sont pas disponibles au public. :path et :url autorisent le même ensemble de variables interpolées.
Lorsqu'un fichier est téléchargé ou joint, il peut se présenter sous l'un des nombreux formulaires d'entrée différents, de l'objet UploadedFile de Rails à un StringIO en passant par un Tempfile ou même une simple chaîne qui est une URL qui pointe vers une image.
Paperclip acceptera, par défaut, plusieurs de ces sources. Il est également capable de gérer encore plus avec un peu de configuration. Les adaptateurs IO qui gèrent les images provenant de sources non locales ne sont pas activés par défaut. Ils peuvent être activés en ajoutant une ligne similaire à la suivante dans config/initializers/paperclip.rb :
Paperclip ::DataUriAdapter.register
Il est préférable d'activer un adaptateur de chargement à distance uniquement si vous en avez besoin. Sinon, il est possible que quelqu'un puisse avoir un aperçu de la structure de votre réseau interne en l'utilisant comme vecteur.
Les adaptateurs suivants ne sont pas chargés par défaut :
Paperclip::UriAdapter - qui accepte une instance URI .
Paperclip::HttpUrlProxyAdapter - qui accepte une chaîne http .
Paperclip::DataUriAdapter - qui accepte une chaîne data: codée en Base64.
Paperclip prend en charge une sélection extensible de post-processeurs. Lorsque vous définissez un ensemble de styles pour une pièce jointe, par défaut, ces « styles » sont en fait des « vignettes ». Ceux-ci sont traités par Paperclip::Thumbnail . Pour des raisons de compatibilité ascendante, vous pouvez transmettre soit une seule chaîne géométrique, soit un tableau contenant une géométrie et un format dans lequel le fichier sera converti, comme ceci :
has_attached_file :avatar, styles: { thumb: ["32x32#", :png] } Cela convertira le style « pouce » en un carré 32x32 au format PNG, quel que soit ce qui a été téléchargé. Si le format n'est pas précisé, il reste le même (par exemple les JPG resteront des JPG). Paperclip::Thumbnail utilise ImageMagick pour traiter les images ; La documentation sur la géométrie d'ImageMagick contient plus d'informations sur les formats de style acceptés.
Pour un contrôle plus précis du processus de conversion, source_file_options et convert_options peuvent être utilisés pour transmettre des indicateurs et des paramètres directement au puissant outil de conversion d'ImageMagick, documenté ici. Par exemple:
has_attached_file :image, styles : { régulier : ['800x800>', :png]},
source_file_options : { régular : "-densité 96 -profondeur 8 -qualité 85" }, convert_options : { régular : "-posterize 3"}ImageMagick prend en charge un certain nombre de variables d'environnement pour contrôler ses limites de ressources. Par exemple, vous pouvez imposer des limites de mémoire ou de temps d'exécution en définissant les variables suivantes dans l'environnement de processus de votre application :
MAGICK_MEMORY_LIMIT=128MiB
MAGICK_MAP_LIMIT=64MiB
MAGICK_TIME_LIMIT=30
Pour une liste complète des variables et une description, consultez la documentation des ressources d'ImageMagick.
Vous pouvez écrire vos propres processeurs de pièces jointes personnalisés pour effectuer des tâches telles que l'ajout de filigranes, la compression d'images ou le cryptage de fichiers. Les processeurs personnalisés doivent être définis dans le module Paperclip , hériter de Paperclip::Processor (voir lib/paperclip/processor.rb ) et implémenter une méthode make qui renvoie un File . Tous les fichiers des répertoires lib/paperclip et lib/paperclip_processors de votre application Rails seront automatiquement chargés par Paperclip. Les processeurs sont spécifiés à l'aide de l'option :processors de has_attached_file :
has_attached_file :scan, styles : { texte : { qualité : meilleure } }, processeurs : [:ocr] Cela chargerait la classe hypothétique Paperclip::Ocr et lui transmettrait les options hash { quality: :better } , ainsi que le fichier téléchargé.
Plusieurs processeurs peuvent être spécifiés et ils seront invoqués dans l'ordre dans lequel ils sont définis dans le tableau :processors . Chaque processeur successif reçoit le résultat du processeur précédent. Tous les processeurs reçoivent les mêmes paramètres, qui sont définis dans le hachage :styles . Par exemple, en supposant que nous ayons cette définition :
has_attached_file :scan, styles : { texte : { qualité : meilleure } }, processeurs : [:rotator, :ocr] Le processeur :rotator et le processeur :ocr recevraient les options { quality: :better } . Si un processeur reçoit une option qu'il ne reconnaît pas, il est censé l'ignorer.
REMARQUE : Étant donné que les processeurs fonctionnent en transformant la pièce jointe d'origine en styles, aucun processeur ne sera exécuté si aucun style n'est défini.
Si vous souhaitez mettre en cache la largeur, la hauteur et la taille de votre vignette dans la base de données, jetez un œil à la gemme paperclip-meta.
De plus, si vous souhaitez générer la vignette à la volée, vous souhaiterez peut-être consulter la gemme attachment_on_the_fly.
Le générateur de vignettes de Paperclip (voir lib/paperclip/thumbnail.rb ) est implémenté en tant que processeur et peut être une bonne référence pour écrire vos propres processeurs.
Avant et après l'étape de post-traitement, Paperclip rappelle le modèle avec quelques rappels, permettant au modèle de modifier ou d'annuler l'étape de traitement. Les rappels sont before_post_process et after_post_process (qui sont appelés avant et après le traitement de chaque pièce jointe), ainsi que les before_ et after_ spécifiques à la pièce jointe. Les rappels sont destinés à être aussi proches que possible des rappels ActiveRecord normaux, donc si vous retournez false (en particulier - renvoyer nil n'est pas la même chose) dans un before_filter , l'étape de post-traitement s'arrêtera. Renvoyer false dans un after_filter n'arrêtera rien, mais vous pouvez accéder au modèle et à la pièce jointe si nécessaire.
REMARQUE : Le post-traitement ne démarrera même pas si la pièce jointe n'est pas valide selon les validations. Vos rappels et processeurs ne seront appelés qu’avec des pièces jointes valides.
class Message < ActiveRecord::Base has_attached_file :asset, styles: { thumb: "100x100#" } before_post_process :skip_for_audio def skip_for_audio
! %w(audio/ogg application/ogg).include?(asset_content_type) fin Paperclip a une interpolation appelée :hash pour obscurcir les noms de fichiers des fichiers accessibles au public.
Exemple d'utilisation :
has_attached_file :avatar, {url : "/system/:hash.:extension", hash_secret : "longSecretString"} L'interpolation :hash sera remplacée par un hachage unique composé de tout ce qui est spécifié dans :hash_data . La valeur par défaut de :hash_data est ":class/:attachment/:id/:style/:updated_at" .
:hash_secret est requis - une exception sera levée si :hash est utilisé sans :hash_secret présent.
Pour en savoir plus sur cette fonctionnalité, lisez la propre explication de l'auteur
Une somme de contrôle du fichier d'origine attribué sera placée dans le modèle s'il possède un attribut nommé empreinte digitale. En suivant l'exemple de migration de modèle utilisateur ci-dessus, la migration ressemblerait à ce qui suit :
class AddAvatarFingerprintColumnToUser < ActiveRecord::Migration def up add_column :users, :avatar_fingerprint, :string end def down remove_column :users, :avatar_fingerprint endend
L'algorithme peut être spécifié à l'aide d'une option de configuration ; la valeur par défaut est MD5 pour une compatibilité ascendante avec Paperclip 5 et versions antérieures.
has_attached_file :some_attachment, adapter_options : { hash_digest : Digest ::SHA256 } Exécutez CLASS=User ATTACHMENT=avatar rake paperclip:refresh:fingerprints après avoir modifié le résumé des pièces jointes existantes pour mettre à jour les empreintes digitales dans la base de données.
Une option est disponible pour conserver les pièces jointes afin de jouer correctement avec les modèles supprimés de manière logicielle. (agit_comme_paranoïde, paranoïa, etc.)
has_attached_file :some_attachment, {preserve_files : true,} Cela empêchera some_attachment d'être effacé lorsque le modèle sera détruit, de sorte qu'il existera toujours lorsque l'objet sera restauré ultérieurement.
Les objets appelables (lambdas, Procs) peuvent être utilisés à plusieurs endroits pour une configuration dynamique dans Paperclip. Cette stratégie existe dans un certain nombre de composants de la bibliothèque, mais elle est plus importante dans les possibilités permettant d'appliquer des styles et des processeurs personnalisés à des instances de modèle spécifiques, plutôt que d'appliquer des styles et des processeurs définis à toutes les instances.
Imaginez un modèle d'utilisateur comportant différents styles en fonction du rôle de l'utilisateur. Peut-être que certains utilisateurs sont des patrons (par exemple, une instance de modèle utilisateur répond à #boss? ) et méritent une vignette d'avatar plus grande que les utilisateurs normaux. La configuration permettant de déterminer quels paramètres de style doivent être utilisés en fonction du rôle de l'utilisateur peut ressembler à ceci : un patron recevra une vignette 300x300 , sinon une vignette 100x100 sera créée.
class User < ActiveRecord::Base has_attached_file :avatar, styles: lambda { |attachment| { thumb : (attachment.instance.boss? ? "300x300>" : "100x100>") } }fin Un autre exemple artificiel est un modèle utilisateur qui sait quels processeurs de fichiers doivent lui être appliqués (au-delà du processeur thumbnail implicite invoqué lorsque :styles sont définis). Peut-être disposons-nous d'un processeur de filigrane et il n'est utilisé que sur les avatars de certains modèles. La configuration pour cela peut être celle où l'instance est interrogée pour savoir quels processeurs doivent lui être appliqués. Vraisemblablement, certains utilisateurs pourraient renvoyer [:thumbnail, :watermark] pour ses processeurs, où un processeur watermark défini est invoqué après le processeur thumbnail déjà défini par Paperclip.
class User < ActiveRecord::Base has_attached_file :avatar, processeurs : lambda { |instance| instance.processors } attr_accessor :processorsendPar défaut, Paperclip génère une journalisation en fonction de votre niveau d'enregistreur. Si vous souhaitez désactiver la journalisation (par exemple pendant les tests), ajoutez ceci dans la configuration de votre environnement :
Votre ::Application.configure do... Paperclip.options[:log] = false...end
Plus d'informations dans les rdocs
Pour créer un lien symbolique Capistrano vers le répertoire public/system afin que les pièces jointes survivent aux nouveaux déploiements, définissez l'option linked_dirs dans votre fichier config/deploy.rb :
set :linked_dirs, fetch(:linked_dirs, []).push('public/system') Paperclip est conscient des nouveaux styles de pièces jointes que vous avez ajoutés lors des déploiements précédents. La seule chose que vous devez faire après chaque déploiement est d'appeler rake paperclip:refresh:missing_styles . Il stockera les styles de pièces jointes actuels dans RAILS_ROOT/public/system/paperclip_attachments.yml par défaut. Vous pouvez le modifier en :
Paperclip.registered_attachments_styles_path = '/tmp/config/paperclip_attachments.yml'
Voici un exemple pour Capistrano :
espace de noms :paperclip faire desc "créer les styles de trombone manquants" tâche :build_missing_styles faire sur les rôles(:app) faire dans release_path faire avec rails_env: fetch(:rails_env) faire exécuter :rake, "paperclip:refresh:missing_styles" end end end endendafter( "deploy:compile_assets", "paperclip:build_missing_styles")
Désormais, vous n'avez plus besoin de penser à actualiser les vignettes en production chaque fois que vous ajoutez un nouveau style. Malheureusement, cela ne fonctionne pas avec les styles dynamiques – il les ignore simplement.
Si vous disposez déjà d'une application fonctionnelle et que vous ne souhaitez pas que rake paperclip:refresh:missing_styles actualise les anciennes images, vous devez indiquer à Paperclip les styles existants. Créez simplement un fichier paperclip_attachments.yml à la main. Par exemple:
class User < ActiveRecord::Base has_attached_file :avatar, styles: { thumb: 'x100', croppable: '600x600>', big: '1000x1000>' }endclass Book < ActiveRecord::Base has_attached_file :cover, styles: { small: 'x100', grand : '1000x1000>' } has_attached_file : exemple, styles : { thumb : 'x100' }end Puis dans RAILS_ROOT/public/system/paperclip_attachments.yml :
---:Utilisateur : :avatar: - :pouce - : recadrable - :big:Livre: :couverture: - :petit - :grand :échantillon: - :pouce
Paperclip fournit des comparateurs compatibles rspec pour tester les pièces jointes. Consultez la documentation sur Paperclip::Shoulda::Matchers pour plus d'informations.
Tests parallèles
En raison du path par défaut pour le stockage Paperclip, si vous essayez d'exécuter des tests en parallèle, vous constaterez peut-être que les fichiers sont écrasés car le même chemin est calculé pour eux dans chaque processus de test. Bien que ce correctif fonctionne pour parallel_tests, un concept similaire doit être utilisé pour tout autre mécanisme permettant d'exécuter des tests simultanément.
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/ :filename"else Paperclip::Attachment.default_options[:path] = ":rails_root/public/system/:rails_env/:class/:attachment/:id_partition/:filename"end La partie importante ici étant l'inclusion de ENV['TEST_ENV_NUMBER'] , ou un mécanisme similaire pour la bibliothèque de tests parallèles que vous utilisez.
Tests d'intégration
L'utilisation de tests d'intégration avec FactoryBot peut enregistrer plusieurs copies de vos fichiers de test dans l'application. Pour éviter cela, spécifiez un chemin personnalisé dans le config/environments/test.rb comme ceci :
Paperclip::Attachment.default_options[:path] = "#{Rails.root}/spec/test_files/:class/:id_partition/:style.:extension" Ensuite, assurez-vous de supprimer ce répertoire après l'exécution de la suite de tests en l'ajoutant à spec_helper.rb .
config.after(:suite) do FileUtils.rm_rf(Dir["#{Rails.root}/spec/test_files/"])endExemple de configuration de test avec Factory Bot
FactoryBot.define do factory :user do avatar { File.new("#{Rails.root}/spec/support/fixtures/image.jpg") } endendSi vous souhaitez contribuer à une fonctionnalité ou à une correction de bug : merci ! Pour vous assurer que votre correctif/fonctionnalité a de grandes chances d'être inclus, veuillez lire les directives suivantes :
Publiez une pull request.
Assurez-vous qu'il y a des tests ! Nous n'accepterons aucun patch non testé. Il est rare que des tests explicites ne soient pas nécessaires. Si vous avez des questions sur l'écriture de tests pour paperclip, veuillez ouvrir un ticket GitHub.
Veuillez consulter CONTRIBUTING.md pour plus de détails sur la contribution et l'exécution des tests.
Merci à tous les contributeurs !
Le trombone est protégé par copyright © 2008-2017 thinkbot, inc. Il s'agit d'un logiciel gratuit et peut être redistribué selon les conditions spécifiées dans le fichier MIT-LICENSE.
Paperclip est maintenu et financé par Thoughtbot. Les noms et logos de Thoughtbot sont des marques commerciales de Thoughtbot, inc.
Nous aimons les logiciels open source ! Consultez nos autres projets ou engagez-nous pour concevoir, développer et développer votre produit.
