Skip to content

Commit ec512a5

Browse files
steevanbsteevanb
committed
Documentation
1 parent f2008dc commit ec512a5

File tree

11 files changed

+353
-4
lines changed

11 files changed

+353
-4
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
/.idea/
22

33
/docker/benchmarkKit/cli/vendor
4+
/docker/benchmarkKit/cli/composer.lock
45

56
/docker/composerUpdate/.env
67
/docker/composerUpdate/common.sh

‎README.md

Lines changed: 47 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,49 @@
1-
phpbenchmarks.com benchmark kit
2-
=
1+
<p align="center">
2+
<img src="http://www.phpbenchmarks.com/images/logo_github.png">
3+
<br>
4+
<a href="http://www.phpbenchmarks.com" target="_blank">www.phpbenchmarks.com</a>
5+
</p>
36

4-
Under construction ;)
7+
Benchmark kit is a tool to add a framework or a template engine benchmark on [phpbenchmarks.com](http://www.phpbenchmarks.com).
58

6-
Require docker-compose ^1.12
9+
Documentation
10+
-
11+
12+
* [Requirements and installation](documentation/installation.md)
13+
* [Ask us to create repositories](documentation/createRepositories.md)
14+
* [Understand repositories and branches](documentation/repositoriesAndBranches.md)
15+
* [Initialize main repository branch](documentation/initializeBranch.md)
16+
* [Use ./composerUpdate.sh and not your composer](documentation/composerUpdate.md)
17+
18+
Add required features for benchmarks
19+
-
20+
21+
Choose your component type (framework or template engine) and benchmark type you want to code:
22+
23+
* Framework
24+
* [Hello world benchmark](documentation/framework/helloWorld.md)
25+
* REST API benchmark (coming soon)
26+
* Template engine
27+
* Hello world benchmark (coming soon)
28+
29+
Note that `all` component benchmarks needs to bo validated to make your component appear on [phpbenchmarks.com](http://www.phpbenchmarks.com).
30+
31+
Code validation
32+
-
33+
34+
You can use [./codeValidation.sh](documentation/codeValidation.md) to validate your code, while you are in development or when you think it's finished.
35+
36+
Code links
37+
-
38+
39+
To show us all features are included, you need to indicate where each feature is coded.
40+
41+
[./codeLink.sh](documentation/codeLink.sh) helps you to tell us.
42+
43+
Everything is done
44+
-
45+
46+
When [./codeValidation.sh](documentation/codeValidation.md) and [./codeLink.sh](documentation/codeLink.md) say it's good,
47+
you can tell us to launch benchmarks with [contact form](http://www.phpbenchmarks.com/en/contact).
48+
49+
Thank you!

‎composer.json

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"name": "phpbenchmarks/benchmark-kit",
3+
"license": "proprietary",
4+
"authors": [
5+
{
6+
"name": "Steevan BARBOYON",
7+
"email": "[email protected]",
8+
"homepage": "http://www.info-droid.fr",
9+
"role": "Project lead"
10+
}
11+
]
12+
}

‎documentation/codeLink.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
Configure code links
2+
-
3+
4+
To prove all features are coded, you need to configure `$codeLinks` in `.phpbenchmarks/codeLink.sh`.
5+
6+
To do it easily, you can use `./codeLink.sh`.
7+
8+
./codeLink.sh
9+
-
10+
11+
Without any parameter, it will ask you 3 informations:
12+
* component type (framework or templateEngine)
13+
* benchmark type (hello-world or rest-api)
14+
* path to your code
15+
16+
```bash
17+
# will ask the 3 informations
18+
./codeLink.sh
19+
# first parameter is component type, it will ask only the 2 next informations
20+
./codeLink.sh framework
21+
# second parameter is benchmark type, it will ask only the path to your code
22+
./codeLink.sh framework hello-world
23+
# all informations are passed as parameters, no ask
24+
./codeLink.sh framework hello-world /foo/bar
25+
```
26+
27+
[Back to documentation index](../README.md)

‎documentation/codeValidation.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
Validate your code
2+
-
3+
4+
To validate your code (configuration and benchmark url), you can use `./codeValidation.sh`.
5+
6+
What will be validated:
7+
* `.phpbenchmarks` directory, and all it's configuration files
8+
* `README.md` content
9+
* git branch name
10+
* `composer.json` and `composer.lock.phpX.Y` dependencies
11+
* benchmark url with each enabled PHP version
12+
13+
./codeValidation.sh
14+
-
15+
16+
Without any parameter, it will ask you 3 informations:
17+
* component type (framework or templateEngine)
18+
* benchmark type (hello-world or rest-api)
19+
* path to your code
20+
21+
Available options:
22+
* `-v`: view each validations performed
23+
* `-vv`: view each validations performed + docker-compose build details
24+
* `--repositories-not-created`: some validations could not be done when working locally, use this parameter before repositories are created.
25+
* `--prod`: validate everything is on the final branch and versioned, instead of development branch and not versioned.
26+
27+
```bash
28+
# will ask the 3 informations
29+
./codeValidation.sh
30+
# first parameter is component type, it will ask only the 2 next informations
31+
./codeValidation.sh framework
32+
# second parameter is benchmark type, it will ask only the path to your code
33+
./codeValidation.sh framework hello-world
34+
# all informations are passed as parameters, no ask
35+
./codeValidation.sh framework hello-world /foo/bar
36+
```
37+
38+
[Back to documentation index](../README.md)

‎documentation/composerUpdate.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
Use composerUpdate.sh and not your composer
2+
-
3+
4+
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`).
5+
6+
Some dependencies could be installed in different versions depending on the version of PHP.
7+
<br>
8+
To test your code with `./codeValidation.sh`,
9+
you should have a `composer.lock` by enabled PHP version (configured in `.phpbenchmarks/configuration.sh`).
10+
<br>
11+
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`.
12+
13+
./composerUpdate.sh
14+
-
15+
16+
Without any parameter, it will ask you 3 informations:
17+
* component type (framework or templateEngine)
18+
* benchmark type (hello-world or rest-api)
19+
* path to your code
20+
21+
Available options:
22+
* `-v`: view each validations performed
23+
* `-vv`: view each validations performed + docker-compose build details
24+
* `--repositories-not-created`: some validations could not be done when working locally, use this parameter before repositories are created.
25+
* `--prod`: validate everything is on the final branch and versioned, instead of development branch and not versioned.
26+
27+
```bash
28+
# will ask the 3 informations
29+
./composerUpdate.sh
30+
# first parameter is component type, it will ask only the 2 next informations
31+
./composerUpdate.sh framework
32+
# second parameter is benchmark type, it will ask only the path to your code
33+
./composerUpdate.sh framework hello-world
34+
# all informations are passed as parameters, no ask
35+
./composerUpdate.sh framework hello-world /foo/bar
36+
```
37+
38+
[Back to documentation index](../README.md)

‎documentation/createRepositories.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
Ask us to create repositories
2+
-
3+
4+
You can ask us to create repositories with [contact form](http://www.phpbenchmarks.com/en/contact).
5+
6+
Tell us which component and version you want to benchmark,
7+
and `your github username` to allow you to commit on this repositories.
8+
9+
We will send you an email when repositories will be created.
10+
11+
[Back to documentation index](../README.md)

‎documentation/framework/helloWorld.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
Hello world benchmark
2+
-
3+
4+
This benchmark shows the overhead cost of using a framework, instead of writing your code in PHP.
5+
6+
To respect that, code should write `Hello World !` in response body, as fast as possible.
7+
8+
Disable everything you can: template engine, session, database access etc.
9+
10+
Features
11+
-
12+
13+
Don't forget this features as to be coded in [common repository](../repositoriesAndBranches.md).
14+
15+
* A route, with the url `benchmark/helloworld`. [Example](https://github.com/phpbenchmarks/symfony-common/blob/symfony_4_hello-world/Resources/config/routing.yml).
16+
* A controller, called by this route. [Example](https://github.com/phpbenchmarks/symfony-common/blob/symfony_4_hello-world/Controller/HelloWorldController.php).
17+
* 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).
18+
19+
Validate your code
20+
-
21+
22+
When your code est terminated, you can validate it with [./codeValidation.sh](../codeValidation.md).
23+
24+
[Back to documentation index](../../README.md)

‎documentation/initializeBranch.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
Initialize code
2+
-
3+
4+
To make benchmark kit works, some file are required in your `main` repository branch.
5+
<br>
6+
You can use `initializeBranch.sh` to create them.
7+
<br>
8+
Feel free to edit them manually.
9+
10+
* `README.md`: explanations about phpbenchmarks.com, this repository etc.
11+
* `.phpbenchmarks/vhost.conf`: nginx configuration for virtual host.
12+
* `.phpbenchmarks/configuration.sh`: configure enabled PHP versions, component version etc.
13+
* `.phpbenchmarks/initBenchmark.sh`: should contains `initBenchmark()` function. Called before the benchmark to clear cache, install dependencies etc.
14+
* `.phpbenchmarks/responseBody/`: should contains files to compare the body returned by your code to expected one.
15+
* `.phpbenchmarks/codeLink.sh`: should contains `$codeLinks` associative array, which contains links to your code. Use [./codeLink.sh](codeLink.md) to easily edit it.
16+
17+
./initializeBranch.sh
18+
-
19+
20+
Without any parameter, it will ask you 3 informations:
21+
* component type (framework or templateEngine)
22+
* benchmark type (hello-world or rest-api)
23+
* path to your code
24+
25+
```bash
26+
# will ask the 3 informations
27+
./initializeBranch.sh
28+
# first parameter is component type, it will ask only the 2 next informations
29+
./initializeBranch.sh framework
30+
# second parameter is benchmark type, it will ask only the path to your code
31+
./initializeBranch.sh framework hello-world
32+
# all informations are passed as parameters, no ask
33+
./initializeBranch.sh framework hello-world /foo/bar
34+
```
35+
36+
[Back to documentation index](../README.md)

‎documentation/installation.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
Requirements
2+
-
3+
4+
You will need this dependencies to make it work:
5+
* Linux, to use Docker and bash scripts
6+
* [Docker ^18.06](https://docs.docker.com/install/)
7+
* [docker-compose ^1.12](https://docs.docker.com/compose/install/)
8+
9+
Installation
10+
-
11+
12+
```bash
13+
mkdir ~/benchmarkKit
14+
cd ~/benchmarkKit
15+
echo '{"require": {"phpbenchmarks/benchmark-kit": "^1.0"}}' > composer.json
16+
docker run --rm -v $(pwd):/app composer/composer update
17+
# composer update is called with root user, so change permissions to current user
18+
sudo chown -R $USER:$USER vendor
19+
```
20+
21+
[Back to documentation index](../README.md)

0 commit comments

Comments
 (0)