# Getting started with the AWS SDK for PHP Version 3 This chapter is dedicated to getting you up and running with the AWS SDK for PHP Version 3. **Topics** + [Prerequisites](getting-started_requirements.md) + [Installing](getting-started_installation.md) + [Authenticating with AWS](credentials.md) + [Creating a simple application](hello.md) + [Use AWS Cloud9 with the SDK](cloud9.md) # Requirements and recommendations for the AWS SDK for PHP Version 3 For best results with AWS SDK for PHP, ensure your environment supports the following requirements and recommendations. ## Requirements To use the AWS SDK for PHP, you must be using PHP version 8.1 or later with the [SimpleXML PHP extension](https://www.php.net/manual/en/book.simplexml.php) enabled. If you need to sign private Amazon CloudFront URLs, you also need the [OpenSSL PHP extension](http://php.net/manual/en/book.openssl.php). ## Recommendations In addition to the minimum requirements, we recommend you also install, uninstall, and use the following. **** | | | | --- |--- | | Install [cURL](http://php.net/manual/en/book.curl.php) 7.16.2 or later | Use a recent version of cURL compiled with OpenSSL/NSS and zlib. If cURL isn’t installed on your system and you don’t configure a custom http\$1handler for your client, the SDK uses the PHP stream wrapper. | | Use [OPCache](http://php.net/manual/en/book.opcache.php) | Use the OPcache extension to improve PHP performance by storing precompiled script bytecode in shared memory. This removes the need for PHP to load and parse scripts on each request. This extension is typically enabled by default. When running Amazon Linux, you need to install the php56-opcache or php55-opcache yum package to use the OPCache extension. | | Uninstall [Xdebug](http://xdebug.org/) in production environments | Xdebug can help identify performance bottlenecks. However, if performance is critical to your application, don’t install the Xdebug extension in your production environment. Loading the extension slows SDK performance considerably. | | Use a [Composer](http://getcomposer.org) classmap autoloader | Autoloaders load classes as they are required by a PHP script. Composer generates an autoloader that can autoload the PHP scripts of your application and all other PHP scripts required by your application, including the AWS SDK for PHP. For production environments, we recommended you use a classmap autoloader to improve autoloader performance. You can generate a classmap autoloader by passing the `-o` or `==optimize-autoloader` option to Composer’s install command. | ## Compatibility test Run the [https://github.com/aws/aws-sdk-php/blob/master/compatibility-test.php](https://github.com/aws/aws-sdk-php/blob/master/compatibility-test.php) file located in the SDK code base to verify your system can run the SDK. In addition to meeting the SDK’s minimum system requirements, the compatibility test checks for optional settings and makes recommendations that can help improve performance. The compatibility test outputs results either to the command line or a web browser. When reviewing test results in a browser, successful checks appear in green, warnings in purple, and failures in red. When running from the command line, the result of a check appears on a separate line. When reporting an issue with the SDK, sharing the output of the compatibility test helps identify the underlying cause. # Installing the AWS SDK for PHP Version 3 You can install the AWS SDK for PHP Version 3: + As a dependency via Composer + As a prepackaged phar of the SDK + As a ZIP file of the SDK Before you install AWS SDK for PHP Version 3 ensure your environment is using PHP version 8.1 or later. Learn more about [environment requirements and recommendations](getting-started_requirements.md). **Note** Installing the SDK via the .phar and .zip methods requires the [Multibyte String PHP extension](https://www.php.net/manual/en/book.mbstring.php) to be installed and enabled separately. ## Install AWS SDK for PHP as a dependency via Composer Composer is the recommended way to install the AWS SDK for PHP. Composer is a tool for PHP that manages and installs the dependencies of your project. For more information on how to install Composer, configure autoloading, and follow other best practices for defining dependencies, see [getcomposer.org](http://getcomposer.org). ### Install Composer If Composer is not already in your project, download and install Composer on the [Download Composer page](http://getcomposer.org/download). + For **Windows**, follow the Windows Installer instructions. + For **Linux**, follow the Command-line installation instructions. ### Add AWS SDK for PHP as a dependency via Composer If [Composer is already installed globally](https://getcomposer.org/doc/00-intro.md#globally) on your system, run the following in the base directory of your project to install AWS SDK for PHP as a dependency: ``` $ composer require aws/aws-sdk-php ``` Otherwise, type this Composer command to install the latest version of the AWS SDK for PHP as a dependency. ``` $ php -d memory_limit=-1 composer.phar require aws/aws-sdk-php ``` ### Add autoloader to your php scripts Installing Composer creates several folders and files in your environment. The primary file you will use is `autoload.php`, which is in the `vendor` folder in your environment. To utilize the AWS SDK for PHP in your scripts, include the autoloader in your scripts, as follows. ``` ``` ## Installing by using the packaged phar Each release of the AWS SDK for PHP includes a prepackaged phar (PHP archive) that contains all the classes and dependencies you need to run the SDK. Additionally, the phar automatically registers a class autoloader for the AWS SDK for PHP and all its dependencies. You can [download the packaged phar](https://docs.aws.amazon.com/aws-sdk-php/v3/download/aws.phar) and include it in your scripts. ``` ``` **Note** Using PHP with the Suhosin patch is not recommended, but is common on Ubuntu and Debian distributions. In this case, you might need to enable the use of phars in the suhosin.ini. If you don’t do this, including a phar file in your code will cause a silent failure. To modify suhosin.ini, add the following line. ``` suhosin.executor.include.whitelist = phar ``` ## Installing by using the ZIP file The AWS SDK for PHP includes a ZIP file containing all the classes and dependencies you need to run the SDK. Additionally, the ZIP file includes a class autoloader for the AWS SDK for PHP and its dependencies. To install the SDK, [download the .zip file](https://docs.aws.amazon.com/aws-sdk-php/v3/download/aws.zip), and then extract it into your project at a location you choose. Then include the autoloader in your scripts, as follows. ``` ``` # Authenticating with AWS using AWS SDK for PHP Version 3 You must establish how your code authenticates with AWS when developing with AWS services. You can configure programmatic access to AWS resources in different ways depending on the environment and the AWS access available to you. To choose your method of authentication and configure it for the SDK, see [Authentication and access](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) in the *AWS SDKs and Tools Reference Guide*. ## Set up authentication with IAM Identity Center for local development We recommend that new users who are developing locally and are not given a method of authentication by their employer should set up AWS IAM Identity Center. This method includes installing the AWS CLI for ease of configuration and for regularly signing in to the AWS access portal. If you choose this method, your environment should contain the following elements after you complete the procedure for [IAM Identity Center authentication](https://docs.aws.amazon.com/sdkref/latest/guide/access-sso.html) in the *AWS SDKs and Tools Reference Guide*: + The AWS CLI, which you use to start an AWS access portal session before you run your application. + A [shared AWS`config` file](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) that has a `[default]` profile with a set of configuration values that can be referenced by the SDK. To find the location of this file, see [Location of the shared files](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html) in the *AWS SDKs and Tools Reference Guide*. + The shared `config` file contains the [https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html](https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html) setting. This sets the default AWS Region that the SDK uses for requests. This Region is used for SDK service requests that aren't explicitly configured with a `region` property. + The SDK uses the profile's [SSO token provider configuration](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sso-credentials.html#feature-sso-credentials-profile) to acquire credentials before sending requests to AWS. The `sso_role_name` value, which is an IAM role connected to an IAM Identity Center permission set, allows access to the AWS services used in your application. The following sample `config` file shows a default profile set up with SSO token provider configuration. The profile's `sso_session` setting refers to the named [`sso-session` section](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#section-session). The `sso-session` section contains settings to initiate an AWS access portal session. ``` [default] sso_session = my-sso sso_account_id = 111122223333 sso_role_name = SampleRole region = us-east-1 output = json [sso-session my-sso] sso_region = us-east-1 sso_start_url = https://provided-domain.awsapps.com/start sso_registration_scopes = sso:account:access ``` The AWS SDK for PHP does not need additional packages (such as `SSO` and `SSOOIDC`) to be added to your application to use IAM Identity Center authentication. ## Start an AWS access portal session Before running an application that accesses AWS services, you need an active AWS access portal session for the SDK to use IAM Identity Center authentication to resolve credentials. Depending on your configured session lengths, your access will eventually expire and the SDK will encounter an authentication error. To sign in to the AWS access portal, run the following command in the AWS CLI. ``` aws sso login ``` If you followed the guidance and have a default profile setup, you do not need to call the command with a `--profile` option. If your SSO token provider configuration is using a named profile, the command is `aws sso login --profile named-profile`. To optionally test if you already have an active session, run the following AWS CLI command. ``` aws sts get-caller-identity ``` If your session is active, the response to this command reports the IAM Identity Center account and permission set configured in the shared `config` file. **Note** If you already have an active AWS access portal session and run `aws sso login`, you will not be required to provide credentials. The sign-in process might prompt you to allow the AWS CLI access to your data. Because the AWS CLI is built on top of the SDK for Python, permission messages might contain variations of the `botocore` name. ## Learn more about authentication + For more details about using IAM Identity Center for authentication, see [Understand IAM Identity Center authentication](https://docs.aws.amazon.com/sdkref/latest/guide/understanding-sso.html) in the *AWS SDKs and Tools Reference Guide* + To learn more about best practices, see [Security best practices in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*. + To create short-term AWS credentials, see [Temporary Security Credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html) in the *IAM User Guide*. + To learn about other credential providers that AWS SDK for PHP can use, see [Standardized credential providers](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html) in the *AWS SDKs and Tools Reference Guide*. # Creating a simple application using the AWS SDK for PHP Version 3 Say hello to Amazon S3 using the AWS SDK for PHP. The following example displays a list of your Amazon S3 buckets. ## Prerequisites + [Download and install the SDK](getting-started_installation.md) + Before you use the AWS SDK for PHP, you must set up authentication with AWS. For information about setting up authentication, see [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md) ## Including the SDK in your code No matter which technique you used to install the SDK, you can include the SDK in your code with just a single `require` statement. See the following table for the PHP code that best fits your installation technique. Replace any instances of `/path/to/` with the actual path on your system. **** | Installation Technique | Require Statement | | --- | --- | | Using Composer | `require '/path/to/vendor/autoload.php';` | | Using the phar | `require '/path/to/aws.phar';` | | Using the ZIP | `require '/path/to/aws-autoloader.php';` | In this topic, we assume the Composer installation method. If you’re using a different installation method, you can refer back to this section to find the correct `require` code to use. ## Write the code Make sure you can authenticate. Copy and paste the following code into a new source file. Save and name the file `hello-s3.php`. ``` 'default', 'region' => 'us-west-2', 'version' => '2006-03-01' ]); //Listing all S3 Bucket $buckets = $s3Client->listBuckets(); foreach ($buckets['Buckets'] as $bucket) { echo $bucket['Name'] . "\n"; } ``` ## Running the program Open a command prompt to run your PHP program. The typical command syntax to run a PHP program is: ``` php [source filename] [arguments...] ``` This sample code uses no arguments. To run this code, enter the following into the command prompt: ``` $ php hello-s3.php ``` ## Next steps To test out many other Amazon S3 operations, check out the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/php/example_code/s3) on GitHub. # Use AWS Cloud9 with the AWS SDK for PHP Version 3 **Note** AWS Cloud9 is no longer available to new customers. Existing customers of AWS Cloud9 can continue to use the service as normal. [Learn more](https://aws.amazon.com/blogs/devops/how-to-migrate-from-aws-cloud9-to-aws-ide-toolkits-or-aws-cloudshell/). AWS Cloud9 is a web-based integrated development environment (IDE) that contains a collection of tools that you use to code, build, run, test, debug, and release software in the cloud. You can use AWS Cloud9 with the AWS SDK for PHP to write and run your PHP code by using a browser. AWS Cloud9 includes tools such as a code editor and terminal. Because the AWS Cloud9 IDE is cloud based, you can work on your projects from your office, home, or anywhere by using an internet-connected machine. For general information about AWS Cloud9, see the [AWS Cloud9 User Guide](https://docs.aws.amazon.com/cloud9/latest/user-guide/welcome.html). Follow these instructions to set up AWS Cloud9 with the AWS SDK for PHP: + [Step 1: Set up your AWS account to use AWS Cloud9](#cloud9-php-account) + [Step 2: Set up your AWS Cloud9 development environment](#cloud9-php-environment) + [Step 3: Set up the AWS SDK for PHP](#cloud9-php-sdk) + [Step 4: Download example code](#cloud9-php-examples) + [Step 5: Run example code](#cloud9-php-run) ## Step 1: Set up your AWS account to use AWS Cloud9 To use AWS Cloud9, sign in to the AWS Cloud9 console from the AWS Management Console. **Note** If you are using AWS IAM Identity Center to authenticate, you might need to add the required permission of `iam:ListInstanceProfilesForRole` to the user-attached policy in the IAM console. To set up an IAM entity in your AWS account to access AWS Cloud9 and sign in to the AWS Cloud9 console, see [Team Setup for AWS Cloud9](https://docs.aws.amazon.com/cloud9/latest/user-guide/setup.html) in the *AWS Cloud9 User Guide*. ## Step 2: Set up your AWS Cloud9 development environment After you sign in to the AWS Cloud9 console, use the console to create an AWS Cloud9 development environment. After you create the environment, AWS Cloud9 opens the IDE for that environment. For details, see [Creating an Environment in AWS Cloud9](https://docs.aws.amazon.com/cloud9/latest/user-guide/create-environment.html) in the *AWS Cloud9 User Guide*. **Note** As you create your environment in the console for the first time, we recommend that you choose the option to **Create a new instance for environment (EC2)**. This option tells AWS Cloud9 to create an environment, launch an Amazon EC2 instance, and then connect the new instance to the new environment. This is the fastest way to begin using AWS Cloud9. If the terminal isn’t already open in the IDE, open it. On the menu bar in the IDE, choose **Window, New Terminal**. You can use the terminal window to install tools and build your applications. ## Step 3: Set up the AWS SDK for PHP After AWS Cloud9 opens the IDE for your development environment, use the terminal window to set up the AWS SDK for PHP in your environment. Composer is the recommended way to install the AWS SDK for PHP. Composer is a tool for PHP that manages and installs the dependencies of your project. For more information on how to install Composer, configure autoloading, and follow other best practices for defining dependencies, see [getcomposer.org](http://getcomposer.org). ### Install Composer If Composer is not already in your project, download and install Composer on the [Download Composer page](http://getcomposer.org/download). + For **Windows**, follow the Windows Installer instructions. + For **Linux**, follow the Command-line installation instructions. ### Add AWS SDK for PHP as a dependency via Composer If [Composer is already installed globally](https://getcomposer.org/doc/00-intro.md#globally) on your system, run the following in the base directory of your project to install AWS SDK for PHP as a dependency: ``` $ composer require aws/aws-sdk-php ``` Otherwise, type this Composer command to install the latest version of the AWS SDK for PHP as a dependency. ``` $ php -d memory_limit=-1 composer.phar require aws/aws-sdk-php ``` ### Add autoloader to your php scripts Installing Composer creates several folders and files in your environment. The primary file you will use is `autoload.php`, which is in the `vendor` folder in your environment. To utilize the AWS SDK for PHP in your scripts, include the autoloader in your scripts, as follows. ``` ``` ## Step 4: Download example code Use the terminal window to download example code for the AWS SDK for PHP into the AWS Cloud9 development environment. To download a copy of all the code examples used in the official AWS SDK documentation into your environment’s root directory, run the following command: ``` $ git clone https://github.com/awsdocs/aws-doc-sdk-examples.git ``` The code examples for the AWS SDK for PHP are located at `ENVIRONMENT_NAME/aws-doc-sdk-examples/php` directory, where `ENVIRONMENT_NAME` is the name of your development environment. To follow along using an Amazon S3 example, we recommend starting with code example `ENVIRONMENT_NAME/aws-doc-sdk-examples/php/example_code/s3/ListBuckets.php`. This example will list your Amazon S3 buckets. Use the terminal window to navigate to the `s3` directory and list the files. ``` $ cd aws-doc-sdk-examples/php/example_code/s3 $ ls ``` To open the file in AWS Cloud9, you can click on the `ListBuckets.php` directly in the terminal window. For more support in understanding code examples, see [AWS SDK for PHP Code Examples](examples_index.md). ## Step 5: Run example code To run code in your AWS Cloud9 development environment, choose the **Run** button in the top menu bar. AWS Cloud9 automatically detects the `.php` file extension and uses the **PHP (built-in web server)** runner to run the code. However, for this example we actually want the **PHP (`cli`)** option. For more information about running code in AWS Cloud9, see [Run Your Code](https://docs.aws.amazon.com/cloud9/latest/user-guide/build-run-debug.html#build-run-debug-run) in the *AWS Cloud9 User Guide*. In the following screenshot, note these basic areas: + 1: Run. The **Run** button is located on the top menu bar. This opens a new tab for your results. **Note** You can also manually create new run configurations. On the menu bar, choose **Run**, **Run Configurations**, **New Run Configuration**. + 2: Command. AWS Cloud9 populates the **Command** text box with the path and file name to the file you run. If your code expects any command line parameters to be passed in, these can be added to the command line in the same way that you would when running the code through a terminal window. + 3: Runner. AWS Cloud9 detects that your file extension is `.php` and selects the **PHP (built-in web server)** Runner to run your code. Select **PHP (`cli`)** to run this example instead. ![\[Choosing Run from the top menu bar of the AWS Cloud9 IDE opens a new tab with the Command box populated and the PHP runner already selected.\]](http://docs.aws.amazon.com/sdk-for-php/v3/developer-guide/images/cloud9_runconfig.png) Any output generated from the running code displays in the tab.