From 07f1321a826588656cfbd06016797c69ae3b823b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Sun, 21 Nov 2021 11:10:56 +0100 Subject: [PATCH 1/5] Merge philosophy+architecture and move to getting started with community --- docs/async/child-processes.md | 2 +- docs/async/fibers.md | 2 +- docs/async/streaming.md | 2 +- docs/best-practices/deployment.md | 2 +- docs/{more => getting-started}/community.md | 2 +- docs/{more => getting-started}/philosophy.md | 16 +++++++++++++++- docs/integrations/authentication.md | 2 +- docs/integrations/database.md | 4 ++-- docs/integrations/filesystem.md | 2 +- docs/integrations/queueing.md | 2 +- docs/integrations/sessions.md | 2 +- docs/integrations/templates.md | 2 +- docs/more/architecture.md | 13 ------------- mkdocs.yml | 6 ++---- 14 files changed, 29 insertions(+), 30 deletions(-) rename docs/{more => getting-started}/community.md (91%) rename docs/{more => getting-started}/philosophy.md (55%) delete mode 100644 docs/more/architecture.md diff --git a/docs/async/child-processes.md b/docs/async/child-processes.md index 37ed21a..e422d4a 100644 --- a/docs/async/child-processes.md +++ b/docs/async/child-processes.md @@ -4,7 +4,7 @@ > > You're seeing an early draft of the documentation that is still in the works. > Give feedback to help us prioritize. -> We also welcome [contributors](../more/community.md) to help out! +> We also welcome [contributors](../getting-started/community.md) to help out! * Avoid blocking by moving blocking implementation to child process * Child process I/O for communication diff --git a/docs/async/fibers.md b/docs/async/fibers.md index 827a682..96049a4 100644 --- a/docs/async/fibers.md +++ b/docs/async/fibers.md @@ -49,7 +49,7 @@ return value. > > This is a feature preview, i.e. it might not have made it into the current beta. > Give feedback to help us prioritize. -> We also welcome [contributors](../more/community.md) to help out! +> We also welcome [contributors](../getting-started/community.md) to help out! At the moment, fibers are available as a development version by installing [react/async](https://github.com/reactphp/async) from a development branch diff --git a/docs/async/streaming.md b/docs/async/streaming.md index 6211394..0b91372 100644 --- a/docs/async/streaming.md +++ b/docs/async/streaming.md @@ -4,7 +4,7 @@ > > You're seeing an early draft of the documentation that is still in the works. > Give feedback to help us prioritize. -> We also welcome [contributors](../more/community.md) to help out! +> We also welcome [contributors](../getting-started/community.md) to help out! Processing large amounts of data or when data arrives at future time. diff --git a/docs/best-practices/deployment.md b/docs/best-practices/deployment.md index 8acdad7..cacc4d7 100644 --- a/docs/best-practices/deployment.md +++ b/docs/best-practices/deployment.md @@ -348,4 +348,4 @@ Hello wörld! > > You're seeing an early draft of the documentation that is still in the works. > Give feedback to help us prioritize. -> We also welcome [contributors](../more/community.md) to help out! +> We also welcome [contributors](../getting-started/community.md) to help out! diff --git a/docs/more/community.md b/docs/getting-started/community.md similarity index 91% rename from docs/more/community.md rename to docs/getting-started/community.md index 0a32754..b2def78 100644 --- a/docs/more/community.md +++ b/docs/getting-started/community.md @@ -4,7 +4,7 @@ > > You're seeing an early draft of the documentation that is still in the works. > Give feedback to help us prioritize. -> We also welcome [contributors](../more/community.md) to help out! +> We also welcome [contributors](../getting-started/community.md) to help out! Framework X will be released as open-source under the permissive MIT license. This means it will be free as in free speech and as in free beer. diff --git a/docs/more/philosophy.md b/docs/getting-started/philosophy.md similarity index 55% rename from docs/more/philosophy.md rename to docs/getting-started/philosophy.md index 62ce5cd..b2929ce 100644 --- a/docs/more/philosophy.md +++ b/docs/getting-started/philosophy.md @@ -4,7 +4,7 @@ > > You're seeing an early draft of the documentation that is still in the works. > Give feedback to help us prioritize. -> We also welcome [contributors](../more/community.md) to help out! +> We also welcome [contributors](../getting-started/community.md) to help out! * Motto: make easy things easy & hard things possible * From quick prototyping (RAD) to production environment in hours @@ -14,3 +14,17 @@ * Promote best practices, but don't enfore certain style * Runs anywhere * Open and inclusive [community](community.md) + +# Architecture + +> ⚠️ **Documentation still under construction** +> +> You're seeing an early draft of the documentation that is still in the works. +> Give feedback to help us prioritize. +> We also welcome [contributors](../getting-started/community.md) to help out! + +* HTTP request response semantics +* PHP runs everywhere +* shared nothing execution model (optional) +* ReactPHP (long-running optional) +* Async PHP diff --git a/docs/integrations/authentication.md b/docs/integrations/authentication.md index 1fac8f2..a06a5b8 100644 --- a/docs/integrations/authentication.md +++ b/docs/integrations/authentication.md @@ -4,7 +4,7 @@ > > You're seeing an early draft of the documentation that is still in the works. > Give feedback to help us prioritize. -> We also welcome [contributors](../more/community.md) to help out! +> We also welcome [contributors](../getting-started/community.md) to help out! * HTTP Basic auth easy to implement * Implementation as HTTP [middleware](../api/middleware.md) recommended diff --git a/docs/integrations/database.md b/docs/integrations/database.md index 004ce23..2af7ab3 100644 --- a/docs/integrations/database.md +++ b/docs/integrations/database.md @@ -177,7 +177,7 @@ database implementations. > > This is a feature preview, i.e. it might not have made it into the current beta. > Give feedback to help us prioritize. -> We also welcome [contributors](../more/community.md) to help out! +> We also welcome [contributors](../getting-started/community.md) to help out! There is ongoing effort to provide an async DBAL (DataBase Abstraction Layer) that will allow you to write your logic in such a way that it is not tied to a @@ -794,7 +794,7 @@ structures to get you started: > > This is a feature preview, i.e. it might not have made it into the current beta. > Give feedback to help us prioritize. -> We also welcome [contributors](../more/community.md) to help out! +> We also welcome [contributors](../getting-started/community.md) to help out! If you're using X behind a [traditional web server](../best-practices/deployment.md#traditional-stacks), there's nothing to worry about: PHP will process a single request and then clean diff --git a/docs/integrations/filesystem.md b/docs/integrations/filesystem.md index fde630c..24235ce 100644 --- a/docs/integrations/filesystem.md +++ b/docs/integrations/filesystem.md @@ -4,7 +4,7 @@ > > You're seeing an early draft of the documentation that is still in the works. > Give feedback to help us prioritize. -> We also welcome [contributors](../more/community.md) to help out! +> We also welcome [contributors](../getting-started/community.md) to help out! * Async APIs with [Promises](../async/promises.md) * Avoid using blocking `fopen()`, `file_get_contents()` and family diff --git a/docs/integrations/queueing.md b/docs/integrations/queueing.md index b4e3437..7e57d99 100644 --- a/docs/integrations/queueing.md +++ b/docs/integrations/queueing.md @@ -4,7 +4,7 @@ > > You're seeing an early draft of the documentation that is still in the works. > Give feedback to help us prioritize. -> We also welcome [contributors](../more/community.md) to help out! +> We also welcome [contributors](../getting-started/community.md) to help out! * Common requirement to offload work from frontend to background workers * Major queue vendors supported already diff --git a/docs/integrations/sessions.md b/docs/integrations/sessions.md index 6ebd446..d0fa8ee 100644 --- a/docs/integrations/sessions.md +++ b/docs/integrations/sessions.md @@ -4,7 +4,7 @@ > > You're seeing an early draft of the documentation that is still in the works. > Give feedback to help us prioritize. -> We also welcome [contributors](../more/community.md) to help out! +> We also welcome [contributors](../getting-started/community.md) to help out! * Session handling common requirement and not hard to implement * Implementation as HTTP [middleware](../api/middleware.md) recommended diff --git a/docs/integrations/templates.md b/docs/integrations/templates.md index 9bc16a2..0e241f1 100644 --- a/docs/integrations/templates.md +++ b/docs/integrations/templates.md @@ -4,7 +4,7 @@ > > You're seeing an early draft of the documentation that is still in the works. > Give feedback to help us prioritize. -> We also welcome [contributors](../more/community.md) to help out! +> We also welcome [contributors](../getting-started/community.md) to help out! * Very common requirement, especially for [HTML pages](../api/response.md#html) * Any template language possible diff --git a/docs/more/architecture.md b/docs/more/architecture.md deleted file mode 100644 index 5fcf73f..0000000 --- a/docs/more/architecture.md +++ /dev/null @@ -1,13 +0,0 @@ -# Architecture - -> ⚠️ **Documentation still under construction** -> -> You're seeing an early draft of the documentation that is still in the works. -> Give feedback to help us prioritize. -> We also welcome [contributors](../more/community.md) to help out! - -* HTTP request response semantics -* PHP runs everywhere -* shared nothing execution model (optional) -* ReactPHP (long-running optional) -* Async PHP diff --git a/mkdocs.yml b/mkdocs.yml index 4782a35..26662fe 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -26,6 +26,8 @@ nav: - Getting Started: # - "Why?": "" - getting-started/quickstart.md + - getting-started/philosophy.md + - getting-started/community.md - Best Practices: - "Controller classes": best-practices/controllers.md - best-practices/testing.md @@ -48,7 +50,3 @@ nav: - integrations/sessions.md - integrations/templates.md - integrations/queueing.md - - More: - - more/philosophy.md - - more/architecture.md - - more/community.md From ba2840b8bc2b50a4f7f51cda8782297e49ee23ba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Tue, 23 Nov 2021 10:11:44 +0100 Subject: [PATCH 2/5] Improve community documentation --- docs/getting-started/community.md | 45 ++++++++++++++++++++++++------- 1 file changed, 35 insertions(+), 10 deletions(-) diff --git a/docs/getting-started/community.md b/docs/getting-started/community.md index b2def78..d1c2a90 100644 --- a/docs/getting-started/community.md +++ b/docs/getting-started/community.md @@ -1,10 +1,40 @@ # Community -> ⚠️ **Documentation still under construction** -> -> You're seeing an early draft of the documentation that is still in the works. -> Give feedback to help us prioritize. -> We also welcome [contributors](../getting-started/community.md) to help out! +Framework X is so much more than *yet another framework*, it is the way to +introduce asynchronous programming to the broader PHP community. We believe it's +essential to involve the whole community in all our processes and provide you +with the opportunity to bring up your awesome ideas. + +## Support + +We are where the open-source community is! We use + +* [GitHub discussions](https://github.com/clue/framework-x/discussions) and +* [GitHub issues](https://github.com/clue/framework-x/issues) + +as a great way to keep track of discussions and follow the project progress and +upcoming enhancements. +See also our [community section](https://framework-x.org/#community) for more +support options, including commercial ones. + +You may also reach out to us by mentioning [**@x_framework** on Twitter](https://twitter.com/x_framework). +We would love to hear your feedback! ❤️ + +## Want to help out? + +We actively invite contributors to this project! + +* Follow [**@x_framework** on Twitter](https://twitter.com/x_framework) +* Engage in our [GitHub discussions](https://github.com/clue/framework-x/discussions) +* Help by giving feedback or triaging [GitHub issues](https://github.com/clue/framework-x/issues) +* Consider becoming a [sponsor on GitHub](https://github.com/sponsors/clue) +* Contribute to our [GitHub repository](https://github.com/clue/framework-x) with a code or documentation PR. Happy hacking! + +If you've tried out X, no matter how small your experiment, make sure to share +your results with the world! We would love to hear what you think about X in a +tweet mentioning [**@x_framework**](https://twitter.com/x_framework). ❤️ + +## Open source Framework X will be released as open-source under the permissive MIT license. This means it will be free as in free speech and as in free beer. @@ -13,8 +43,3 @@ We believe in open source and made a conscious decision to take this path. Being open-source means we can foster a community to focus on building the best possible framework together. Framework X builds on top of existing open-source projects and we want to give back to this community of awesome engineers and developers. Being open to outside contributions means we can guarantee interoperability with a vivid ecosystem and ensure the longevity of the project. - -* Twitter [@x_framework](https://twitter.com/x_framework) -* GitHub discussions -* Support chat -* GitHub sponsors From 2ef80a06aad2a9e189dd8e1b8b6d108b27e30295 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Tue, 23 Nov 2021 11:03:54 +0100 Subject: [PATCH 3/5] Improve philosophy documentation --- docs/getting-started/philosophy.md | 102 +++++++++++++++++++++-------- 1 file changed, 74 insertions(+), 28 deletions(-) diff --git a/docs/getting-started/philosophy.md b/docs/getting-started/philosophy.md index b2929ce..455ff64 100644 --- a/docs/getting-started/philosophy.md +++ b/docs/getting-started/philosophy.md @@ -1,30 +1,76 @@ # Our philosophy -> ⚠️ **Documentation still under construction** -> -> You're seeing an early draft of the documentation that is still in the works. -> Give feedback to help us prioritize. -> We also welcome [contributors](../getting-started/community.md) to help out! - -* Motto: make easy things easy & hard things possible -* From quick prototyping (RAD) to production environment in hours -* Batteries included, but swappable -* Reuse where applicable, but accept some duplication -* Long-term support (LTS) and careful upgrade paths -* Promote best practices, but don't enfore certain style -* Runs anywhere -* Open and inclusive [community](community.md) - -# Architecture - -> ⚠️ **Documentation still under construction** -> -> You're seeing an early draft of the documentation that is still in the works. -> Give feedback to help us prioritize. -> We also welcome [contributors](../getting-started/community.md) to help out! - -* HTTP request response semantics -* PHP runs everywhere -* shared nothing execution model (optional) -* ReactPHP (long-running optional) -* Async PHP +## What drives us + +Framework X is so much more than *yet another framework*. Here's what drives +us and how we make decisions for the framework. + +* **make easy things easy & hard things possible** + + Making easy things easy is one of our leading mottos. If making the hard thing + possible involves making the easy thing hard, we would rather focus on the easy + thing. + +* **From quick prototyping RAD to production environments in hours** + + Get started in minutes with a RAD prototype! + With X, you can get from prototypes to production in hours, not weeks. + +* **Batteries included, but swappable** + + X provides everything you need to get started. We use a very composable + architecture, so all the parts are swappable in case you need custom + integrations. + +* **Reuse where applicable, but accept some duplication** + + Code reuse is great! But if applying DRY + involves too many abstractions, we would rather accept some duplication. We value simplicity + as a core design principle. + +* **Long-term support (LTS) and careful upgrade paths** + + We're committed to providing long-term support (LTS) options and providing a smooth upgrade + path between versions. We want to be the rock-solid foundation that you can build on top of. + +* **Promote best practices, but don't enforce certain style** + + We like DDD, TDD, + and more. If you don't, that's fine, we like choice. While we encourage following best + practices and try to give recommendations, we don't enforce a certain style. + +* **Runs anywhere** + + We support the latest versions but we only require PHP 7.1+ for maximum compatibility to + ensure X runs anywhere. From shared hosting to cloud-native! + +* **Open and inclusive community** + + Framework X is so much more than the sum of its parts. In particular, see our awesome [community](community.md). + +## Architecture + +* **HTTP request response semantics** + + Framework X is all about handling [HTTP requests](../api/request.md) and sending back + [ HTTP responses](../api/response.md). + +* **PHP runs everywhere** + + We know, PHP has its quirks. But it also provides a unique opportunity with its huge ecosystem + that allows you to run X literally anywhere. + +* **shared-nothing execution (optional)** + + We support PHP's default shared-nothing execution model when running with + [traditional stacks](../best-practices/deployment.md#traditional-stacks). + +* **built-in web server (optional)** + + If you're ready, get even more awesome features with its + [built-in web server](../best-practices/deployment.md#built-in-web-server). + +* **Async PHP** + + We're standing on the shoulders of giants. Thank you [ReactPHP](https://reactphp.org/) for + providing an awesome foundation! From 8fc41403570c7943409501e293d3593fd82122d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Tue, 23 Nov 2021 11:12:35 +0100 Subject: [PATCH 4/5] Move child processes and streaming to integrations --- docs/{async => integrations}/child-processes.md | 2 +- docs/integrations/database.md | 2 +- docs/integrations/filesystem.md | 2 +- docs/{async => integrations}/streaming.md | 0 mkdocs.yml | 4 ++-- 5 files changed, 5 insertions(+), 5 deletions(-) rename docs/{async => integrations}/child-processes.md (95%) rename docs/{async => integrations}/streaming.md (100%) diff --git a/docs/async/child-processes.md b/docs/integrations/child-processes.md similarity index 95% rename from docs/async/child-processes.md rename to docs/integrations/child-processes.md index e422d4a..40b4e0a 100644 --- a/docs/async/child-processes.md +++ b/docs/integrations/child-processes.md @@ -10,4 +10,4 @@ * Child process I/O for communication * Multithreading, but isolated processes * See [reactphp/child-process](https://reactphp.org/child-process/) for underlying APIs -* See [clue/reactphp-pq](https://github.com/clue/reactphp-pq) for higher-level API to automatically wrap blocking functions in an async child process and turn blocking functions into non-blocking [promises](promises.md) +* See [clue/reactphp-pq](https://github.com/clue/reactphp-pq) for higher-level API to automatically wrap blocking functions in an async child process and turn blocking functions into non-blocking [promises](../async/promises.md) diff --git a/docs/integrations/database.md b/docs/integrations/database.md index 2af7ab3..83f4c5d 100644 --- a/docs/integrations/database.md +++ b/docs/integrations/database.md @@ -169,7 +169,7 @@ database implementations. > described above. For legacy integrations, we provide limited support for > blocking database calls such as PDO, Doctrine, etc., but as a rule of thumb, > going for an async alternative is usually somewhat more efficient. -> See [child processes](../async/child-processes.md) for more details. +> See [child processes](child-processes.md) for more details. ## DBAL diff --git a/docs/integrations/filesystem.md b/docs/integrations/filesystem.md index 24235ce..4416408 100644 --- a/docs/integrations/filesystem.md +++ b/docs/integrations/filesystem.md @@ -10,5 +10,5 @@ * Avoid using blocking `fopen()`, `file_get_contents()` and family * Few blocking calls *can* be acceptable * See [reactphp/filesystem](https://github.com/reactphp/filesystem) for filesystem prototype -* Avoid blocking filesystem by using [child process](../async/child-processes.md) +* Avoid blocking filesystem by using [child process](child-processes.md) * See [clue/reactphp-s3](https://github.com/clue/reactphp-s3) for async S3 filesystem API (supporting Amazon S3, Ceph, MiniIO, DigitalOcean Spaces and others) diff --git a/docs/async/streaming.md b/docs/integrations/streaming.md similarity index 100% rename from docs/async/streaming.md rename to docs/integrations/streaming.md diff --git a/mkdocs.yml b/mkdocs.yml index 26662fe..258cde8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -41,11 +41,11 @@ nav: - async/fibers.md - async/coroutines.md - async/promises.md - - async/streaming.md - - "Child processes": async/child-processes.md - Integrations: - integrations/database.md - integrations/filesystem.md + - "Child processes": integrations/child-processes.md + - integrations/streaming.md - integrations/authentication.md - integrations/sessions.md - integrations/templates.md From e6a280b18a53cd0fef6d89600299c6441168e0c9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Tue, 23 Nov 2021 11:17:24 +0100 Subject: [PATCH 5/5] Mark incomplete sections in documentation --- mkdocs.yml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 258cde8..65097a7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -43,10 +43,10 @@ nav: - async/promises.md - Integrations: - integrations/database.md - - integrations/filesystem.md - - "Child processes": integrations/child-processes.md - - integrations/streaming.md - - integrations/authentication.md - - integrations/sessions.md - - integrations/templates.md - - integrations/queueing.md + - "⚠ Filesystem": integrations/filesystem.md + - "⚠ Child processes": integrations/child-processes.md + - "⚠ Streaming": integrations/streaming.md + - "⚠ Authentication": integrations/authentication.md + - "⚠ Sessions": integrations/sessions.md + - "⚠ Templates": integrations/templates.md + - "⚠ Queueing": integrations/queueing.md