|
|
@@ -1,19 +1,89 @@
|
|
|
-# Tricks to writing PHP-based Frameworks
|
|
|
-
|
|
|
-Many servers use the `php`, `php-fpm`, or other binaries. If your
|
|
|
-server launches with `sudo` (e.g. `sudo php-fpm`) then you should be
|
|
|
-aware that using sudo resets the `$PATH` environment variable, and your
|
|
|
-specific binary may not be the one being used. The solution is to
|
|
|
-always use `sudo <full-path-to-my-binary>`. For example, `cakephp`'s
|
|
|
-`bash_profile.sh` sets the variable `$PHP_FPM` to be the full path
|
|
|
-to the `php-fpm` binary that `cakephp` wants, and then uses `sudo $PHP_FPM`
|
|
|
-to ensure that the `php-fpm` binary used by sudo is the exact binary
|
|
|
-desired.
|
|
|
+# PHP Version
|
|
|
+
|
|
|
+[Currently this toolset runs PHP 5.5.17](https://github.com/TechEmpower/FrameworkBenchmarks/blob/master/toolset/setup/linux/languages/php.sh). At the moment all PHP-based frameworks use the
|
|
|
+same PHP version, but we are open to receiving a pull request
|
|
|
+that enables supporting multiple versions.
|
|
|
+
|
|
|
+# PHP Acceleration and Caching
|
|
|
+
|
|
|
+Caching the output of the PHP bytecode compiler is expressly
|
|
|
+allowed by this benchmark. As we use PHP 5.5, which comes
|
|
|
+with opcache built in, we recommend you use this. However,
|
|
|
+some frameworks utilize APC instead as switching can be
|
|
|
+problematic (e.g. APC allows arbitrary data caching, while
|
|
|
+opcache).
|
|
|
+
|
|
|
+Caching the output of parsing your configuration files is
|
|
|
+also expressly allowed (e.g. file caching). Some frameworks
|
|
|
+use APCu to achieve this.
|
|
|
+
|
|
|
+Caching of the classloader (often referred to as optimizing
|
|
|
+the classloader) is also allowed. Most frameworks have their
|
|
|
+own methods of doing this.
|
|
|
+
|
|
|
+Caching of any database, ORM results, or rendered templates
|
|
|
+is not allowed.
|
|
|
+
|
|
|
+Caching any data using Redis is discouraged, as 1) our
|
|
|
+Redis installation runs on a separate computer across the
|
|
|
+network, so you won't see much benefit 2) your usage of
|
|
|
+Redis *may* impact other framework's tests, which we cannot
|
|
|
+allow. You may launch Redis on the application server as
|
|
|
+part of your setup.sh scripts and utilize it for caching
|
|
|
+if you so desire.
|
|
|
+
|
|
|
+# Adding New PHP-based Frameworks
|
|
|
+
|
|
|
+Most PHP frameworks use `fw_depends php nginx composer` in their `install.sh` file,
|
|
|
+which installs PHP, Nginx, and Composer automatically. They then create a `setup.sh`
|
|
|
+containing these lines (comments added to clarify what's happening)
|
|
|
+
|
|
|
+ # Explanation of variables provided by toolset:
|
|
|
+ # FWROOT - absolute path to framework toolset, normally
|
|
|
+ # something like /home/username/FrameworkBenchmarks
|
|
|
+ # TROOT - absolute path to this framework's folder, normally
|
|
|
+ # something like /home/username/FrameworkBenchmarks/frameworks/PHP/cakephp
|
|
|
+ # IROOT - absolute path to the location where the toolset has installed software,
|
|
|
+ # something like /home/username/FrameworkBenchmarks/installs
|
|
|
+ #
|
|
|
+ # As of writing fw_depends installs 5.5.17 into the installer root
|
|
|
+ export PHP_HOME=${IROOT}/php-5.5.17
|
|
|
+ export PHP_FPM=$PHP_HOME/sbin/php-fpm
|
|
|
+ export NGINX_HOME=${IROOT}/nginx
|
|
|
+
|
|
|
+ # Uses the full path to php-fpm
|
|
|
+ # - php-fpm configuration is located in the config folder found in the
|
|
|
+ # root of this project
|
|
|
+ # - We tell PHP-FPM to place it's PID file into the deploy folder
|
|
|
+ $PHP_FPM --fpm-config $FWROOT/config/php-fpm.conf -g $TROOT/deploy/php-fpm.pid
|
|
|
+ # Turn on nginx using the configuration file found in this framework's deploy
|
|
|
+ # folder
|
|
|
+ $NGINX_HOME/sbin/nginx -c $TROOT/deploy/nginx.conf
|
|
|
+
|
|
|
+When using `php`, `php-fpm`, or other binaries, always use the full path
|
|
|
+to the binary, e.g. instead of `php <command>`,
|
|
|
+use `/home/foo/FrameworkBenchmarks/installs/php-5.5.17/bin/php <your command>`.
|
|
|
|
|
|
# Dependency Management Using Composer
|
|
|
|
|
|
-Many PHP apps use [Composer](https://getcomposer.org/) for dependency management.
|
|
|
-To support this, setup your `install.sh` with these two commands
|
|
|
+Many PHP apps use [Composer](https://getcomposer.org/) for dependency management,
|
|
|
+which greatly simplifies downloading the framework, loading the framework, and
|
|
|
+upgrading the framework version in the future.
|
|
|
+
|
|
|
+There are two main guidelines for PHP frameworks:
|
|
|
+
|
|
|
+* **Never include the source code for your framework into this repository.** Download it
|
|
|
+using Composer, wget, or some other tool
|
|
|
+* **When using Composer, always add a `composer.lock` file in addition to the `composer.json` file**.
|
|
|
+The lock file is a fully-defined file generated by composer 1) reading your JSON file 2) finding all
|
|
|
+dependencies 3) downloading a lot of data from Github. Without this lock file, composer takes 2-3x
|
|
|
+longer to run, and it can even halt and require user input
|
|
|
+
|
|
|
+## Setting up Composer
|
|
|
+
|
|
|
+Add a `composer.json` file to your framework's root folder, e.g. `php-fuel/composer.json`.
|
|
|
+Ensure your `install.sh` lists composer as a dependency, and uses `composer.phar` to
|
|
|
+install the dependencies required by your project.
|
|
|
|
|
|
# Note the order! Composer depends on PHP so it has to come second
|
|
|
fw_depends php composer
|
|
|
@@ -23,29 +93,29 @@ To support this, setup your `install.sh` with these two commands
|
|
|
--no-interaction --working-dir $TROOT --no-progress \
|
|
|
--optimize-autoloader
|
|
|
|
|
|
-Add your `composer.json` file to your framework's folder, e.g. `php-fuel/composer.json`.
|
|
|
After installation runs, your framework folder will have a new `vendor` folder,
|
|
|
-e.g. `php-fuel/vendor` that contains all dependencies.
|
|
|
-
|
|
|
-## One-time Composer Setup
|
|
|
-
|
|
|
-Composer uses Github *a lot*, enough so that it is common
|
|
|
-for it to exceed the API limit and cause infinite hangs or
|
|
|
-installation failures. To avoid this, it is necessary to
|
|
|
-generate a `composer.lock` file by manually running the
|
|
|
-installation one time - this file will list the exact
|
|
|
-github URLs that are needed for this project, which is then
|
|
|
-used by subsequent composer commands to avoid Github's
|
|
|
-rate limits. More on this [here](https://getcomposer.org/doc/03-cli.md#install) and [here](https://circleci.com/docs/composer-api-rate-limit)
|
|
|
-
|
|
|
-You need to generate `composer.lock` manually, and then add it
|
|
|
-to your framework's folder. This must be done manually because
|
|
|
-it will require you to provide input. Use these steps
|
|
|
-
|
|
|
- # Run one installation to ensure PHP is installed
|
|
|
- cd FrameworkBenchmarks
|
|
|
- toolset/run-tests.py --install server --install-only --test <your test>
|
|
|
-
|
|
|
+e.g. `php-fuel/vendor` that contains all dependencies. Update your PHP scripts
|
|
|
+to either directly reference files inside of vendor, or use the `vendor/autoload.php`
|
|
|
+file.
|
|
|
+
|
|
|
+## Generating composer.lock file
|
|
|
+
|
|
|
+Composer uses Github *a lot*, enough so that it is common for it to exceed the
|
|
|
+API limit and cause infinite hangs or installation failures. To avoid this, it
|
|
|
+is necessary to generate a `composer.lock` file. If you're lucky, you can run
|
|
|
+`toolset/run-tests.py --install server --test <your framework> --install-only`,
|
|
|
+which will run your `install.sh` file and leave the `composer.lock` file right
|
|
|
+next to your `composer.json` file. If this works, just add the lock file to
|
|
|
+the repository and you're done. There is more info on this [here](https://getcomposer.org/doc/03-cli.md#install)
|
|
|
+and [here](https://circleci.com/docs/composer-api-rate-limit)
|
|
|
+
|
|
|
+*Note:* You may have to force-add the lock file (e.g. `git add -f composer.lock`),
|
|
|
+because some gitignore files in this repo contain `*.lock` to avoid Ruby's lock files.
|
|
|
+
|
|
|
+If you are prompted for input during the `run-tests.py` script above, then you
|
|
|
+need to generate your lock file manually so that you may answer the input
|
|
|
+queries as they are shown. Use these steps
|
|
|
+
|
|
|
# Switch to the user that runs tests
|
|
|
sudo su testrunner
|
|
|
|
|
|
@@ -56,28 +126,24 @@ it will require you to provide input. Use these steps
|
|
|
# Run the installation shown above
|
|
|
#
|
|
|
# This will manually prompt you for your Github credentials
|
|
|
- # to avoid the Github rate limit, and when this command
|
|
|
- # finishes running you will have a new file composer.lock
|
|
|
+ # to avoid the Github rate limit
|
|
|
+ # When this command completes, you will have a lock file
|
|
|
${IROOT}/php-5.5.17/bin/php $IROOT/composer.phar install \
|
|
|
--working-dir $TROOT
|
|
|
|
|
|
- # Add the lock file to this repository so it's used for all
|
|
|
- # future installations
|
|
|
+ # Add the lock file to this repository
|
|
|
git add -f composer.lock
|
|
|
|
|
|
-**NOTE:** You should run this process manually once to generate the `composer.lock` file
|
|
|
-
|
|
|
## Updating Composer setup
|
|
|
|
|
|
-If you update `composer.json`, you need to re-run the above
|
|
|
-process to generate a new `composer.lock` file. If you forget
|
|
|
-to do this, you will see this error message when running the
|
|
|
-framework:
|
|
|
+If you update `composer.json`, you need to regenerate the lock
|
|
|
+file. If you forget to do this, you will see this error message
|
|
|
+when running:
|
|
|
|
|
|
Warning: The lock file is not up to date with the latest changes in composer.json. You may be getting outdated dependencies. Run update to update them.
|
|
|
|
|
|
# Debugging PHP Frameworks
|
|
|
|
|
|
-The first stop for HTTP 500 errors is to enable stack
|
|
|
-traces. Update `config/php-fpm.conf` to
|
|
|
-include `php_flag[display_errors] = on`.
|
|
|
+The first stop for HTTP 500 errors is to enable stack traces.
|
|
|
+Update `config/php-fpm.conf` to include `php_flag[display_errors] = on`.
|
|
|
+If you don't use php-fpm, update the `config/php.ini`
|
Hamilton Turner