paperclip 6.0.0 → 6.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 610c7d5a2752fdd632262c73bcfbdf2cfc170663
-  data.tar.gz: 4c8484cdd5426d92a272d45e0bd9ee46e77e9c07
+SHA256:
+  metadata.gz: 898cd227405301490ff021b70120159d15482f1bcf07357f32bc4f14c92a5a46
+  data.tar.gz: 48290676c056a90077da05f9906e8621ab2e8593634606b8bcf8e7beee28ef15
 SHA512:
-  metadata.gz: 9d03df62f808fe6cb43b50389ed78071a592bd5b72ad73477ccebd08b12bba0f3e6810209e8d00bcb15128c9f359efccf04f874dddc84e1c89c7adcb16fb6ad0
-  data.tar.gz: e8c3f8a23d4d42d75460a1204f37e5ba75fd4e3a6b58859d1d3e33929a46e253e60d5cbd923e11dda6856ec43d5c19fff3cc57f83a3e08dbe8d2f6574c059286
+  metadata.gz: 589b966a2cdf5ccaafa13faa9fb9298e5501274d282aafb098260ffc5268892828ea3f8ddbe4f5ee8de8dcc365031f417577d69b3320cc558eda6b8917ede710
+  data.tar.gz: 1b1559aa80cac274756a923a7b943cc4c50e06d984c362764ceeda86f75d9eae2833428dffa0959eee56984e2034e091fd2811aea30b9e933713bfb0070cb107

data/.github/issue_template.md

@@ -0,0 +1,3 @@
+## Deprecation notice
+
+Paperclip is currently undergoing [deprecation in favor of ActiveStorage](https://github.com/thoughtbot/paperclip/blob/master/MIGRATING.md). Maintainers of this repository will no longer be tending to new issues. We're leaving the issues page open so Paperclip users can still see & search through old issues, and continue existing discussions if they wish.

data/MIGRATING-ES.md

@@ -0,0 +1,317 @@
+# Migrando de Paperclip a ActiveStorage
+
+Paperclip y ActiveStorage resuelven problemas similares con soluciones
+similares, por lo que pasar de uno a otro es simple.
+
+El proceso de ir desde Paperclip hacia ActiveStorage es como sigue:
+
+1. Implementa las migraciones a la base de datos de ActiveStorage.
+2. Configura el almacenamiento.
+3. Copia la base de datos.
+4. Copia los archivos.
+5. Actualiza tus pruebas.
+6. Actualiza tus vistas.
+7. Actualiza tus controladores.
+8. Actualiza tus modelos.
+
+## Implementa las migraciones a la base de datos de ActiveStorage
+
+Sigue [las instrucciones para instalar ActiveStorage]. Muy probablemente vas a
+querer agregar la gema `mini_magick` a tu Gemfile.
+
+
+```sh
+rails active_storage:install
+```
+
+[las instrucciones para instalar ActiveStorage]: https://github.com/rails/rails/blob/master/activestorage/README.md#installation
+
+## Configura el almacenamiento
+
+De nuevo, sigue [las instrucciones para configurar ActiveStorage].
+
+[las instrucciones para configurar ActiveStorage]: http://edgeguides.rubyonrails.org/active_storage_overview.html#setup
+
+## Copia la base de datos.
+
+Las tablas `active_storage_blobs` y`active_storage_attachments` son en donde
+ActiveStorage espera encontrar los metadatos del archivo. Paperclip almacena los
+metadatos del archivo directamente en en la tabla del objeto asociado.
+
+Vas a necesitar escribir una migración para esta conversión. Proveer un script
+simple, es complicado porque están involucrados tus modelos. ¡Pero lo
+intentaremos!
+
+Así sería para un `User` con un `avatar` en Paperclip:
+
+```ruby
+class User < ApplicationRecord
+  has_attached_file :avatar
+end
+```
+
+Tus migraciones de Paperclip producirán una tabla como la siguiente:
+
+```ruby
+create_table "users", force: :cascade do |t|
+  t.string "avatar_file_name"
+  t.string "avatar_content_type"
+  t.integer "avatar_file_size"
+  t.datetime "avatar_updated_at"
+end
+```
+
+Y tu la convertirás en estas tablas:
+
+```ruby
+create_table "active_storage_attachments", force: :cascade do |t|
+  t.string "name", null: false
+  t.string "record_type", null: false
+  t.integer "record_id", null: false
+  t.integer "blob_id", null: false
+  t.datetime "created_at", null: false
+  t.index ["blob_id"], name: "index_active_storage_attachments_on_blob_id"
+  t.index ["record_type", "record_id", "name", "blob_id"], name: "index_active_storage_attachments_uniqueness", unique: true
+end
+```
+
+```ruby
+create_table "active_storage_blobs", force: :cascade do |t|
+  t.string "key", null: false
+  t.string "filename", null: false
+  t.string "content_type"
+  t.text "metadata"
+  t.bigint "byte_size", null: false
+  t.string "checksum", null: false
+  t.datetime "created_at", null: false
+  t.index ["key"], name: "index_active_storage_blobs_on_key", unique: true
+end
+```
+
+Así que asumiendo que quieres dejar los archivos en el mismo lugar, _esta es tu
+migración_. De otra forma, ve la siguiente sección primero y modifica la
+migración como corresponda.
+
+```ruby
+Dir[Rails.root.join("app/models/**/*.rb")].sort.each { |file| require file }
+
+class ConvertToActiveStorage < ActiveRecord::Migration[5.2]
+  require 'open-uri'
+
+  def up
+    # postgres
+    get_blob_id = 'LASTVAL()'
+    # mariadb
+    # get_blob_id = 'LAST_INSERT_ID()'
+    # sqlite
+    # get_blob_id = 'LAST_INSERT_ROWID()'
+
+    active_storage_blob_statement = ActiveRecord::Base.connection.raw_connection.prepare(<<-SQL)
+      INSERT INTO active_storage_blobs (
+        key, filename, content_type, metadata, byte_size,
+        checksum, created_at
+      ) VALUES (?, ?, ?, '{}', ?, ?, ?)
+    SQL
+
+    active_storage_attachment_statement = ActiveRecord::Base.connection.raw_connection.prepare(<<-SQL)
+      INSERT INTO active_storage_attachments (
+        name, record_type, record_id, blob_id, created_at
+      ) VALUES (?, ?, ?, #{get_blob_id}, ?)
+    SQL
+
+    models = ActiveRecord::Base.descendants.reject(&:abstract_class?)
+
+    transaction do
+      models.each do |model|
+        attachments = model.column_names.map do |c|
+          if c =~ /(.+)_file_name$/
+            $1
+          end
+        end.compact
+
+        model.find_each.each do |instance|
+          attachments.each do |attachment|
+            active_storage_blob_statement.execute(
+              key(instance, attachment),
+              instance.send("#{attachment}_file_name"),
+              instance.send("#{attachment}_content_type"),
+              instance.send("#{attachment}_file_size"),
+              checksum(instance.send(attachment)),
+              instance.updated_at.iso8601
+            )
+
+            active_storage_attachment_statement.
+              execute(attachment, model.name, instance.id, instance.updated_at.iso8601)
+          end
+        end
+      end
+    end
+
+    active_storage_attachment_statement.close
+    active_storage_blob_statement.close
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration
+  end
+
+  private
+
+  def key(instance, attachment)
+    SecureRandom.uuid
+    # Alternativamente:
+    # instance.send("#{attachment}_file_name")
+  end
+
+  def checksum(attachment)
+    # archivos locales almacenados en disco:
+    url = attachment.path
+    Digest::MD5.base64digest(File.read(url))
+
+    # archivos remotos almacenados en la computadora de alguién más:
+    # url = attachment.url
+    # Digest::MD5.base64digest(Net::HTTP.get(URI(url)))
+  end
+end
+```
+
+## Copia los archivos
+
+La migración de arriba deja los archivos como estaban. Sin embargo,
+los servicios de Paperclip y ActiveStorage utilizan diferentes ubicaciones.
+
+Por defecto, Paperclip se ve así:
+
+```
+public/system/users/avatars/000/000/004/original/the-mystery-of-life.png
+```
+
+Y ActiveStorage se ve así:
+
+```
+storage/xM/RX/xMRXuT6nqpoiConJFQJFt6c9
+```
+
+Ese `xMRXuT6nqpoiConJFQJFt6c9` es el valor de `active_storage_blobs.key`. En la
+migración de arriba usamos simplemente el nombre del archivo, pero tal vez
+quieras usar un UUID.
+
+Migrando los archivos en un hospedaje externo (S3, Azure Storage, GCS, etc.)
+está fuera del alcance de este documento inicial. Así es como se vería para un
+almacenamiento local:
+
+```ruby
+#!bin/rails runner
+
+class ActiveStorageBlob < ActiveRecord::Base
+end
+
+class ActiveStorageAttachment < ActiveRecord::Base
+  belongs_to :blob, class_name: 'ActiveStorageBlob'
+  belongs_to :record, polymorphic: true
+end
+
+ActiveStorageAttachment.find_each do |attachment|
+  name = attachment.name
+
+  source = attachment.record.send(name).path
+  dest_dir = File.join(
+    "storage",
+    attachment.blob.key.first(2),
+    attachment.blob.key.first(4).last(2))
+  dest = File.join(dest_dir, attachment.blob.key)
+
+  FileUtils.mkdir_p(dest_dir)
+  puts "Moving #{source} to #{dest}"
+  FileUtils.cp(source, dest)
+end
+```
+
+## Actualiza tus pruebas
+
+En lugar de utilizar `have_attached_file`, será necesario que escribas tu propio
+matcher. Aquí hay un matcher similar _en espíritu_ al que Paperclip provee:
+
+
+```ruby
+RSpec::Matchers.define :have_attached_file do |name|
+  matches do |record|
+    file = record.send(name)
+    file.respond_to?(:variant) && file.respond_to?(:attach)
+  end
+end
+```
+
+## Actualiza tus vistas
+
+En Paperclip se ven así:
+
+```ruby
+image_tag @user.avatar.url(:medium)
+```
+
+En ActiveStorage se ven así:
+
+```ruby
+image_tag @user.avatar.variant(resize: "250x250")
+```
+
+## Actualiza tus controladores
+
+Esto no debería _requerir_ ningúna actualización. Sin embargo, si te fijas en
+el schema de tu base de datos, notaras un join.
+
+Por ejemplo si tu controlador tiene:
+
+```ruby
+def index
+  @users = User.all.order(:name)
+end
+```
+
+Y tu vista tiene:
+
+```
+<ul>
+  <% @users.each do |user| %>
+    <li><%= image_tag user.avatar.variant(resize: "10x10"), alt: user.name %></li>
+  <% end %>
+</ul>
+```
+
+Vas a terminar con un n+1, ya que descargas cada archivo adjunto dentro del
+bucle.
+
+Así que mientras que el controlador y el modelo funcionarán sin ningún cambio,
+tal vez quieras revisar dos veces tus bucles y agregar `includes` en dónde haga
+falta.
+
+ActiveStorage agrega `avatar_attachment` y `avatar_blob` a las relaciones del
+tipo `has-one`, así como `avatar_attachments` y `avatar_blobs` a las relaciones
+de tipo `has-many`:
+
+```ruby
+def index
+  @users = User.all.order(:name).includes(:avatar_attachment)
+end
+```
+
+## Actualiza tus modelos
+
+Sigue [la guía sobre cómo adjuntar archivos a los registros]. Por ejemplo, un
+`User` con un `avatar` se representa como:
+
+```ruby
+class User < ApplicationRecord
+  has_one_attached :avatar
+end
+```
+
+Cualquier cambio de tamaño se hace en la vista como un `variant`.
+
+[la guía sobre cómo adjuntar archivos a los registros]: http://edgeguides.rubyonrails.org/active_storage_overview.html#attaching-files-to-records
+
+## Quita Paperclip
+
+Quita la gema de tu `Gemfile` y corre `bundle`. Corre tus pruebas porque ya
+terminaste!

data/MIGRATING.md

@@ -0,0 +1,375 @@
+# Migrating from Paperclip to ActiveStorage
+
+Paperclip and ActiveStorage solve similar problems with similar solutions, so
+transitioning from one to the other is straightforward data re-writing.
+
+The process of going from Paperclip to ActiveStorage is as follows:
+
+1. Apply the ActiveStorage database migrations.
+2. Configure storage.
+3. Copy the database data over.
+4. Copy the files over.
+5. Update your tests.
+6. Update your views.
+7. Update your controllers.
+8. Update your models.
+
+## Apply the ActiveStorage database migrations
+
+Follow [the instructions for installing ActiveStorage]. You'll very likely want
+to add the `mini_magick` gem to your Gemfile.
+
+```sh
+rails active_storage:install
+```
+
+[the instructions for installing ActiveStorage]: https://github.com/rails/rails/blob/master/activestorage/README.md#installation
+
+## Configure storage
+
+Again, follow [the instructions for configuring ActiveStorage].
+
+[the instructions for configuring ActiveStorage]: http://edgeguides.rubyonrails.org/active_storage_overview.html#setup
+
+## Copy the database data over
+
+The `active_storage_blobs` and `active_storage_attachments` tables are where
+ActiveStorage expects to find file metadata. Paperclip stores the file metadata
+directly on the associated object's table.
+
+You'll need to write a migration for this conversion. Because the models for
+your domain are involved, it's tricky to supply a simple script. But we'll try!
+
+Here's how it would go for a `User` with an `avatar`, that is this in
+Paperclip:
+
+```ruby
+class User < ApplicationRecord
+  has_attached_file :avatar
+end
+```
+
+Your Paperclip migrations will produce a table like so:
+
+```ruby
+create_table "users", force: :cascade do |t|
+  t.string "avatar_file_name"
+  t.string "avatar_content_type"
+  t.integer "avatar_file_size"
+  t.datetime "avatar_updated_at"
+end
+```
+
+And you'll be converting into these tables:
+
+```ruby
+create_table "active_storage_attachments", force: :cascade do |t|
+  t.string "name", null: false
+  t.string "record_type", null: false
+  t.integer "record_id", null: false
+  t.integer "blob_id", null: false
+  t.datetime "created_at", null: false
+  t.index ["blob_id"], name: "index_active_storage_attachments_on_blob_id"
+  t.index ["record_type", "record_id", "name", "blob_id"], name: "index_active_storage_attachments_uniqueness", unique: true
+end
+```
+
+```ruby
+create_table "active_storage_blobs", force: :cascade do |t|
+  t.string "key", null: false
+  t.string "filename", null: false
+  t.string "content_type"
+  t.text "metadata"
+  t.bigint "byte_size", null: false
+  t.string "checksum", null: false
+  t.datetime "created_at", null: false
+  t.index ["key"], name: "index_active_storage_blobs_on_key", unique: true
+end
+```
+
+So, assuming you want to leave the files in the exact same place,  _this is
+your migration_. Otherwise, see the next section first and modify the migration
+to taste.
+
+```ruby
+Dir[Rails.root.join("app/models/**/*.rb")].sort.each { |file| require file }
+
+class ConvertToActiveStorage < ActiveRecord::Migration[5.2]
+  require 'open-uri'
+
+  def up
+    # postgres
+    get_blob_id = 'LASTVAL()'
+    # mariadb
+    # get_blob_id = 'LAST_INSERT_ID()'
+    # sqlite
+    # get_blob_id = 'LAST_INSERT_ROWID()'
+
+    active_storage_blob_statement = ActiveRecord::Base.connection.raw_connection.prepare(<<-SQL)
+      INSERT INTO active_storage_blobs (
+        `key`, filename, content_type, metadata, byte_size, checksum, created_at
+      ) VALUES (?, ?, ?, '{}', ?, ?, ?)
+    SQL
+
+    active_storage_attachment_statement = ActiveRecord::Base.connection.raw_connection.prepare(<<-SQL)
+      INSERT INTO active_storage_attachments (
+        name, record_type, record_id, blob_id, created_at
+      ) VALUES (?, ?, ?, #{get_blob_id}, ?)
+    SQL
+
+    models = ActiveRecord::Base.descendants.reject(&:abstract_class?)
+
+    transaction do
+      models.each do |model|
+        attachments = model.column_names.map do |c|
+          if c =~ /(.+)_file_name$/
+            $1
+          end
+        end.compact
+
+        model.find_each.each do |instance|
+          attachments.each do |attachment|
+            active_storage_blob_statement.execute(
+              key(instance, attachment),
+              instance.send("#{attachment}_file_name"),
+              instance.send("#{attachment}_content_type"),
+              instance.send("#{attachment}_file_size"),
+              checksum(instance.send(attachment)),
+              instance.updated_at.iso8601
+            )
+
+            active_storage_attachment_statement.
+              execute(attachment, model.name, instance.id, instance.updated_at.iso8601)
+          end
+        end
+      end
+    end
+
+    active_storage_attachment_statement.close
+    active_storage_blob_statement.close
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration
+  end
+
+  private
+
+  def key(instance, attachment)
+    SecureRandom.uuid
+    # Alternatively:
+    # instance.send("#{attachment}_file_name")
+  end
+
+  def checksum(attachment)
+    # local files stored on disk:
+    url = attachment.path
+    Digest::MD5.base64digest(File.read(url))
+
+    # remote files stored on another person's computer:
+    # url = attachment.url
+    # Digest::MD5.base64digest(Net::HTTP.get(URI(url)))
+  end
+end
+```
+
+## Copy the files over
+
+The above migration leaves the files as they are. However, the default
+Paperclip and ActiveStorage storage services use different locations.
+
+By default, Paperclip looks like this:
+
+```
+public/system/users/avatars/000/000/004/original/the-mystery-of-life.png
+```
+
+And ActiveStorage looks like this:
+
+```
+storage/xM/RX/xMRXuT6nqpoiConJFQJFt6c9
+```
+
+That `xMRXuT6nqpoiConJFQJFt6c9` is the `active_storage_blobs.key` value. In the
+migration above we simply used the filename but you may wish to use a UUID
+instead.
+
+
+### Moving local storage files
+
+```ruby
+#!bin/rails runner
+
+class ActiveStorageBlob < ActiveRecord::Base
+end
+
+class ActiveStorageAttachment < ActiveRecord::Base
+  belongs_to :blob, class_name: 'ActiveStorageBlob'
+  belongs_to :record, polymorphic: true
+end
+
+ActiveStorageAttachment.find_each do |attachment|
+  name = attachment.name
+
+  source = attachment.record.send(name).path
+  dest_dir = File.join(
+    "storage",
+    attachment.blob.key.first(2),
+    attachment.blob.key.first(4).last(2))
+  dest = File.join(dest_dir, attachment.blob.key)
+
+  FileUtils.mkdir_p(dest_dir)
+  puts "Moving #{source} to #{dest}"
+  FileUtils.cp(source, dest)
+end
+```
+
+### Moving files on a remote host (S3, Azure Storage, GCS, etc.)
+
+One of the most straightforward ways to move assets stored on a remote host is
+to use a rake task that regenerates the file names and places them in the
+proper file structure/hierarchy.
+
+Assuming you have a model configured similarly to the example below:
+
+```ruby
+class Organization < ApplicationRecord
+  # New ActiveStorage declaration
+  has_one_attached :logo
+
+  # Old Paperclip config
+  # must be removed BEFORE to running the rake task so that
+  # all of the new ActiveStorage goodness can be used when
+  # calling organization.logo
+  has_attached_file :logo,
+                    path: "/organizations/:id/:basename_:style.:extension",
+                    default_url: "https://s3.amazonaws.com/xxxxx/organizations/missing_:style.jpg",
+                    default_style: :normal,
+                    styles: { thumb: "64x64#", normal: "400x400>" },
+                    convert_options: { thumb: "-quality 100 -strip", normal: "-quality 75 -strip" }
+end
+```
+
+The following rake task would migrate all of your assets:
+
+```ruby
+namespace :organizations do
+  task migrate_to_active_storage: :environment do
+    Organization.where.not(logo_file_name: nil).find_each do |organization|
+      # This step helps us catch any attachments we might have uploaded that
+      # don't have an explicit file extension in the filename
+      image = organization.logo_file_name
+      ext = File.extname(image)
+      image_original = URI.unescape(image.gsub(ext, "_original#{ext}"))
+
+      # this url pattern can be changed to reflect whatever service you use
+      logo_url = "https://s3.amazonaws.com/xxxxx/organizations/#{organization.id}/#{image_original}"
+      organization.logo.attach(io: open(logo_url),
+                                   filename: organization.logo_file_name,
+                                   content_type: organization.logo_content_type)
+    end
+  end
+end
+```
+
+An added advantage of this method is that you're creating a copy of all assets,
+which is handy in the event you need to rollback your deploy.
+
+This also means that you can run the rake task from your development machine
+and completely migrate the assets before your deploy, minimizing the chances
+that you'll have a timed-out deployment.
+
+The main drawback of this method is the same as its benefit - you are
+essentially duplicating all of your assets. These days storage and bandwidth
+are relatively cheap, but in some instances where you have a huge volume of
+files, or very large file sizes, this might get a little less feasible.
+
+In my experience I was able to move tens of thousands of images in a matter of
+a couple of hours, just by running the migration overnight on my MacBook Pro.
+
+Once you've confirmed that the migration and deploy have gone successfully you
+can safely delete the old assets from your remote host.
+
+## Update your tests
+
+Instead of the `have_attached_file` matcher, you'll need to write your own.
+Here's one that is similar in spirit to the Paperclip-supplied matcher:
+
+```ruby
+RSpec::Matchers.define :have_attached_file do |name|
+  matches do |record|
+    file = record.send(name)
+    file.respond_to?(:variant) && file.respond_to?(:attach)
+  end
+end
+```
+
+## Update your views
+
+In Paperclip it looks like this:
+
+```ruby
+image_tag @user.avatar.url(:medium)
+```
+
+In ActiveStorage it looks like this:
+
+```ruby
+image_tag @user.avatar.variant(resize: "250x250")
+```
+
+## Update your controllers
+
+This should _require_ no update. However, if you glance back at the database
+schema above, you may notice a join.
+
+For example, if your controller has
+
+```ruby
+def index
+  @users = User.all.order(:name)
+end
+```
+
+And your view has
+
+```
+<ul>
+  <% @users.each do |user| %>
+    <li><%= image_tag user.avatar.variant(resize: "10x10"), alt: user.name %></li>
+  <% end %>
+</ul>
+```
+
+Then you'll end up with an n+1 as you load each attachment in the loop.
+
+So while the controller and model will work without change, you will want to
+double-check your loops and add `includes` as needed. ActiveStorage adds an
+`avatar_attachment` and `avatar_blob` relationship to has-one relations, and
+`avatar_attachments` and `avatar_blobs` to has-many:
+
+```ruby
+def index
+  @users = User.all.order(:name).includes(:avatar_attachment)
+end
+```
+
+## Update your models
+
+Follow [the guide on attaching files to records]. For example, a `User` with an
+`avatar` is represented as:
+
+```ruby
+class User < ApplicationRecord
+  has_one_attached :avatar
+end
+```
+
+Any resizing is done in the view as a variant.
+
+[the guide on attaching files to records]: http://edgeguides.rubyonrails.org/active_storage_overview.html#attaching-files-to-records
+
+## Remove Paperclip
+
+Remove the Gem from your `Gemfile` and run `bundle`. Run your tests because
+you're done!