s3_storage/vendor/akeeba/s3/src/Configuration.php

   1 <?php
   2 /**
   3  * Akeeba Engine
   4  *
   5  * @package   akeebaengine
   6  * @copyright Copyright (c)2006-2023 Nicholas K. Dionysopoulos / Akeeba Ltd
   7  * @license   GNU General Public License version 3, or later
   8  */
   9
  10 namespace Akeeba\S3;
  11
  12 // Protection against direct access
  13 defined('AKEEBAENGINE') || die();
  14
  15 /**
  16  * Holds the Amazon S3 confiugration credentials
  17  */
  18 class Configuration
  19 {
  20         /**
  21          * Access Key
  22          *
  23          * @var  string
  24          */
  25         protected $access = '';
  26
  27         /**
  28          * Secret Key
  29          *
  30          * @var  string
  31          */
  32         protected $secret = '';
  33
  34         /**
  35          * Security token. This is only required with temporary credentials provisioned by an EC2 instance.
  36          *
  37          * @var  string
  38          */
  39         protected $token = '';
  40
  41         /**
  42          * Signature calculation method ('v2' or 'v4')
  43          *
  44          * @var  string
  45          */
  46         protected $signatureMethod = 'v2';
  47
  48         /**
  49          * AWS region, used for v4 signatures
  50          *
  51          * @var  string
  52          */
  53         protected $region = 'us-east-1';
  54
  55         /**
  56          * Should I use SSL (HTTPS) to communicate to Amazon S3?
  57          *
  58          * @var  bool
  59          */
  60         protected $useSSL = true;
  61
  62         /**
  63          * Should I use SSL (HTTPS) to communicate to Amazon S3?
  64          *
  65          * @var  bool
  66          */
  67         protected $useDualstackUrl = false;
  68
  69         /**
  70          * Should I use legacy, path-style access to the bucket? When it's turned off (default) we use virtual hosting style
  71          * paths which are RECOMMENDED BY AMAZON per http://docs.aws.amazon.com/AmazonS3/latest/API/APIRest.html
  72          *
  73          * @var  bool
  74          */
  75         protected $useLegacyPathStyle = false;
  76
  77         /**
  78          * Amazon S3 endpoint. You can use a custom endpoint with v2 signatures to access third party services which offer
  79          * S3 compatibility, e.g. OwnCloud, Google Storage etc.
  80          *
  81          * @var  string
  82          */
  83         protected $endpoint = 's3.amazonaws.com';
  84
  85         /**
  86          * Public constructor
  87          *
  88          * @param   string  $access           Amazon S3 Access Key
  89          * @param   string  $secret           Amazon S3 Secret Key
  90          * @param   string  $signatureMethod  Signature method (v2 or v4)
  91          * @param   string  $region           Region, only required for v4 signatures
  92          */
  93         function __construct(string $access, string $secret, string $signatureMethod = 'v2', string $region = '')
  94         {
  95                 $this->setAccess($access);
  96                 $this->setSecret($secret);
  97                 $this->setSignatureMethod($signatureMethod);
  98                 $this->setRegion($region);
  99         }
 100
 101         /**
 102          * Get the Amazon access key
 103          *
 104          * @return  string
 105          */
 106         public function getAccess(): string
 107         {
 108                 return $this->access;
 109         }
 110
 111         /**
 112          * Set the Amazon access key
 113          *
 114          * @param   string  $access  The access key to set
 115          *
 116          * @throws  Exception\InvalidAccessKey
 117          */
 118         public function setAccess(string $access): void
 119         {
 120                 if (empty($access))
 121                 {
 122                         throw new Exception\InvalidAccessKey;
 123                 }
 124
 125                 $this->access = $access;
 126         }
 127
 128         /**
 129          * Get the Amazon secret key
 130          *
 131          * @return string
 132          */
 133         public function getSecret(): string
 134         {
 135                 return $this->secret;
 136         }
 137
 138         /**
 139          * Set the Amazon secret key
 140          *
 141          * @param   string  $secret  The secret key to set
 142          *
 143          * @throws  Exception\InvalidSecretKey
 144          */
 145         public function setSecret(string $secret): void
 146         {
 147                 if (empty($secret))
 148                 {
 149                         throw new Exception\InvalidSecretKey;
 150                 }
 151
 152                 $this->secret = $secret;
 153         }
 154
 155         /**
 156          * Return the security token. Only for temporary credentials provisioned through an EC2 instance.
 157          *
 158          * @return  string
 159          */
 160         public function getToken(): string
 161         {
 162                 return $this->token;
 163         }
 164
 165         /**
 166          * Set the security token. Only for temporary credentials provisioned through an EC2 instance.
 167          *
 168          * @param   string  $token
 169          */
 170         public function setToken(string $token): void
 171         {
 172                 $this->token = $token;
 173         }
 174
 175         /**
 176          * Get the signature method to use
 177          *
 178          * @return  string
 179          */
 180         public function getSignatureMethod(): string
 181         {
 182                 return $this->signatureMethod;
 183         }
 184
 185         /**
 186          * Set the signature method to use
 187          *
 188          * @param   string  $signatureMethod  One of v2 or v4
 189          *
 190          * @throws  Exception\InvalidSignatureMethod
 191          */
 192         public function setSignatureMethod(string $signatureMethod): void
 193         {
 194                 $signatureMethod = strtolower($signatureMethod);
 195                 $signatureMethod = trim($signatureMethod);
 196
 197                 if (!in_array($signatureMethod, ['v2', 'v4']))
 198                 {
 199                         throw new Exception\InvalidSignatureMethod;
 200                 }
 201
 202                 $this->signatureMethod = $signatureMethod;
 203
 204                 // If you switch to v2 signatures we unset the region.
 205                 if ($signatureMethod == 'v2')
 206                 {
 207                         $this->setRegion('');
 208
 209                         /**
 210                          * If we are using Amazon S3 proper (not a custom endpoint) we have to set path style access to false.
 211                          * Amazon S3 does not support v2 signatures with path style access at all (it returns an error telling
 212                          * us to use the virtual hosting endpoint BUCKETNAME.s3.amazonaws.com).
 213                          */
 214                         if (strpos($this->endpoint, 'amazonaws.com') !== false)
 215                         {
 216                                 $this->setUseLegacyPathStyle(false);
 217                         }
 218
 219                 }
 220         }
 221
 222         /**
 223          * Get the Amazon S3 region
 224          *
 225          * @return  string
 226          */
 227         public function getRegion(): string
 228         {
 229                 return $this->region;
 230         }
 231
 232         /**
 233          * Set the Amazon S3 region
 234          *
 235          * @param   string  $region
 236          */
 237         public function setRegion(string $region): void
 238         {
 239                 /**
 240                  * You can only leave the region empty if you're using v2 signatures. Anything else gets you an exception.
 241                  */
 242                 if (empty($region) && ($this->signatureMethod == 'v4'))
 243                 {
 244                         throw new Exception\InvalidRegion;
 245                 }
 246
 247                 /**
 248                  * Setting a Chinese-looking region force-changes the endpoint but ONLY if you were using the original Amazon S3
 249                  * endpoint. If you're using a custom endpoint and provide a region with 'cn-' in its name we don't override
 250                  * your custom endpoint.
 251                  */
 252                 if (($this->endpoint == 's3.amazonaws.com') && (substr($region, 0, 3) == 'cn-'))
 253                 {
 254                         $this->setEndpoint('amazonaws.com.cn');
 255                 }
 256
 257                 $this->region = $region;
 258         }
 259
 260         /**
 261          * Is the connection to be made over HTTPS?
 262          *
 263          * @return  bool
 264          */
 265         public function isSSL(): bool
 266         {
 267                 return $this->useSSL;
 268         }
 269
 270         /**
 271          * Set the connection SSL preference
 272          *
 273          * @param   bool  $useSSL  True to use HTTPS
 274          */
 275         public function setSSL(bool $useSSL): void
 276         {
 277                 $this->useSSL = $useSSL ? true : false;
 278         }
 279
 280         /**
 281          * Get the Amazon S3 endpoint
 282          *
 283          * @return  string
 284          */
 285         public function getEndpoint(): string
 286         {
 287                 return $this->endpoint;
 288         }
 289
 290         /**
 291          * Set the Amazon S3 endpoint. Do NOT use a protocol
 292          *
 293          * @param   string  $endpoint  Custom endpoint, e.g. 's3.example.com' or 'www.example.com/s3api'
 294          */
 295         public function setEndpoint(string $endpoint): void
 296         {
 297                 if (stristr($endpoint, '://'))
 298                 {
 299                         throw new Exception\InvalidEndpoint;
 300                 }
 301
 302                 /**
 303                  * If you set a custom endpoint we have to switch to v2 signatures since our v4 implementation only supports
 304                  * Amazon endpoints.
 305                  */
 306                 if ((strpos($endpoint, 'amazonaws.com') === false))
 307                 {
 308                         $this->setSignatureMethod('v2');
 309                 }
 310
 311                 $this->endpoint = $endpoint;
 312         }
 313
 314         /**
 315          * Should I use legacy, path-style access to the bucket? You should only use it with custom endpoints. Amazon itself
 316          * is currently deprecating support for path-style access but has extended the migration date to an unknown
 317          * time https://aws.amazon.com/blogs/aws/amazon-s3-path-deprecation-plan-the-rest-of-the-story/
 318          *
 319          * @return  bool
 320          */
 321         public function getUseLegacyPathStyle(): bool
 322         {
 323                 return $this->useLegacyPathStyle;
 324         }
 325
 326         /**
 327          * Set the flag for using legacy, path-style access to the bucket
 328          *
 329          * @param   bool  $useLegacyPathStyle
 330          */
 331         public function setUseLegacyPathStyle(bool $useLegacyPathStyle): void
 332         {
 333                 $this->useLegacyPathStyle = $useLegacyPathStyle;
 334
 335                 /**
 336                  * If we are using Amazon S3 proper (not a custom endpoint) we have to set path style access to false.
 337                  * Amazon S3 does not support v2 signatures with path style access at all (it returns an error telling
 338                  * us to use the virtual hosting endpoint BUCKETNAME.s3.amazonaws.com).
 339                  */
 340                 if ((strpos($this->endpoint, 'amazonaws.com') !== false) && ($this->signatureMethod == 'v2'))
 341                 {
 342                         $this->useLegacyPathStyle = false;
 343                 }
 344         }
 345
 346         /**
 347          * Should we use the dualstack URL (which will ship traffic over ipv6 in most cases). For more information on these
 348          * endpoints please read https://docs.aws.amazon.com/AmazonS3/latest/dev/dual-stack-endpoints.html
 349          *
 350          * @return  bool
 351          */
 352         public function getDualstackUrl(): bool
 353         {
 354                 return $this->useDualstackUrl;
 355         }
 356
 357         /**
 358          * Set the flag for using legacy, path-style access to the bucket
 359          *
 360          * @param   bool  $useDualstackUrl
 361          */
 362         public function setUseDualstackUrl(bool $useDualstackUrl): void
 363         {
 364                 $this->useDualstackUrl = $useDualstackUrl;
 365         }
 366 }