瀏覽代碼

Update PHP readme

Hamilton Turner 10 年之前
父節點
當前提交
6814f04bc4
共有 2 個文件被更改,包括 133 次插入51 次删除
  1. 114 48
      frameworks/PHP/README.md
  2. 19 3
      frameworks/PHP/php-symfony2/README.md

+ 114 - 48
frameworks/PHP/README.md

@@ -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
 # 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
     # Note the order! Composer depends on PHP so it has to come second
     fw_depends php composer 
     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 \
     --no-interaction --working-dir $TROOT --no-progress \
     --optimize-autoloader 
     --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, 
 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
     # Switch to the user that runs tests
     sudo su testrunner
     sudo su testrunner
     
     
@@ -56,28 +126,24 @@ it will require you to provide input. Use these steps
     # Run the installation shown above
     # Run the installation shown above
     #
     #
     # This will manually prompt you for your Github credentials 
     # 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 \
     ${IROOT}/php-5.5.17/bin/php $IROOT/composer.phar install \
       --working-dir $TROOT
       --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
     git add -f composer.lock
 
 
-**NOTE:** You should run this process manually once to generate the `composer.lock` file
-
 ## Updating Composer setup
 ## 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.
     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
 # 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`

+ 19 - 3
frameworks/PHP/php-symfony2/README.md

@@ -1,13 +1,24 @@
 # Symfony 2 Benchmarking Test
 # Symfony 2 Benchmarking Test
 
 
-This is the Symfony 2 PHP portion of a [benchmarking test suite](../) comparing a variety of web development platforms.
+This is the Symfony 2 PHP portion of a benchmarking test suite comparing a variety of web development platforms.
+
+This implementation is the direct result of installing the 
+[Standard Edition of Symfony 2](https://github.com/symfony/symfony-standard) using [Composer](https://getcomposer.org/), and making 
+the minimum modifications necessary to support 
+running the benchmark. Specifically, unnecessary bundles 
+have *not* been removed from the kernel to properly 
+reflect "out of the box" performance. If you're interested
+in tuned performance, see the symfony-stripped test, which
+removes and unnecessary components. 
+
+Note: `app/bootstrap.php.cache` is generated by Composer
+when you first run `composer.phar install`
 
 
 ### JSON Encoding Test
 ### JSON Encoding Test
 Uses the PHP standard [JSON encoder](http://www.php.net/manual/en/function.json-encode.php).
 Uses the PHP standard [JSON encoder](http://www.php.net/manual/en/function.json-encode.php).
 
 
 * [JSON test controller](src/Skamander/BenchmarkBundle/Controller/BenchController.php)
 * [JSON test controller](src/Skamander/BenchmarkBundle/Controller/BenchController.php)
 
 
-
 ### Data-Store/Database Mapping Test
 ### Data-Store/Database Mapping Test
 Uses the Symfony 2/Doctrine 2 Entity functionality.
 Uses the Symfony 2/Doctrine 2 Entity functionality.
 
 
@@ -19,7 +30,6 @@ Uses Symfony's template engine 'Twig'
 
 
 * [Template test controller](src/Skamander/BenchmarkBundle/Controller/BenchController.php)
 * [Template test controller](src/Skamander/BenchmarkBundle/Controller/BenchController.php)
 
 
-
 ## Infrastructure Software Versions
 ## Infrastructure Software Versions
 The tests were run with:
 The tests were run with:
 
 
@@ -44,3 +54,9 @@ http://localhost/db?queries=2
 ### Templating Test
 ### Templating Test
 
 
 http://localhost/fortunes
 http://localhost/fortunes
+
+# Interesting Links
+
+[Discussion on APC vs Zend Optimizer, PHP 5.4](http://www.ricardclau.com/2013/03/apc-vs-zend-optimizer-benchmarks-with-symfony2/)
+
+[Symphony2 Performance Tuning](http://symfony.com/doc/current/book/performance.html)