Download the PHP package symplely/hyper without Composer

hyper

An simple advance PSR-7 implementation and asynchronous PSR-18 HTTP client using coroutines.

Table of Contents

• Introduction/Usage
• Functions
• Installation
• Usage/Historical
• Options
• Contributing
• License

Introduction/Usage

This package is based on coroutines using yield an generator, it requires our other repo package Coroutine. It's construction is inspired by and an overhaul of shuttle, an PSR-18 client.

There is a lot to be said about coroutines, but for an quick overview, checkout this video, if you have no formulary with the concept or construction. Only one thing to keep in mind when viewing the video, is that it's an overview of callbacks vs promises vs generators, an object given an async/await construction in other languages. And the Promise reference there, is referred here has as an Task, that returns a plain Integer.

This library and the whole Coroutine concept here, is base around NEVER having the user/developer directly accessing the Task, the Promise like object. For conceptually usage example see Advanced Asyncio: Solving Real World Production Problems.

From example's folder:

Functions

The functions listed here and in Core.php file is the recommended way to use this package. An functional programming approach is being used, the actual OOP class library used is constantly changing, but these calling functions will not.

Installation

Usage/Historical

Making requests: The easy old fashion way, with one caveat, need to be prefix with yield

The quickest and easiest way to begin making requests is to use the HTTP method name:

This library has built-in methods to support the major HTTP verbs: GET, POST, PUT, PATCH, DELETE, HEAD, and OPTIONS. However, you can make any HTTP verb request using the request method directly, that returns an PSR-7 RequestInterface.

Handling responses

Responses in Hyper implement PSR-7 ResponseInterface and as such are streamable resources.

Handling failed requests

This library will throw a RequestException by default if the request failed. This includes things like host name not found, connection timeouts, etc.

Responses with HTTP 4xx or 5xx status codes will not throw an exception and must be handled properly within your business logic.

Making requests: The PSR-7 way, with one caveat, need to be prefix with yield

If code reusability and portability is your thing, future proof your code by making requests the PSR-7 way. Remember, PSR-7 stipulates that Request and Response messages be immutable.

Options

The following options can be pass on each request.

• Authorization An array with key as either: auth_basic, auth_bearer, auth_digest, and value as password or token.
• Headers An array of key & value pairs to pass in with each request.
• Options An array of key & value pairs to pass in with each request.

Request bodies

An easy way to submit data with your request is to use the Body class. This class will automatically transform the data, convert to a BufferStream, and set a default Content-Type header on the request.

Pass one of the following CONSTANTS, onto the class constructor will:

• Body::JSON Convert an associative array into JSON, sets Content-Type header to application/json.
• Body::FORM Convert an associative array into a query string, sets Content-Type header to application/x-www-form-urlencoded.
• Body::XML Does no conversion of data, sets Content-Type header to application/xml.
• Body::FILE Does no conversion of data, will detect and set Content-Type header.
• Body::MULTI Does no conversion of data, sets Content-Type header to multipart/form-data.

To submit a JSON payload with a request:

Contributing

Contributions are encouraged and welcome; I am always happy to get feedback or pull requests on Github :) Create Github Issues for bugs and new features and comment on the ones you are interested in.

License

The MIT License (MIT). Please see License File for more information.