FORGEBOX Enterprise 🚀 - Take your ColdFusion (CFML) Development to Modern Times! Learn More...

Amazon S3 SDK

v4.5.0+110 Public

Build Status

Welcome to the Amazon S3, DigitalOcean Spaces SDK

This SDK allows you to add Amazon S3, Digital Ocean Spaces capabilities to your ColdFusion (CFML) applications. It is also a ColdBox Module, so if you are using ColdBox, you get auto-registration and much more.

Resources

Installation

This SDK can be installed as standalone or as a ColdBox Module. Either approach requires a simple CommandBox command:

box install s3sdk

Then follow either the standalone or module instructions below.

Standalone

This SDK will be installed into a directory called s3sdk and then the SDK can be instantiated via new s3sdk.models.AmazonS3() with the following constructor arguments:

/**
 * Create a new S3SDK Instance
 *
 * @accessKey The Amazon access key.
 * @secretKey The Amazon secret key.
 * @awsDomain The Domain used S3 Service (amazonws.com, digitalocean.com, storage.googleapis.com). Defaults to amazonws.com
 * @awsRegion The Amazon region. Defaults to us-east-1 for amazonaws.com
 * @encryption_charset The charset for the encryption. Defaults to UTF-8.
 * @signature The signature version to calculate, "V2" is deprecated but more compatible with other endpoints. "V4" requires Sv4Util.cfc & ESAPI on Lucee. Defaults to V4
 * @ssl True if the request should use SSL. Defaults to true.
 * @defaultTimeOut Default HTTP timeout for all requests. Defaults to 300.
 * @defaultDelimiter Delimter to use for getBucket calls. "/" is standard to treat keys as file paths
 * @defaultBucketName Bucket name to use by default
 * @defaultCacheControl Default caching policy for objects. Defaults to: no-store, no-cache, must-revalidate
 * @defaultStorageClass Default storage class for objects that affects cost, access speed and durability. Defaults to STANDARD.
 * @defaultACL Default access control policy for objects and buckets. Defaults to public-read.
 * @autoContentType Tries to determine content type of file by file extension. Defaults to false.
 * @autoMD5 Calculates MD5 hash of content automatically. Defaults to false.
 * @debug Used to turn debugging on or off outside of logbox. Defaults to false.
 *
 * @return An AmazonS3 instance.
 */
public AmazonS3 function init(
	required string accessKey,
	required string secretKey,
	string awsDomain = "amazonaws.com",
	string awsRegion = "us-east-1",
	string encryption_charset = "UTF-8",
	string signature = "V4",
	boolean ssl = true,
	string defaultTimeOut= 300,
	string defaultDelimiter='/',
	string defaultBucketName='',
	string defaultCacheControl= "no-store, no-cache, must-revalidate",
	string defaultStorageClass= "STANDARD",
	string defaultACL= "public-read",
	boolean autoContentType= false,
	boolean autoMD5= false,
	boolean debug= false
)
)

ColdBox Module

This package also is a ColdBox module as well. The module can be configured by creating an s3sdk configuration structure in your moduleSettings struct in the application configuration file: config/Coldbox.cfc with the following settings:

moduleSettings = {
	s3sdk = {
		// Your amazon, digital ocean access key
		accessKey = "",
		// Your amazon, digital ocean secret key
		secretKey = "",
		// The default encryption character set: defaults to utf-8
		encryption_charset = "utf-8",
		// The signature version to calculate, "V2" is deprecated but more compatible with other endpoints. "V4" requires Sv4Util.cfc & ESAPI on Lucee. Defaults to V4
		signature = "V4",
		// SSL mode or not on cfhttp calls: Defaults to true
		ssl = true,
		// Your AWS/Digital Ocean Domain Mapping: defaults to amazonaws.com
		awsDomain = "amazonaws.com",
		// Your AWS/Digital Ocean Region: Defaults to us-east-1
		awsregion = "us-east-1",
		// Default HTTP timeout for all requests. Defaults to 300.
		defaultTimeOut = 300,
		// The default delimiter for folder operations
		defaultDelimiter = "/",
		// The default bucket name to root the operations on.
		defaultBucketName = "",
		// Default caching policy for objects. Defaults to: no-store, no-cache, must-revalidate
		defaultCacheControl = "no-store, no-cache, must-revalidate",
		// Default storage class for objects that affects cost, access speed and durability. Defaults to STANDARD.
		defaultStorageClass = "STANDARD",
		// Default access control policy for objects and buckets. Defaults to public-read.
		defaultACL = "public-read",
		// Tries to determine content type of file by file extension. Defaults to false.
		autoContentType = false,
		// Calculates MD5 hash of content automatically. Defaults to false.
		autoMD5 = false
		// Used to turn debugging on or off outside of logbox. Defaults to false.
		debug = false
	}
};

Then you can leverage the SDK CFC via the injection DSL: [email protected]

Usage

Please check out the api docs: https://apidocs.ortussolutions.com/#/coldbox-modules/s3sdk/

Dependencies (0)


Dev Dependencies (0)


Changelog

v4.6.0

  • Improvements : Added more formatting
  • Task : Cleanup of old cfml engine files
  • Task : Cleanup of old init code
  • Task : Removed some settings from test harness

v4.5.0

  • Feature : SV4Util is now a singleton for added performance and more configuration expansion by adding the sdk reference
  • Improvement : Better error messages when s3 goes 💥
  • Bug : Fix for ACF double encoding

v4.4.0

  • Reworked SSL setup to allow for dynamic creation of the URL entry point
  • Removed ACF11 officially, it is impossible to deal with their cfhttp junk! It works, but at your own risk.

v4.3.0

  • Removal of debugging code

v4.2.1

  • Avoid double encoding on copy, putObjectFile, and delete() operations
  • Consolidate ssl to use variables instead of arguments

v4.2.0

  • ACF compatiblities
  • Fixes for auth on folder commands
  • New constructor args: defaultDelimiter for folder operations, defaultBucketname so you can set a default bucket for all bucket related operations.
  • Avoid nasty error on bucket deletion
  • Add new method objectExists() boolean check for objects
  • Fix URI encoding on signatures for headers and query params

v4.1.1

  • Left some dump/aborts

v4.1.0

  • DigitalOcean Spaces compatiblity
  • Region naming support, you can now pass the awsRegion argument to the constructor to select the AWS or DO region
  • SSL is now the default for all operations
  • Addition of two new constructor params: awsRegion and awsDomain to support regions and multi-domains for AWS and Digital Ocean
  • Added log debugging to calls and signatures if LogBox is on debug level

v4.0.1

  • Fixes to models location, oopsy!

v4.0.0

  • AWS Region Support
  • Migrated Module Layout to use Ortus Standard Module Layout
  • Added testing for all ACF Engines
  • Rework as generic Box module (compatibility change), you must move your s3sdk top level settings in ColdBox Config to moduleSettings.s3sdk
  • deleteBucket() returns false if bucket doesn't exist instead of throwing an exception
  • Few optimizations and documentation of the API

v3.0.1

  • Travis Updates and self-publishing

v3.0.0

  • Ugprade to ColdBox 4 standards
  • Upgrade to latest Amazon S3 SDK standards
  • Travis build process

v2.0

  • Original Spec as a ColdBox Plugin

 

$ box install s3sdk

No collaborators yet.
     
5.00 / 3
  • Nov 25 2009 03:34 AM
  • Mar 11 2020 06:07 PM
  • 13,115
  • 16,136
  • 9,346