Documentation without using Composer about s3

[nikosdion]

It's funny that you mention the AWS SDK as a counter-example of requirements overload because, er, it's the very example of bloat! It is a massive mega-library for all AWS features and uses a rather old version of Guzzle with a bazillion of dependencies. The Phar file is just what you'd get through Composer, all packed in one file. With all the code that their SDK isn't using. Yup. It's bloated as cardinal sin and then some. This is the reason I wrote this small library here. Not to mention that a library shipping as a Phar archive is the antithesis of practical for commercial hosting (it's OK when you run your own server but it's misguided to think that you can do better server security in your spare time than what a dedicated team does full time; of course there are people who'd rather spend $5 per month on a thoroughly hacked server they manage rather than $10 per month on a decent shared host that won't be hacked but I have finally learned not to try and fix stupid anymore since practical ways to do that are not legal and legal ways to do that are not practical).

I don't just hate bloat, I can't afford bloat. Most of my software is very popular extensions / plugins for other CMS such as Joomla and WordPress. Bundling a 16MB megadependency with a 2MB plugin increases my Amazon CloudFront CDN costs by 800%. We're talking hundreds of thousands of downloads per version and that makes a horrific difference in business sustainability. Not to mention that an 18MB package won't be installable on most commercial hosts with an upload limit typically in the 4MB to 10MB range. That would increase my support costs, shutting me down.

Hence what I need is...

MAXIMUM EFFORT! Writing my own library is hard but it costs me a tiny fraction of the alternative. As long as I keep it teensy tiny.

The only thing I am pulling in when you install it through Composer is... nothing. Really! Check it out for yourself :D The only thing besides my code is Composer's auto-included PSR-0 and PSR-4 autoloader and the auto-generated map file for said autoloader. That's, dunno, another 20KB or so?

Regarding writing your own autoloader, I already linked you to the source of the PSR-4 reference autoloader. But, there's no need to go there. Installing my S3 library through Composer is lightweight and far easier.

Remember. Composer and NPM by themselves are not bad. It's people abusing them to pull in a bazillion dependencies they don't really need that screws it up. I've been using computers since when a 360KB disk was all you got. My first sites, back in the late 90s, had to be loaded in a reasonable amount of time (back then: 10 seconds or less) over a 56Kbps modem. These are the practical restrictions that shaped my approach to using and programming computers. When I say that I keep bloat to an absolute minimum you'd better believe it :)

[ryandemmer]

I'm going to jump in here and say that if you are using this excellent S3 library in a Joomla extension, you can just add this to the file using the library (set your own path to where the S3 library is in place of 'path/to/akeeba') :

// define constant for Akeeba files
define('AKEEBAENGINE', 1);

// define cacert.pem path
define('AKEEBA_CACERT_PEM', JPATH_LIBRARIES . '/src/Http/Transport/cacert.pem');

// register Akeeba namespaces
JLoader::registerNamespace('Akeeba\\Engine\\Postproc\\Connector\\S3v4', 'path/to/akeeba', false, false, 'psr4');

Thank you Nicholas!

[nikosdion]

All of your points are readily answered in the composer.json and README.md files.

This is a self-contained solution. It has no external dependencies. You of course need all of the files for it to work. What do you think, we put unnecessary code files in the repo just because? Asking which files to include makes zero sense.

Cross-including .php files or doing a massive block of require_once to consume a library is a method that's error prone and long dead (since PHP 5.0 to be exact). I made that mistake back in 2006 when I needed to support PHP 4 and it took me 5 long, gruelling years to address it. If you're not using Composer you need to provide your own PSR-4 autoloader for its namespace (Akeeba\Engine\Postproc\Connector\S3v4). At the very least you could use a variation of the reference PSR-4 autoloader.

Regarding Phar files, your article is talking about packaging entire standalone applications, not libraries. Considering that you're talking to the guy who wrote and maintains Akeeba Remote CLI and Akeeba UNiTE (both delivered as Phar archives) I'd say that your reference is misguided. If it'd make sense I would indeed deliver it as a Phar archive.

Delivering libraries as Phar archives it's something I have talked about, most recently in J and Beyond 2017 in the context of digitally signing sensitive source files. Unfortunately, many commercial hosts outright prohibit you from using Phar files. There are also some finer points about Phar files regarding how to best organize their contents, their visibility in IDEs (thankfully changing to the better) and their performance impact on an application. Dependency management is also a big issue. At the time of this writing it makes far more sense using Composer to deliver a library than a Phar file and I don't see that changing in the immediate future.

[Ben-CA]

No worries - you obviously have reasons and have thought this through.

I dislike Composer (and NPM and the like), partly because it often results in lazy programming and including a zillion dependancies which in turn have tendencies to introduce additional security vulnerabilities, etc. and make for a bloated application. You end up packaging an application that's 200MB that should be 2MB.

The reason I mention .phar is that the AWS PHP SDK offers that, but it's like 16MB (because of all the dependancies), which I didn't want to include in my application for just a few S3 functions.

I liked the look of your source code, because it's not bloated and doesn't have other dependancies, but I'm not sure that I'm smart enough to develop my own PSR-4 autoloader.

[Ben-CA]

Sounds like we agree. The AWS PHP SDK is incredibly bloated. Bloat is bad for multiple reasons. (I also used to save files on floppy disks back on the 90's - and vaguely remember internet on a 14.4K modem. My early websites also had to function on slow dial-up connections.)

And I use managed hosting for websites and mostly-managed AWS Elastic Beanstalk and RDS for more business critical applications - I figure the AWS teams can keep systems patched and upgraded better than I can. (Even if they apparently don't mind bloat!)

Perhaps I should be using Composer, but just severely limit what I allow myself to use it for... ;)

[nikosdion]

@Ben-CA My first Internet experience was also on a 14.4Kbps modem, bought with painstaking savings circa 1994. I didn't have a computer with a hard disk until 1997 -- I basically spent the 90s juggling disks. 1.44MB disks were hot stuff, especially when you formatted them as 1.7MB (as long as you didn't mind storing only a couple of big files). Ah, the good old days, when booting a computer took long enough to change from street clothes to house clothes, make a coffee and read a magazine or two :D

@ryandemmer Thank you, I appreciate your kind words! Good thing you mentioned the AKEEBA_CACERT_PEM constant, I think I never included that in the README.

[ryandemmer]

@nikosdion - Yours is the only slimmed down PHP library available for S3! It is very much appreciated!

Now, what about your Azure library? Any chance of putting that on github? ;)

[Ben-CA]

@nikosdion - I also appreciate you making this available; although I'm still trying to get it working.

I installed it using Composer (only adds about 300KB to my project), with the following composer.json:

{
    "require": {
        "akeeba/s3": "*"
    },
    "minimum-stability": "dev"
}

Ran "composer install" on the folder, and now I have the vendor folder with it's contents:

And then from a PHP file in the same parent folder as the vendors folder, I'm trying to use the code (just as a test to list my buckets):

// define constant for Akeeba files
define('AKEEBAENGINE', 1);

require('vendor/autoload.php');

use akeeba\s3;

$AWSRegion = 'ca-central-1';
$role = file_get_contents('http://169.254.169.254/latest/meta-data/iam/security-credentials/');
$jsonCredentials = file_get_contents('http://169.254.169.254/latest/meta-data/iam/security-credentials/' . $role);
$credentials = json_decode($jsonCredentials, true);
$configuration = new Configuration(
	$credentials['AccessKeyId'],
	$credentials['SecretAccessKey'],
	'v4',
	$AWSRegion
);
$configuration->setToken($credentials['Token']);

$connector = new Connector($configuration);

$listing = $connector->listBuckets(true);

print_r($listing);

But I just get this error when I run it:

Fatal error: Uncaught Error: Class 'Configuration' not found in /var/app/current/.........

Probably something simple I'm overlooking...

[ryandemmer]

use akeeba\s3;

This should be

use Akeeba\Engine\Postproc\Connector\S3v4\Configuration;
use Akeeba\Engine\Postproc\Connector\S3v4\Connector;

[Ben-CA]

Thanks @nikosdion ! That did it!

Now I'm getting:
Fatal error: Uncaught Akeeba\Engine\Postproc\Connector\S3v4\Exception\CannotListBuckets: Akeeba\Engine\Postproc\Connector\S3v4\Connector::listBuckets(): [0] Access Denied

But I think this will just be an AWS permission I need to adjust.

[ryandemmer]

You need to configure permissions for the bucket.

An example of the IAM permissions you will need for filesystem operations is:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "akeeba-aws-s3-1",
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetObject",
                "s3:GetObjectAcl",
                "s3:PutObject",
                "s3:PutObjectAcl",
                "s3:DeleteObject"
            ],
            "Resource": [
                "arn:aws:s3:::your-bucket-name",
                "arn:aws:s3:::your-bucket-name/*"
            ]
        }
    ]
}

[ryandemmer]

See - https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html

[Ben-CA]

Thanks @ryandemmer , I got it working, so now it lists my buckets. Now I can play around with it and see if I can make it do something useful. :)

[nikosdion]

@ryandemmer Send me an email about the Azure code. I need to ask you a few things before deciding on it :)