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/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/getting-started/community.md b/docs/getting-started/community.md new file mode 100644 index 0000000..d1c2a90 --- /dev/null +++ b/docs/getting-started/community.md @@ -0,0 +1,45 @@ +# Community + +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. + +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. diff --git a/docs/getting-started/philosophy.md b/docs/getting-started/philosophy.md new file mode 100644 index 0000000..455ff64 --- /dev/null +++ b/docs/getting-started/philosophy.md @@ -0,0 +1,76 @@ +# Our philosophy + +## 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! 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/async/child-processes.md b/docs/integrations/child-processes.md similarity index 84% rename from docs/async/child-processes.md rename to docs/integrations/child-processes.md index 37ed21a..40b4e0a 100644 --- a/docs/async/child-processes.md +++ b/docs/integrations/child-processes.md @@ -4,10 +4,10 @@ > > 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 * 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 004ce23..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 @@ -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..4416408 100644 --- a/docs/integrations/filesystem.md +++ b/docs/integrations/filesystem.md @@ -4,11 +4,11 @@ > > 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 * 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/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/async/streaming.md b/docs/integrations/streaming.md similarity index 90% rename from docs/async/streaming.md rename to docs/integrations/streaming.md index 6211394..0b91372 100644 --- a/docs/async/streaming.md +++ b/docs/integrations/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/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/docs/more/community.md b/docs/more/community.md deleted file mode 100644 index 0a32754..0000000 --- a/docs/more/community.md +++ /dev/null @@ -1,20 +0,0 @@ -# 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](../more/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. - -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 diff --git a/docs/more/philosophy.md b/docs/more/philosophy.md deleted file mode 100644 index 62ce5cd..0000000 --- a/docs/more/philosophy.md +++ /dev/null @@ -1,16 +0,0 @@ -# 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](../more/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) diff --git a/mkdocs.yml b/mkdocs.yml index 4782a35..65097a7 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 @@ -39,16 +41,12 @@ 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 - - integrations/authentication.md - - integrations/sessions.md - - integrations/templates.md - - integrations/queueing.md - - More: - - more/philosophy.md - - more/architecture.md - - more/community.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