A package to ease the use of multiple storage and CDN services.
Add Storage to the package dependencies (in your Package.swift file):
dependencies: [
...,
.package(url: "https://github.com/nodes-vapor/storage.git", from: "1.0.0")
]as well as to your target (e.g. "App"):
targets: [
...
.target(
name: "App",
dependencies: [... "Storage" ...]
),
...
]Storage makes it easy to start uploading and downloading files. Just register a network driver and get going.
There are a few different interfaces for uploading a file, the simplest being the following:
Storage.upload(
bytes: [UInt8],
fileName: String?,
fileExtension: String?,
mime: String?,
folder: String,
on container: Container
) throws -> StringThe aforementioned function will attempt to upload the file using your selected driver and template and will return a String representing the location of the file.
If you want to upload an image named profile.png your call site would look like:
try Storage.upload(
bytes: bytes,
fileName: "profile.png",
on: req
)Is your file a base64 or data URI? No problem!
Storage.upload(base64: "SGVsbG8sIFdvcmxkIQ==", fileName: "base64.txt", on: req)
Storage.upload(dataURI: "data:,Hello%2C%20World!", fileName: "data-uri.txt", on: req)Download an asset from a URL and then reupload it to your storage server.
Storage.upload(url: "http://mysite.com/myimage.png", fileName: "profile.png", on: req)To download a file that was previously uploaded you simply use the generated path.
// download image as `Foundation.Data`
let data = try Storage.get("/images/profile.png", on: req)In order to use the CDN path convenience, you'll have to set the CDN base url on Storage, e.g. in your configure.swift file:
Storage.cdnBaseURL = "https://cdn.vapor.cloud"Here is how you generate the CDN path to a given asset.
let cdnPath = try Storage.getCDNPath(for: path)If your CDN path is more involved than cdnUrl + path, you can build out Storage's optional completionhandler to override the default functionality.
Storage.cdnPathBuilder = { baseURL, path in
let joinedPath = (baseURL + path)
return joinedPath.replacingOccurrences(of: "/images/original/", with: "/image/")
}Deleting a file can be done as follows.
try Storage.delete("/images/profile.png")Storage has a variety of configurable options.
The network driver is the module responsible for interacting with your 3rd party service. The default, and currently the only, driver is s3.
import Storage
let driver = try S3Driver(
bucket: "bucket",
accessKey: "access",
secretKey: "secret"
)
services.register(driver, as: NetworkDriver.self)bucket, accessKeyand secretKey are required by the S3 driver, while template, host and region are optional. region will default to eu-west-1 and host will default to s3.amazonaws.com.
A times, you may need to upload files to a different scheme than /file.ext. You can achieve this by passing in the pathTemplate parameter when creating the S3Driver. If the parameter is omitted it will default to /#file.
The following template will upload profile.png from the folder images to /myapp/images/profile.png
let driver = try S3Driver(
bucket: "mybucket",
accessKey: "myaccesskey",
secretKey: "mysecretkey",
pathTemplate: "/myapp/#folder/#file"
)Aliases are special keys in your template that will be replaced with dynamic information at the time of upload.
Note: if you use an alias and the information wasn't provided at the file upload's callsite, Storage will throw a missingX/malformedX error.
#file: The file's name and extension.
File: "test.png"
Returns: test.png
#fileName: The file's name.
File: "test.png"
Returns: test
#fileExtension: The file's extension.
File: "test.png"
Returns: png
#folder: The provided folder.
File: "uploads/test.png"
Returns: uploads
#mime: The file's content type.
File: "test.png"
Returns: image/png
#mimeFolder: A folder generated according to the file's mime.
This alias will check the file's mime and if it's an image, it will return images/original else it will return data
File: "test.png"
Returns: images/original
#day: The current day.
File: "test.png"
Date: 12/12/2012
Returns: 12
#month: The current month.
File: "test.png"
Date: 12/12/2012
Returns: 12
#year: The current year.
File: "test.png"
Date: 12/12/2012
Returns: 2012
#timestamp: The time of upload.
File: "test.png"
Time: 17:05:00
Returns: 17:05:00
#uuid: A generated UUID.
File: "test.png"
Returns: 123e4567-e89b-12d3-a456-426655440000
This package is developed and maintained by the Vapor team at Nodes.
This package is open-sourced software licensed under the MIT license