<?php

//Display the contents of the read me file
function _aws_s3_getting_started() {

  $adminUI = [];
  $adminUI['PAGE_TITLE'] = [
    t("Plugins")            => '?menu=admin&action=plugins',
    t("AWNS S3") => '?_pluginAction=_aws_s3_getting_started',
  ];

  // content
  $adminUI['CONTENT'] = '';
  
  $adminUI['CONTENT']  = "";
  $adminUI['CONTENT'] .= ob_capture(function() {
    //_mab_menu_header("App Certificates");
  ?>

    <?php echo adminUI_separator(t('Plugin Settings')); ?>

    <p>NOTE: plugin authentication information is stored in the plugin file "auth_details.php"</p>
    <p>You must rename the auth_details_SAMPLE.php file to auth_details.php and update its details</p>
    <p>See the notes under HOW TO USE below for more information whether or not to provide our copy of SSL Certificate Authority Root Certificates (in case server/OS doesn't already have them setup)</p>
    <p>if you get an "AWS S3: Error authenticating: Unknown AWS Error!", try setting this to true:</p>
    <pre>$GLOBALS['AWS_S3_PROVIDE_CACERT'] = true;</pre>

    <p>turning this off is not recommended!</p>
    <pre>$GLOBALS['AWS_S3_SKIP_AUTH_ERROR_CHECKING'] = false;"</pre>


    <?php echo adminUI_separator(t('What Is S3')); ?>


    <p>Amazon Web Service's S3 stands for "Simple Storage Service". It's a relatively simple way to store and retrieve arbitrarily-sized files in the cloud with reasonable availability (3-4 nines), great dependability (11 nines), low bandwidth costs, and reasonably fast access times. Due to its web interface and the ability to grant read-only permission to anonymous users, it also doubles as a static web hosting platform.</p>

    <p>S3's storage is partitioned into buckets, each with a (globally) unique name. Developers create their own buckets and do not have access to others' buckets. Files (aka "objects") are uploaded ("put") into a bucket using a user-specified "key". It's recommended to treat keys as filepaths, using slashes ("/") to organize files into "directories". The file's bucket and key correspond to its URL (e.g. https://s3-us-west-2.amazonaws.com/mybucketname/mykeyname). Files can be listed in alphabetical order, and a key prefix can be specified, meaning that it's easy to list the (recursive) contents of a "directory". Uploading ("put"ting) a file with the same key as an existing file will overwrite it. It's also possible to delete files. AWS has a web interface for exploring the contents of a bucket.</p>

    <p>More info on S3: <a href="https://aws.amazon.com/s3/faqs/" >https://aws.amazon.com/s3/faqs/</a></p>


    <?php echo adminUI_separator(t('HOW TO USE THIS PLUGIN')); ?>

    <ul>
      <li>Requires PHP 5.5 for Amazon S3 SDK</li>
      <li>Rename the auth_details_SAMPLE.php file to auth_details.php and record details in it as you accumulate them below</li>
      <li>In your AWS control panel, create an "IAM User" with access to read and write to your S3 buckets</li>
      <ul>
        <li>Security & Identity > Identity & Access Management (IAM)</li>
        <li>Create an IAM User, record the "key" and "secret" in the auth_details.php file</li>
        <li>Enter an email address in the auth_details.php file to represent this account (pick any email you like, this value is for your own reference)</li>
        <li>Create an IAM Group, enable write permissions for s3, add the IAM User to the IAM Group</li>
      </ul>
      <li>In your AWS control panel, create an S3 bucket</li>
      <ul>
        <li>Storage & Content Delivery > S3</li>
        <li>You can choose the "region" when creating a bucket (you should choose a region close to your intended audience)</li>
        <li>Enter the bucket name and region into the auth_details.php file</li>
        <ul>
          <li>Look up the Region (code) here: https://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region</li>
        </ul>
      </ul>
      <li>Grant read-only permission to anonymous users:</li>
      <ul>
        <li>In your bucket Properties, under Permissions, click the "Add bucket policy" button</li>
        <li>The policy dialog will appear with an empty text area</li>
        <li>Copy the example policy and customize it with your bucket's name</li>
        <ul>
          <li>Click the "Sample Bucket Policies" link on the policy dialog and find the "Granting Read-Only Permission to an Anonymous User" example</li>
          <ul>
            <li>Direct link: https://docs.aws.amazon.com/AmazonS3/latest/dev/example-bucket-policies.html#example-bucket-policies-use-case-2</li>
          </ul>
          <li>A copy of the example policy is provided below:<br>
            <pre>
              {
                "Version":"2012-10-17",
                "Statement":[
                  {
                    "Sid":"AddPerm",
                    "Effect":"Allow",
                    "Principal": "*",
                    "Action":["s3:GetObject"],
                    "Resource":["arn:aws:s3:::examplebucket/*"]
                  }
                ]
              }'
            </pre>
          </li>
          <ul>
            <li>Copy the policy, paste it into your bucket's policy</li>
            <li>IMPORTANT: Change "examplebucket" in the policy to your bucket's name!</li>
            <li>Click the Save button</li>
          </ul>
          <li>If the example policy above can't be found or does not work, you can use the AWS Policy Generator</li>
          <ul>
            <li>Click the AWS Policy Generator in the policy dialog</li>
            <li>The Policy Generator page will open in a new tab</li>
            <li>
              Enter the following information:<br>
              <pre>
                Select Type of Policy:       S3 Bucket Policy
                Effect:                      Allow
                Principal:                   *
                Actions:                     GetObject
                Amazon Resource Name (ARN):  arn:aws:s3:::examplebucket
              </pre>
            </li>
            <li>You must change "examplebucket" in the ARN to your bucket's name</li>
            <li>Click Add Statement</li>
            <li>Click Generate Policy</li>
            <li>Copy the policy, close the tab, and paste it into your bucket's policy</li>
            <li>Click the Save button</li>
          </ul>
        </ul>
      </ul>
    </ul>


    <?php echo adminUI_separator(t('API OVERVIEW')); ?>

    <pre>
      aws_s3_put
      ----------
      $url = aws_s3_put('key', 'text/html', 'Hello world!');

      aws_s3_get
      ----------
      list($content, $contentType) = aws_s3_get('key');

      aws_s3_get_saveToFile
      ---------------------
      aws_s3_get_saveToFile('key', 'tmp/filepath.png');

      aws_s3_delete
      -------------
      aws_s3_delete('key');

      aws_s3_deleteMultiple
      ---------------------
      aws_s3_deleteMultiple(['key1', 'key2']);

      aws_s3_exists
      ----------------------
      $keyExists = aws_s3_exists('key');

      aws_s3_list
      -----------
      $rows = aws_s3_list('testing/'); // return all(!) objects with a prefix of 'testing/'
      $rows = aws_s3_list('', 5000);   // return 5000 rows max

      aws_s3_listPage
      ---------------
      list($rows, $nextPageKey) = aws_s3_listPage('testing/'); // returns 1000 rows max
    </pre>

    <?php
  });
  adminUI($adminUI);
  exit;
}

// eof