src
11 months ago
CODE_OF_CONDUCT.md
11 months ago
LICENSE
11 months ago
NOTICE
11 months ago
README.md
11 months ago
composer.json
11 months ago
README.md
118 lines
| 1 | # AWS Common Runtime PHP bindings |
| 2 | |
| 3 | ## Requirements |
| 4 | |
| 5 | * PHP 5.5+ on UNIX platforms, 7.2+ on Windows |
| 6 | * CMake 3.x |
| 7 | * GCC 4.4+, clang 3.8+ on UNIX, Visual Studio build tools on Windows |
| 8 | * Tests require [](https://getcomposer.orgComposer](https://getcomposer.org](https://getcomposer.org) |
| 9 | |
| 10 | ## Installing with Composer and PECL |
| 11 | |
| 12 | The package has two different package published to [](https://packagist.org/packages/aws/aws-crt-phpcomposer](https://packagist.org/packages/aws/aws-crt-php](https://packagist.org/packages/aws/aws-crt-php) and [](https://pecl.php.net/package/awscrtPECL](https://pecl.php.net/package/awscrt](https://pecl.php.net/package/awscrt). |
| 13 | |
| 14 | On UNIX, you can get the package from package manager or build from source: |
| 15 | |
| 16 | ``` |
| 17 | pecl install awscrt |
| 18 | composer require aws/aws-crt-php |
| 19 | ``` |
| 20 | |
| 21 | On Windows, you need to build from source as instruction written below for the native extension `php_awscrt.dll` . And, follow https://www.php.net/manual/en/install.pecl.windows.php#install.pecl.windows.loading to load extension. After that: |
| 22 | |
| 23 | ``` |
| 24 | composer require aws/aws-crt-php |
| 25 | ``` |
| 26 | |
| 27 | ## Building from Github source |
| 28 | |
| 29 | ```sh |
| 30 | $ git clone --recursive https://github.com/awslabs/aws-crt-php.git |
| 31 | $ cd aws-crt-php |
| 32 | $ phpize |
| 33 | $ ./configure |
| 34 | $ make |
| 35 | $ ./dev-scripts/run_tests.sh |
| 36 | ``` |
| 37 | |
| 38 | ## Building on Windows |
| 39 | |
| 40 | ### Requirements for Windows |
| 41 | |
| 42 | * Ensure you have the [](https://github.com/microsoft/php-sdk-binary-toolswindows PHP SDK](https://github.com/microsoft/php-sdk-binary-tools](https://github.com/microsoft/php-sdk-binary-tools) (this example assumes installation of the SDK to C:\php-sdk and that you've checked out the PHP source to php-src within the build directory) and it works well on your machine. |
| 43 | |
| 44 | * Ensure you have "Development package (SDK to develop PHP extensions)" and PHP available from your system path. You can download them from https://windows.php.net/download/. You can check if they are available by running `phpize -v` and `php -v` |
| 45 | |
| 46 | ### Instructions |
| 47 | |
| 48 | From Command Prompt (not powershell). The instruction is based on Visual Studio 2019 on 64bit Windows. |
| 49 | |
| 50 | ```bat |
| 51 | > git clone --recursive https://github.com/awslabs/aws-crt-php.git |
| 52 | > git clone https://github.com/microsoft/php-sdk-binary-tools.git C:\php-sdk |
| 53 | > C:\php-sdk\phpsdk-vs16-x64.bat |
| 54 | |
| 55 | C:\php-sdk\ |
| 56 | $ cd <your-path-to-aws-crt-php> |
| 57 | |
| 58 | <your-path-to-aws-crt-php>\ |
| 59 | $ phpize |
| 60 | |
| 61 | # --with-prefix only required when your php runtime in system path is different than the runtime you wish to use. |
| 62 | <your-path-to-aws-crt-php>\ |
| 63 | $ configure --enable-awscrt=shared --with-prefix=<your-path-to-php-prefix> |
| 64 | |
| 65 | <your-path-to-aws-crt-php>\ |
| 66 | $ nmake |
| 67 | |
| 68 | <your-path-to-aws-crt-php>\ |
| 69 | $ nmake generate-php-ini |
| 70 | |
| 71 | # check .\php-win.ini, it now has the full path to php_awscrt.dll that you can manually load to your php runtime, or you can run the following command to run tests and load the required native extension for awscrt. |
| 72 | <your-path-to-aws-crt-php>\ |
| 73 | $ .\dev-scripts\run_tests.bat <your-path-to-php-binary> |
| 74 | ``` |
| 75 | |
| 76 | Note: for VS2017, Cmake will default to build for Win32, refer to [](https://cmake.org/cmake/help/latest/generator/Visual%20Studio%2015%202017.htmlhere](https://cmake.org/cmake/help/latest/generator/Visual%20Studio%2015%202017.html](https://cmake.org/cmake/help/latest/generator/Visual%20Studio%2015%202017.html). If you are building for x64 php, you can set environment variable as follow to let cmake pick x64 compiler. |
| 77 | |
| 78 | ```bat |
| 79 | set CMAKE_GENERATOR=Visual Studio 15 2017 |
| 80 | set CMAKE_GENERATOR_PLATFORM=x64 |
| 81 | ``` |
| 82 | |
| 83 | ## Debugging |
| 84 | |
| 85 | Using [](https://github.com/phpbrew/phpbrewPHPBrew](https://github.com/phpbrew/phpbrew](https://github.com/phpbrew/phpbrew) to build/manage multiple versions of PHP is helpful. |
| 86 | |
| 87 | Note: You must use a debug build of PHP to debug native extensions. |
| 88 | See the [](https://www.phpinternalsbook.com/php7/build_system/building_php.htmlPHP Internals Book](https://www.phpinternalsbook.com/php7/build_system/building_php.html](https://www.phpinternalsbook.com/php7/build_system/building_php.html) for more info |
| 89 | |
| 90 | ```shell |
| 91 | # PHP 8 example |
| 92 | $ phpbrew install --stdout -j 8 8.0 +default -- CFLAGS=-Wno-error --disable-cgi --enable-debug |
| 93 | # PHP 5.5 example |
| 94 | $ phpbrew install --stdout -j 8 5.5 +default -openssl -mbstring -- CFLAGS="-w -Wno-error" --enable-debug --with-zlib=/usr/local/opt/zlib |
| 95 | $ phpbrew switch php-8.0.6 # or whatever version is current, it'll be at the end of the build output |
| 96 | $ phpize |
| 97 | $ ./configure |
| 98 | $ make CMAKE_BUILD_TYPE=Debug |
| 99 | ``` |
| 100 | |
| 101 | Ensure that the php you launch from your debugger is the result of `which php` , not just |
| 102 | the system default php. |
| 103 | |
| 104 | ## Security |
| 105 | |
| 106 | See [](CONTRIBUTING.md#security-issue-notificationsCONTRIBUTING](CONTRIBUTING.md#security-issue-notifications](CONTRIBUTING.md#security-issue-notifications) for more information. |
| 107 | |
| 108 | ## Known OpenSSL related issue (Unix only) |
| 109 | |
| 110 | * When your php loads a different version of openssl than your system openssl version, awscrt may fail to load or weirdly crash. You can find the openssl version php linked via: `php -i | grep 'OpenSSL'`, and awscrt linked from the build log, which will be `Found OpenSSL: * (found version *)` |
| 111 | |
| 112 | The easiest workaround to those issue is to build from source and get aws-lc for awscrt to depend on instead. |
| 113 | TO do that, same instructions as [](#building-from-github-sourcehere](#building-from-github-source](#building-from-github-source), but use `USE_OPENSSL=OFF make` instead of `make` |
| 114 | |
| 115 | ## License |
| 116 | |
| 117 | This project is licensed under the Apache-2.0 License. |
| 118 |