Verse::Shrine

This gem provides a plugin to integrate the Shrine file attachment library with the Verse framework. It allows you to easily configure and use Shrine for file uploads, downloads, and management within your Verse application.

Installation

Add this line to your application's Gemfile:

gem 'verse-shrine'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install verse-shrine

Configuration

To use the verse-shrine plugin, you need to configure it in your config/verse.yml file. The plugin allows you to define multiple storages, each with a specific adapter and configuration.

Here's an example of how to configure the plugin with a file system storage:

plugins:
  - name: shrine
    config:
      storages:
        - name: :cache # The name of the storage
          adapter: :file_system # The adapter to use
          config:
            path: "tmp/shrine" # The path where to store the files
            prefix: "cache" # A prefix for the files in the storage
        - name: :store # The name of the storage
          adapter: :file_system
          config:
            path: "public/uploads"
            prefix: "store"

Supported Adapters

The plugin supports the following adapters:

• :file_system: Stores files on the local filesystem.
• :s3: Stores files on Amazon S3.

File System Adapter Configuration

The :file_system adapter has the following configuration options:

• path (required): The directory where files will be stored.
• prefix (optional): A subdirectory within the path where files will be stored.
• directory_permissions (optional): The permissions for the created directories, in octal format (e.g., "755").
• permissions (optional): The permissions for the created files, in octal format (e.g., "644").

S3 Adapter Configuration

The :s3 adapter has the following configuration options:

• bucket (required): The name of the S3 bucket.
• access_key_id (required): Your AWS access key ID.
• secret_access_key (required): Your AWS secret access key.
• region (optional): The AWS region of your bucket.
• prefix (optional): A prefix for the files in the bucket.
• endpoint (optional): The S3 endpoint (for S3-compatible services).
• public (optional, default: true): Whether the files should be publicly accessible.

Here's an example of how to configure the S3 adapter:

plugins:
  - name: shrine
    config:
      storages:
        - name: :store
          adapter: :s3
          config:
            bucket: "my-bucket"
            access_key_id: "YOUR_ACCESS_KEY_ID"
            secret_access_key: "YOUR_SECRET_ACCESS_KEY"
            region: "us-east-1"
            prefix: "uploads"

Usage

Once the plugin is configured, you can access the storage manager through the Verse::Plugin[:shrine] method. The manager provides methods for uploading, downloading, and deleting files.

Accessing a Storage

To access a specific storage, you can use the storage method on the plugin instance:

# Get the default storage manager
storage_manager = Verse::Plugin[:shrine].storage(:store)

# Get a specific storage manager
cache_manager = Verse::Plugin[:shrine].storage(:cache)

You can also use the with_storage method to work with a storage in a block:

Verse::Plugin[:shrine].with_storage(:store) do |storage|
  file = File.open("my_file.txt")
  file_info = storage.upload(file)
  puts "File uploaded with ID: #{file_info.id}"
end

Uploading a File

To upload a file, use the upload method on the storage manager. This method takes a file-like object (e.g., an IO or a File) and returns a FileInfo struct with the uploaded file's information.

file = File.open("my_file.txt")
file_info = storage_manager.upload(file)

puts "File uploaded with ID: #{file_info.id}"
puts "File URL: #{file_info.file_url}"

The FileInfo struct contains the following attributes:

• id: The unique ID of the uploaded file.
• filename: The name of the uploaded file.
• size: The size of the uploaded file in bytes.
• mime_type: The MIME type of the uploaded file.
• file_url: The URL of the uploaded file.

Downloading a File

To download a file, use the open method on the storage manager. This method takes a file ID and returns a Shrine::UploadedFile object, which you can use to read the file's content.

uploaded_file = storage_manager.open(file_info.id)
puts uploaded_file.read

Deleting a File

To delete a file, use the delete method on the storage manager. This method takes a file ID and deletes the corresponding file from the storage.

storage_manager.delete(file_info.id)

Plugin Lifecycle

The verse-shrine plugin is loaded and initialized by the verse-core plugin system. When the application starts, the on_init method of the plugin is called, which initializes Shrine, validates the configuration, and sets up the configured storages.

The plugin registers a Manager instance for each configured storage, which can be accessed as described in the Usage section.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/verse-rb/verse.

License

The gem is available as open source under the terms of the MIT License.