Some fixes and documentation

Author: steevanb

README.md

@@ -10,15 +10,75 @@ Documentation
 -
 
  * [Requirements and installation](documentation/installation.md)
- * [Ask us to create repositories](documentation/createRepositories.md)
  * [Understand repositories and branches](documentation/repositoriesAndBranches.md)
- * [Initialize main repository branch](documentation/initializeBranch.md)
- * [Use ./composerUpdate.sh and not your composer](documentation/composerUpdate.md)
- 
-Add required features for benchmarks
+
+Benchmark kit commands
+-
+
+When you are inside benchmark kit Docker container, you can use `phpbench` to list benchmark kit commands.
+
+Almost all commands accept this options:
+* `--skip-branch-name`: don't validate git branch name, usefull while you are in development and repositories are not created yet.
+* `--skip-source-code-urls`: don't validate source code urls, usefull while you are in development.
+* `--validate-prod`: you should not need it, it's used when we test your code before benchmarking it.
+
+#1 Ask us to create repositories
+-
+
+You can ask us to create repositories with [contact form](http://www.phpbenchmarks.com/en/contact).
+
+Tell us which component and version you want to benchmark,
+and `your github username` to allow you to commit on this repositories.
+
+We will send you an email when repositories will be created.
+
+
+#2 Start benchmark kit
+-
+
+To start benchmark kit Docker container, you have to call `./vendor/bin/start.sh`.
+
+It will ask you the directory where you code is located.
+You can pass this directory as parameter to this script.
+
+```bash
+./vendor/bin/start.sh
+./vendor/bin/start.sh /foo/code
+```
+
+#3 Initialize code
 -
 
-Choose your component type (framework or template engine) and benchmark type you want to code:
+To make your benchmark work you will need some files into `.phpbenchmarks` directory:
+* `AbstractComponentConfiguration.php`: configuration of benchmarked component.
+* `initBenchmark.sh`: called before the benchmark to initialize everything (composer install, cache warmup etc).
+* `vhost.conf`: nginx virtual host configuration.
+* `responseBody/`: benchmark url body will be compared to files in this directory to validate it's content.
+
+All this files can be created and configured with `phpbench` commands:
+
+```
+composer:update                     Execute composer update for all enabled PHP versions and create composer.lock.phpX.Y
+
+configure:all                       Call all configure commands
+configure:component                 Create .phpbenchmarks/AbstractComponentConfiguration.php and configure it
+configure:component:sourceCodeUrls  Create .phpbenchmarks/AbstractComponentConfiguration.php and configure getSourceCodeUrls()
+configure:directory                 Create .phpbenchmarks and .phpbenchmarks/responseBody directories
+configure:initBenchmark             Create .phpbenchmarks/initBenchmark.sh
+configure:responseBody              Create .phpbenchmarks/responseBody files
+configure:vhost                     Create .phpbenchmarks/vhost.conf, create phpXY.benchmark.loc vhosts and reload nginx
+```
+
+You can call `configure:all` to create all of them, or use the one your need.
+
+Note the `phpbench composer:update` command. We need a `composer.lock` per PHP version,
+because some dependencies are installed in different versions depending on the version of PHP.
+Use `phpbench composer:update` to switch between PHP version, and create `composer.lock.phpX.Y`.
+
+#4 Add required features for benchmarks
+-
+
+Choose the component type and benchmark type you want to code:
 
 * Framework
   * [Hello world benchmark](documentation/framework/helloWorld.md)
@@ -28,22 +88,24 @@ Choose your component type (framework or template engine) and benchmark type you
 
 Note that `all` component benchmarks needs to bo validated to make your component appear on [phpbenchmarks.com](http://www.phpbenchmarks.com).
 
-Code validation
+#5 Test and validate your code
 -
 
-You can use [./codeValidation.sh](documentation/codeValidation.md) to validate your code, while you are in development or when you think it's finished.
-
-Code links
--
+Docker container provide a domain for each PHP version, from 5.6 to 7.3:
+* http://php56.benchmark.loc
+* http://php70.benchmark.loc
+* http://php71.benchmark.loc
+* http://php72.benchmark.loc
+* http://php73.benchmark.loc
 
-To show us all features are included, you need to indicate where each feature is coded.
+You can use them to test your code.
 
-[./codeLink.sh](documentation/codeLink.md) helps you to tell us.
+When you think it's ok, use `phpbench benchmark:validate` to validate it.
 
-Everything is done
+#6 Submit your code
 -
 
-When [./codeValidation.sh](documentation/codeValidation.md) and [./codeLink.sh](documentation/codeLink.md) say it's good,
+When `phpbench benchmark:validate` say it's good,
 you can tell us to launch benchmarks with [contact form](http://www.phpbenchmarks.com/en/contact).
 
 Thank you!

composer.json

@@ -12,5 +12,9 @@
     ],
     "require-dev": {
         "steevanb/docker-php-code-sniffs": "~1.0.2"
-    }
+    },
+    "bin": [
+        "start.sh",
+        "dockerBash.sh"
+    ]
 }

documentation/codeLink.md

@@ -3,7 +3,7 @@ Hello world benchmark
 
 This benchmark shows the overhead cost of using a framework, instead of writing your code in PHP.
 
-To respect that, code should write `Hello World !` in response body, as fast as possible.
+To respect that, code should write `Hello World !` (yes, with space before `!`, cocorico ;)) in response body, as fast as possible.
 
 Disable everything you can: template engine, session, database access etc.
 
@@ -16,9 +16,4 @@ Don't forget this features as to be coded in [common repository](../repositories
 * A controller, called by this route. [Example](https://github.com/phpbenchmarks/symfony-common/blob/symfony_4_hello-world/Controller/HelloWorldController.php).
 * This controller should write `Hello World !` in response body as fast as possible. [Example](https://github.com/phpbenchmarks/symfony-common/blob/symfony_4_hello-world/Controller/HelloWorldController.php#L13).
 
-Validate your code
--
-
-When your code est terminated, you can validate it with [./codeValidation.sh](../codeValidation.md).
-
 [Back to documentation index](../../README.md)

documentation/codeValidation.md

@@ -2,20 +2,23 @@ Requirements
 -
 
 You will need this dependencies to make it work:
-* Linux, to use Docker and bash scripts
+* Linux to use Docker and bash scripts
 * [Docker ^18.06](https://docs.docker.com/install/)
 * [docker-compose ^1.12](https://docs.docker.com/compose/install/)
 
 Installation
 -
 
-Add `phpbenchmarks/benchmark-kit` as dependency of your projet.
-
-Not you have to do it in `require`, not in `require-dev`.
-As benchmark kit contains only bash scripts, requiring it will not affect your code until you call them manually.
-
 ```bash
-composer require phpbenchmarks/benchmark-kit ^1.0
+# you can install it where you want, ~/benchmarkKit used for the example
+mkdir ~/benchmarkKit
+cd ~/benchmarkKit
+echo '{"require": {"phpbenchmarks/benchmark-kit": "^2.0"}}' > composer.json
+
+# you can use your local composer installation, of the official Docker container
+docker run --rm -v $(pwd):/app composer/composer update --no-dev
+# in Docker container, composer update is called with root user, so change permissions to current user
+sudo chown -R $USER:$USER vendor
 ```
 
 [Back to documentation index](../README.md)

documentation/composerUpdate.md

@@ -43,7 +43,7 @@ protected function validateForPhpVersion(string $phpVersion): self
         $url =
             'http://php'
             . str_replace('.', null, $phpVersion)
-            . '.benchmark.loc'
+            . '.benchmark.loc/'
             . ComponentConfiguration::getBenchmarkUrl();
 
         $this

documentation/createRepositories.md

@@ -78,7 +78,7 @@ function () use ($phpVersion) {
         $this->defineVariable(
             '____PHPBENCHMARKS_BENCHMARK_URL____',
             function () {
-                return $this->question('Benchmark url, after host?', '/benchmark/helloworld');
+                return $this->question('Benchmark url, after host?', 'benchmark/helloworld');
             }
         );
 

documentation/framework/helloWorld.md

@@ -28,7 +28,7 @@ function echoAsk {
 }
 
 function defineInstallationPath {
-    lastInstallationPathFile=$(dirname $0)/var/lastInstallationPath.sh
+    lastInstallationPathFile="$KIT_ROOT_PATH/var/lastInstallationPath.sh"
     if [ ! -d "$installationPath" ]; then
         question="Path to your code?"
         if [ -f "$lastInstallationPathFile" ]; then
@@ -93,6 +93,7 @@ function addHost() {
 }
 
 trap onExit EXIT
+readonly KIT_ROOT_PATH="vendor/phpbenchmarks/benchmark-kit"
 
 currentAction=
 
@@ -107,9 +108,9 @@ addHost "php71.benchmark.loc"
 addHost "php72.benchmark.loc"
 addHost "php73.benchmark.loc"
 
-cd docker
+cd "$KIT_ROOT_PATH/docker"
 buildDockerImage
 startDockerContainer
 cd - 1>/dev/null
 
-source dockerBash.sh
+source "$KIT_ROOT_PATH/dockerBash.sh"