diff --git a/.gitattributes b/.gitattributes index da20d18..9709aa5 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,7 +1,9 @@ /.gitattributes export-ignore /.github/workflows/ export-ignore /.gitignore export-ignore +/docs/ export-ignore /examples/ export-ignore +/mkdocs.yml export-ignore /phpunit.xml.dist export-ignore /phpunit.xml.legacy export-ignore /tests/ export-ignore diff --git a/README.md b/README.md index a9b58d7..f84ec5e 100644 --- a/README.md +++ b/README.md @@ -11,27 +11,10 @@ Framework X – the simple and fast micro framework for building reactive web ap ## Quickstart -First manually change your `composer.json` to include these lines: - -```json -{ - "repositories": [ - { - "type": "vcs", - "url": "https://github.com/clue-access/framework-x" - } - ] -} -``` - -Simply install Framework X: - -```bash -$ composer require clue/framework-x:dev-main -``` - -Once everything is installed, you can now use this example to get started with -a new `app.php` file: +Start by creating an empty project directory. +Next, we can start by taking a look at a simple example application. +You can use this example to get started by creating a new `app.php` file in your +empty project directory: ```php get('/', function () { ); }); +$app->get('/users/{name}', function (Psr\Http\Message\ServerRequestInterface $request) { + return new React\Http\Message\Response( + 200, + [], + "Hello " . $request->getAttribute('name') . "!\n" + ); +}); + +$app->run(); $loop->run(); ``` +Next, we need to install X and its dependencies to actually run this project. +Start by creating a new `composer.json` in the project directory with the following contents: + +```json +{ + "repositories": [ + { + "type": "vcs", + "url": "https://github.com/clue-access/framework-x" + } + ] +} +``` + +Finally, simply install Framework X: + +```bash +$ composer require clue/framework-x:dev-main +``` + That's it already! The next step is now to serve this web application. One of the nice properties of this project is that is works both behind traditional web server setups as well as in a stand-alone environment. @@ -67,41 +79,18 @@ You can now use your favorite webbrowser or command line tool to check your web application responds as expected: ```bash -$ curl -v http://localhost:8080/ -HTTP/1.1 200 OK -… - +$ curl http://localhost:8080/ Hello wörld! ``` ## Documentation Hooked? -See [full documentation](docs/) for more details. - -> We use [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) to -> render our documentation to a pretty HTML version. -> -> If you want to contribute to the documentation, it's easiest to just run -> this in a Docker container like this: -> -> ```bash -> $ docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material -> ``` -> -> You can access the documentation via `http://localhost:8000`. -> If you want to generate a static HTML folder for deployment, you can again -> use a Docker container like this: -> -> ```bash -> $ docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build -> ``` -> -> The resulting `build/docs/` should then be deployed behind a web server (tbd). -> If you want to add a new documentation file and/or change the page order, make sure the [`mkdocs.yml`](mkdocs.yml) -> file contains an up-to-date list of all pages. -> -> Happy hacking! +See [website](https://framework-x.clue.engineering/) for full documentation. + +Found a typo or want to contribute? +The website documentation is build from the source documentation files in +the [docs/](docs/) folder. ## Tests diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..48f6bb6 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,42 @@ +# Framework X documentation + +This folder contains the source documentation files for Framework X. + +You can see the [website](https://framework-x.clue.engineering/) for the +user-accessible version. + +## Contribute + +Found a typo or want to contribute? +This folder contains everything you need to help out with the documentation. + +We use [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) to +render our documentation to a pretty HTML version. + +If you want to contribute to the documentation, it's easiest to just run +this in a Docker container in the project root directory like this: + +```bash +$ docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material +``` + +You can access the documentation via `http://localhost:8000`. +Props to mkdocs, this uses live reloading, so that every change you do while +this Docker container is running should immediately be reflected in your web +browser. + +If you want to generate a static HTML folder for deployment, you can again +use a Docker container in the project root directory like this: + +```bash +$ docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build +``` + +The resulting `build/docs/` should then be deployed behind a web server. +See also the [Framework X website repository](https://github.com/clue/framework-x-website) +for more details about the website itself. + +If you want to add a new documentation file and/or change the page order, make sure the [`mkdocs.yml`](../mkdocs.yml) +file in the project root directory contains an up-to-date list of all pages. + +Happy hacking! diff --git a/docs/best-practices/deployment.md b/docs/best-practices/deployment.md index ba9c85c..74ff1e7 100644 --- a/docs/best-practices/deployment.md +++ b/docs/best-practices/deployment.md @@ -52,23 +52,8 @@ Hello wörld! ``` You may be wondering how fast a pure PHP web server implementation could possibly be. - -``` -$ ab -n10000 -c10 http://localhost:8080/ -… -Concurrency Level: 10 -Time taken for tests: 0.991 seconds -Complete requests: 10000 -Failed requests: 0 -Total transferred: 1090000 bytes -HTML transferred: 130000 bytes -Requests per second: 10095.17 [#/sec] (mean) -Time per request: 0.991 [ms] (mean) -Time per request: 0.099 [ms] (mean, across all concurrent requests) -Transfer rate: 1074.58 [Kbytes/sec] received -``` - -The answer: Very fast! +In fact, in benchmarks this setup outperforms any traditional PHP stack by orders of magnitude. +The answer: [Lightning fast!](https://framework-x.clue.engineering/#lightning-fast) If you're going to use this in production, we still recommend running this behind a reverse proxy such as nginx, HAproxy, etc. for TLS termination diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md index 421e808..53faa1c 100644 --- a/docs/getting-started/quickstart.md +++ b/docs/getting-started/quickstart.md @@ -33,6 +33,14 @@ $app->get('/', function () { ); }); +$app->get('/users/{name}', function (Psr\Http\Message\ServerRequestInterface $request) { + return new React\Http\Message\Response( + 200, + [], + "Hello " . $request->getAttribute('name') . "!\n" + ); +}); + $app->run(); $loop->run(); ``` diff --git a/mkdocs.yml b/mkdocs.yml index 4dbb56f..a7d595a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,12 +1,19 @@ -site_name: Documentation +site_name: Framework X documentation +site_url: https://framework-x.clue.engineering/docs/ site_dir: build/docs extra: homepage: ../ +repo_url: https://github.com/clue/framework-x +repo_name: clue/framework-x +edit_uri: "" # not publicly accessible while in early access + theme: name: material features: - navigation.sections + icon: + repo: fontawesome/brands/github markdown_extensions: - pymdownx.highlight