From de198f390962c8253ae79c68f6f66345e97e7ca5 Mon Sep 17 00:00:00 2001 From: Steevan BARBOYON Date: Wed, 30 Jan 2019 16:17:12 +0100 Subject: [PATCH] Some fixes and documentation --- README.md | 92 ++++++++++++++++--- composer.json | 6 +- documentation/codeLink.md | 38 -------- documentation/codeValidation.md | 37 -------- documentation/composerUpdate.md | 37 -------- documentation/createRepositories.md | 11 --- documentation/framework/helloWorld.md | 7 +- documentation/initializeBranch.md | 39 -------- documentation/installation.md | 17 ++-- src/Command/BenchmarkValidateCommand.php | 2 +- .../Configure/ConfigureComponentCommand.php | 2 +- start.sh | 7 +- var/.gitkeep | 0 13 files changed, 99 insertions(+), 196 deletions(-) delete mode 100644 documentation/codeLink.md delete mode 100644 documentation/codeValidation.md delete mode 100644 documentation/composerUpdate.md delete mode 100644 documentation/createRepositories.md delete mode 100644 documentation/initializeBranch.md create mode 100644 var/.gitkeep diff --git a/README.md b/README.md index 296840d..638dc72 100644 --- a/README.md +++ b/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! diff --git a/composer.json b/composer.json index f54bb3f..229a126 100644 --- a/composer.json +++ b/composer.json @@ -12,5 +12,9 @@ ], "require-dev": { "steevanb/docker-php-code-sniffs": "~1.0.2" - } + }, + "bin": [ + "start.sh", + "dockerBash.sh" + ] } diff --git a/documentation/codeLink.md b/documentation/codeLink.md deleted file mode 100644 index bbbaa38..0000000 --- a/documentation/codeLink.md +++ /dev/null @@ -1,38 +0,0 @@ -Configure code links -- - -To prove all features are coded, you need to configure `$codeLinks` in `.phpbenchmarks/codeLink.sh`. - -`$codeLinks` contains links to your code, on `common` repository, for each benchmark feature. -
-Example for Symfony 4.0 Hello world: -```bash -#!/usr/bin/env bash - -declare -A codeLinks=( - [controller]="https://github.com/phpbenchmarks/symfony-common/blob/symfony_4_hello-world_prepare/Controller/HelloWorldController.php" - [route]="https://github.com/phpbenchmarks/symfony-common/blob/symfony_4_hello-world_prepare/Resources/config/routing.yml" -) -``` - -To do it easily, you can use `./codeLink.sh`. - -./codeLink.sh -- - -Without any parameter, it will ask you 2 informations: -* component type (framework or templateEngine) -* benchmark type (hello-world or rest-api) - -```bash -cd vendor/phpbenchmarks/benchmark-kit - -# will ask the 3 informations -./codeLink.sh -# first parameter is component type, it will ask only the 2 next informations -./codeLink.sh framework -# all informations are passed as parameters, no ask -./codeLink.sh framework hello-world -``` - -[Back to documentation index](../README.md) diff --git a/documentation/codeValidation.md b/documentation/codeValidation.md deleted file mode 100644 index 030beed..0000000 --- a/documentation/codeValidation.md +++ /dev/null @@ -1,37 +0,0 @@ -Validate your code -- - -To validate your code (configuration and benchmark url), you can use `./codeValidation.sh`. - -What will be validated: -* `.phpbenchmarks` directory, and all it's configuration files -* `README.md` content -* git branch name -* `composer.json` and `composer.lock.phpX.Y` dependencies -* benchmark url with each enabled PHP version - -./codeValidation.sh -- - -Without any parameter, it will ask you 2 informations: -* component type (framework or templateEngine) -* benchmark type (hello-world or rest-api) - -Available options: -* `-v`: view each validations performed -* `-vv`: view each validations performed + docker-compose build details -* `--skip-branch-name`: some validations could not be done when working before repositories are created. Use this parameter before repositories are created. -* `--prod`: validate everything is on the final branch and versioned, instead of development branch and not versioned. - -```bash -cd vendor/phpbenchmarks/benchmark-kit - -# will ask the 3 informations -./codeValidation.sh -# first parameter is component type, it will ask only the 2 next informations -./codeValidation.sh framework -# all informations are passed as parameters, no ask -./codeValidation.sh framework hello-world -``` - -[Back to documentation index](../README.md) diff --git a/documentation/composerUpdate.md b/documentation/composerUpdate.md deleted file mode 100644 index e8ec030..0000000 --- a/documentation/composerUpdate.md +++ /dev/null @@ -1,37 +0,0 @@ -Use composerUpdate.sh and not your composer -- - -While you are in development, you can use your own installation of Composer, or the official Composer Docker container (`docker run --rm -v $(pwd):/app composer/composer update`). - -Some dependencies could be installed in different versions depending on the version of PHP. -
-To test your code with `./codeValidation.sh`, -you should have a `composer.lock` by enabled PHP version (configured in `.phpbenchmarks/configuration.sh`). -
-To create them, you can use `./composerUpdate.sh`, who will do a `composer update` into a Docker container then move `composer.lock` to `composer.lock.phpX.Y`. - -./composerUpdate.sh -- - -Without any parameter, it will ask you 2 informations: -* component type (framework or templateEngine) -* benchmark type (hello-world or rest-api) - -Available options: -* `-v`: view each validations performed -* `-vv`: view each validations performed + docker-compose build details -* `--skip-branch-name`: some validations could not be done when when working before repositories are created. Use this parameter before repositories are created. -* `--prod`: validate everything is on the final branch and versioned, instead of development branch and not versioned. - -```bash -cd vendor/phpbenchmarks/benchmark-kit - -# will ask the 3 informations -./composerUpdate.sh -# first parameter is component type, it will ask only the 2 next informations -./composerUpdate.sh framework -# all informations are passed as parameters, no ask -./composerUpdate.sh framework hello-world -``` - -[Back to documentation index](../README.md) diff --git a/documentation/createRepositories.md b/documentation/createRepositories.md deleted file mode 100644 index b293f4b..0000000 --- a/documentation/createRepositories.md +++ /dev/null @@ -1,11 +0,0 @@ -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. - -[Back to documentation index](../README.md) diff --git a/documentation/framework/helloWorld.md b/documentation/framework/helloWorld.md index 5ec5ed6..3bc7a8f 100644 --- a/documentation/framework/helloWorld.md +++ b/documentation/framework/helloWorld.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) diff --git a/documentation/initializeBranch.md b/documentation/initializeBranch.md deleted file mode 100644 index 8b19bdd..0000000 --- a/documentation/initializeBranch.md +++ /dev/null @@ -1,39 +0,0 @@ -Initialize branch -- - -To make benchmark kit works, some file are required in your `main` repository branch. -
-You can use `initializeBranch.sh` to create them. -
-Feel free to edit them manually. - -* `README.md`: explanations about phpbenchmarks.com, this repository etc. -* `.phpbenchmarks/vhost.conf`: nginx configuration for virtual host. -* `.phpbenchmarks/configuration.sh`: configure enabled PHP versions, component version etc. -* `.phpbenchmarks/initBenchmark.sh`: should contains `initBenchmark()` function. Called before the benchmark to clear cache, install dependencies etc. -* `.phpbenchmarks/responseBody/`: should contains files to compare the body returned by your code to expected one. -* `.phpbenchmarks/codeLink.sh`: should contains `$codeLinks` associative array, which contains links to your code. Use [./codeLink.sh](codeLink.md) to easily edit it. - -./initializeBranch.sh -- - -Without any parameter, it will ask you 2 informations: -* component type (framework or templateEngine) -* benchmark type (hello-world or rest-api) - -Available options: -* `-v`: view each validations performed -* `-vv`: view each validations performed and wget output if configuration files are downloaded from github - -```bash -cd vendor/phpbenchmarks/benchmark-kit - -# will ask the 3 informations -./initializeBranch.sh -# first parameter is component type, it will ask only the 2 next informations -./initializeBranch.sh framework -# all informations are passed as parameters, no ask -./initializeBranch.sh framework hello-world -``` - -[Back to documentation index](../README.md) diff --git a/documentation/installation.md b/documentation/installation.md index c398e93..48d025e 100644 --- a/documentation/installation.md +++ b/documentation/installation.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) diff --git a/src/Command/BenchmarkValidateCommand.php b/src/Command/BenchmarkValidateCommand.php index e3a4346..8827244 100644 --- a/src/Command/BenchmarkValidateCommand.php +++ b/src/Command/BenchmarkValidateCommand.php @@ -43,7 +43,7 @@ protected function validateForPhpVersion(string $phpVersion): self $url = 'http://php' . str_replace('.', null, $phpVersion) - . '.benchmark.loc' + . '.benchmark.loc/' . ComponentConfiguration::getBenchmarkUrl(); $this diff --git a/src/Command/Configure/ConfigureComponentCommand.php b/src/Command/Configure/ConfigureComponentCommand.php index c6cbe8c..a43c29f 100644 --- a/src/Command/Configure/ConfigureComponentCommand.php +++ b/src/Command/Configure/ConfigureComponentCommand.php @@ -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'); } ); diff --git a/start.sh b/start.sh index 8fd81fc..2ea3e77 100755 --- a/start.sh +++ b/start.sh @@ -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" diff --git a/var/.gitkeep b/var/.gitkeep new file mode 100644 index 0000000..e69de29