1
0
mirror of https://github.com/danog/amp.git synced 2024-12-02 17:37:50 +01:00
amp/README.md

96 lines
4.6 KiB
Markdown
Raw Normal View History

2017-11-12 16:13:12 +01:00
<a href="https://amphp.org/">
<img src="https://github.com/amphp/logo/blob/master/repos/amp-logo-with-margin.png?raw=true" width="250" align="right" alt="Amp Logo">
2017-11-12 16:13:12 +01:00
</a>
2015-04-29 17:29:09 +02:00
2018-04-30 22:49:57 +02:00
<a href="https://amphp.org/"><img alt="Amp" src="https://github.com/amphp/logo/blob/master/repos/amp-text.png?raw=true" width="100" valign="middle"></a>
2015-07-19 19:29:25 +02:00
2017-07-16 18:24:07 +02:00
Amp is a non-blocking concurrency framework for PHP. It provides an event loop, promises and streams as a base for asynchronous programming.
2017-03-13 13:16:59 +01:00
Promises in combination with generators are used to build coroutines, which allow writing asynchronous code just like synchronous code, without any callbacks.
2018-04-30 22:49:57 +02:00
<a href="https://travis-ci.org/amphp/amp"><img src="https://img.shields.io/travis/amphp/amp/master.svg?style=flat-square" valign="middle"></a>
<a href="https://coveralls.io/github/amphp/amp?branch=master"><img src="https://img.shields.io/coveralls/amphp/amp/master.svg?style=flat-square" valign="middle"></a>
<a href="blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" valign="middle"></a>
2019-09-21 21:02:47 +02:00
## Motivation
Traditionally, PHP has a synchronous execution flow, doing one thing at a time.
If you query a database, you send the query and wait for the response from the database server in a blocking manner.
Once you have the response, you can start doing the next thing.
Instead of sitting there and doing nothing while waiting, we could already send the next database query, or do an HTTP call to an API.
Making use of the time we usually spend on waiting for I/O can speed up the total execution time.
The following diagram shows the execution flow with dependencies between the different tasks, once executed sequentially and once concurrently.
![](docs/images/sequential-vs-concurrent.png)
Amp allows such concurrent I/O operations while keeping the cognitive load low by avoiding callbacks.
Instead, the results of asynchronous operations can be awaited using `yield` resulting in code which is structured like traditional blocking I/O code while the actual execution flow is handled by Amp.
2017-03-13 13:16:59 +01:00
## Installation
This package can be installed as a [Composer](https://getcomposer.org/) dependency.
```bash
2017-07-16 18:24:07 +02:00
composer require amphp/amp
2017-03-13 13:16:59 +01:00
```
2019-09-21 21:02:47 +02:00
This installs the basic building blocks for asynchronous applications in PHP.
We offer a lot of repositories building on top of this repository, e.g.
- [`amphp/byte-stream`](https://github.com/amphp/byte-stream) providing a stream abstraction
- [`amphp/socket`](https://github.com/amphp/socket) providing a socket layer for UDP and TCP including TLS
- [`amphp/parallel`](https://github.com/amphp/parallel) providing parallel processing to utilize multiple CPU cores and offload blocking operations
- [`amphp/http-client`](https://github.com/amphp/http-client) providing an HTTP/1.1 and HTTP/2 client
- [`amphp/http-server`](https://github.com/amphp/http-server) providing an HTTP/1.1 and HTTP/2 application server
- [`amphp/mysql`](https://github.com/amphp/mysql) and [`amphp/postgres`](https://github.com/amphp/postgres) for non-blocking database access
- and [many more packages](https://github.com/amphp?type=source)
## Documentation
Documentation can be found on [amphp.org](https://amphp.org/) as well as in the [`./docs`](./docs) directory.
2019-09-21 21:02:47 +02:00
Each packages has it's own `./docs` directory.
2017-03-13 13:16:59 +01:00
## Requirements
2013-08-05 22:05:08 +02:00
2019-09-21 21:02:47 +02:00
This package requires PHP 7.0 or later.
Many of the other packages raised their requirement to PHP 7.1.
No extensions required!
2015-07-22 06:06:02 +02:00
2019-09-21 21:02:47 +02:00
##### Optional Extensions
2015-07-22 06:06:02 +02:00
2019-09-21 21:02:47 +02:00
Extensions are only needed if your app necessitates a high numbers of concurrent socket connections, usually this limit is configured up to 1024 file descriptors.
2015-11-01 03:54:13 +01:00
2019-09-21 21:02:47 +02:00
- [`ev`](https://pecl.php.net/package/ev)
- [`event`](https://pecl.php.net/package/event)
- [`uv`](https://github.com/bwoebi/php-uv)
2015-05-12 21:18:28 +02:00
## Examples
2019-09-21 21:02:47 +02:00
Examples can be found in the [`./examples`](./examples) directory of this repository as well as in the `./examples` directory of [our other libraries](https://github.com/amphp?utf8=%E2%9C%93&q=&type=public&language=php).
2019-09-21 21:02:47 +02:00
## Versioning
2019-09-21 21:02:47 +02:00
`amphp/amp` follows the [semver](http://semver.org/) semantic versioning specification like all other `amphp` packages.
2014-08-07 07:35:17 +02:00
2019-09-21 23:23:56 +02:00
##### 2.x
2017-03-13 13:16:59 +01:00
2019-09-21 21:02:47 +02:00
Supported. We don't have plans to release v3, yet.
2017-03-13 13:16:59 +01:00
2019-09-21 23:23:56 +02:00
##### 1.x
2017-03-13 13:16:59 +01:00
2019-09-21 21:02:47 +02:00
No longer supported. We stopped providing bug fixes 2017-12-31 and stopped providing security fixes 2018-12-31.
2017-06-30 12:04:05 +02:00
2017-03-13 13:16:59 +01:00
## Compatible Packages
Compatible packages should use the [`amphp`](https://github.com/search?utf8=%E2%9C%93&q=topic%3Aamphp) topic on GitHub.
## Security
2019-09-21 21:02:47 +02:00
If you discover any security related issues, please email [`me@kelunik.com`](mailto:me@kelunik.com) instead of using the issue tracker.
2017-03-13 13:16:59 +01:00
## License
The MIT License (MIT). Please see [`LICENSE`](./LICENSE) for more information.