bittyphp/http

This package is abandoned and no longer maintained. No replacement package was suggested.

PSR-7 and PSR-17 HTTP implementation.

Maintainers

Details

github.com/bittyphp/http

Installs: 33 909

Dependents: 5

Suggesters: 0

Security: 0

Stars: 3

Watchers: 2

Forks: 2

This package has no released version yet, and little information is available.

README

Build Status Codacy Badge PHPStan Enabled Mutation Score Total Downloads License

A complete PSR-7 HTTP and PSR-17 HTTP Factory implementation.

Installation

It's best to install using Composer.

$ composer require bittyphp/http

Outline

Abstract Messages

All Request and Response classes share a base AbstractMessage class that provides methods for interacting with the headers and body of a message.

Available Methods

The following methods are available on all Request and Response objects:

getProtocolVersion()

Gets the HTTP protocol version as a string (e.g., "1.0" or "1.1").

withProtocolVersion($version)

Returns a new instance of the message with the given HTTP protocol version as a string (e.g., "1.0" or "1.1").

getHeaders()

Returns an array of the headers tied to the message. The array keys are the header names and each value is an array of strings for that header.

hasHeader($name)

Makes a case-insensitive comparison to see if the header name given exists in the headers of the message. Returns true if found, false if not.

getHeader($name)

Returns an array of strings for the values of the given case-insensitive header. If the header does not exist, it will return an empty array.

getHeaderLine($name)

Returns a comma-separated string of all the values of the given case-insensitive header. If the header does not exist, it will return an empty string.

withHeader($name, $value)

Returns a new instance of the message while replacing the given header with the value or values specified.

<?php

use Bitty\Http\ServerRequest;

$request = new ServerRequest(...);

$newRequest = $request->withHeader(
    'Content-Type',
    'text/html'
);

$newRequest = $request->withHeader(
    'Accept',
    ['application/json', 'application/xml']
);

withAddedHeader($name, $value)

Returns a new instance of the message while adding the given header with the value or values specified. Very similar to withHeader(), except it maintains all existing headers.

withoutHeader($name)

Returns a new instance of the message while completely removing the given header.

getBody()

Gets the body of the message in a Psr\Http\Message\StreamInterface format.

withBody($body)

Returns a new instance of the message using the given body. The body must be an instance of Psr\Http\Message\StreamInterface.

Requests

There are two types of requests: Request and ServerRequest. The Request class is used for outgoing requests, e.g. you send a request to another server. The ServerRequest class is used for incoming requests, e.g. someone makes a request to your website for you to process and respond to.

Unless you're building an HTTP client, you'll most likely only use the ServerRequest. Both are included because this library is a complete PSR-7 implementation.

Request

The Request class is used to build an outgoing, client-side request. Requests are considered immutable; all methods that change the state of the request return a new instance that contains the changes. The original request is always left unchanged.

Building a Request

The RequestFactory is the most consistent way to build a request, regardless of the framework being used. All PSR-17 implementations share this method signature.

<?php

use Bitty\Http\RequestFactory;
use Psr\Http\Message\RequestInterface;

$factory = new RequestFactory();

/** @var RequestInterface */
$request = $factory->createRequest('GET', '/some/path?foo=bar');

Alternatively, you can build the request manually.

<?php

use Bitty\Http\Request;

$method = 'GET';
$uri = 'http://example.com/';
$headers = ['Content-Type' => 'application/json'];
$body = '{"ping": "pong"}';
$protocolVersion = '1.1';

// All of the parameters are optional.
$request = new Request(
    $method,
    $uri,
    $headers,
    $body,
    $protocolVersion
);

Available Methods

In addition to all of the methods inherited from AbstractMessage, the following methods are available:

getRequestTarget()

Gets the message's request target as it will be seen for clients. In most cases, this will be the origin-form of the URI, unless a specific value has been provided. For example, if you request "http://example.com/search?q=test" then this will contain "/search?q=test").

withRequestTarget($requestTarget)

Returns a new instance with the message's request target, as given.

getMethod()

Gets the HTTP method of the request.

withMethod($method)

Returns a new instance with the message's HTTP method set as given. The method name should be uppercase, however it will not correct the capitalization for you.

getUri()

Gets the URI of the request as a Psr\Http\Message\UriInterface.

withUri($uri, $preserveHost = false)

Returns a new instance with the message's URI set as given. It must be given a Psr\Http\Message\UriInterface. If preserve host is set to true, it will not change the hostname of the request unless there isn't one already set.

ServerRequest

The ServerRequest class extends Request and is used to build an incoming, server-side request. Requests are considered immutable; all methods that change the state of the request return a new instance that contains the changes. The original request is always left unchanged.

Building a ServerRequest

The ServerRequestFactory is the most consistent way to build a request, regardless of the framework being used. All PSR-17 implementations share this method signature.

<?php

use Bitty\Http\ServerRequestFactory;
use Psr\Http\Message\ServerRequestInterface;

$factory = new ServerRequestFactory();

/** @var ServerRequestInterface */
$request = $factory->createServerRequest('GET', '/some/path?foo=bar');
$request = $factory->createServerRequest('GET', '/some/path?foo=bar', $serverParams);

Available Methods

In addition to all of the methods inherited from Request, the following methods are available:

getServerParams()

Gets the server parameters for the request. Typically this is the contents of the $_SERVER variable, but doesn't have to be.

withServerParams($params)

Returns a new instance of the request with the updated server parameters.

getCookieParams()

Gets the cookie parameters for the request. The return structure matches the format of what $_COOKIE provides.

withCookieParams($cookies)

Returns a new instance of the request with the updated cookie parameters. The $cookies parameter must match the structure that $_COOKIE provides.

getQueryParams()

Gets the query string parameters for the request. Typically this is the contents of the $_GET variable, but doesn't have to be. It's also possible for the query parameters to be out of sync with the URI query parameters, as setting one does not automatically set the other.

withQueryParams($query)

Returns a new instance of the request with the updated query parameters. Updating the query parameters will not automatically update the URI of the request.

getUploadedFiles()

Gets an array of normalized file uploads where each node of the array is a Psr\Http\Message\UploadedFileInterface.

withUploadedFiles($uploadedFiles)

Returns a new instance of the request with the given file tree. Each node of the array must be a Psr\Http\Message\UploadedFileInterface.

<?php

use Bitty\Http\ServerRequest;

$request = new ServerRequest(...);

// A simple list.
$newRequest = $request->withUploadedFiles(
    [
        'fileA' => $fileA,
        'fileB' => $fileB,
    ]
);

// A nested list.
$newRequest = $request->withUploadedFiles(
    [
        'images' => [
            'small' => $fileA,
            'large' => $fileB,
        ],
        'foo' => [
            'bar' => [
                'baz' => $fileC,
            ],
        ],
    ]
);
getParsedBody()

Gets the parameters of the request body. If the request Content-Type is either application/x-www-form-urlencoded or multipart/form-data, and the request method is POST, this method will return an array similar to $_POST. For other methods, such as PUT or PATCH, it will only parse the body if the Content-Type is application/x-www-form-urlencoded or application/json and then return the resulting array.

withParsedBody($body)

Returns a new instance of the request with the given parsed body. It only accepts array, object, or null values.

getAttributes()

Gets all custom attributes associated with the request. Attributes are application-specific data added to a request and can be anything, such as routing data or authentication flags.

getAttribute($name, $default = null)

Gets the given attribute for the request. If the attribute is not set, the default value will be returned.

withAttribute($name, $value)

Returns a new instance of the request with the given attribute set.

<?php

use Bitty\Http\ServerRequest;

$request = new ServerRequest(...);

// If you have a route such as /product/{id}
// And a request for /product/123
// You can set the 'id' attribute to the product ID
$newRequest = $request->withAttribute('id', 123);

// Some controller for the route
$controller = function ($request) {
    // Look up product data
    $productId = $request->getAttribute('id');
    $product = $someRepository->find($productId);

    // Do something with $product
};

$controller($newRequest);
withoutAttribute($name)

Returns a new instance of the request without the given attribute.

Responses

There are three response classes available, mainly for convenience, but they all extend Response.

Response

The Response class is used to return data to the client, typically in the form of HTML.

Building a Response

The ResponseFactory is the most consistent way to build a response, regardless of the framework being used. All PSR-17 implementations share this method signature.

<?php

use Bitty\Http\ResponseFactory;
use Psr\Http\Message\ResponseInterface;

$factory = new ResponseFactory();

/** @var ResponseInterface */
$response = $factory->createResponse();
$response = $factory->createResponse(404);
$response = $factory->createResponse(404, 'Not Found');

Or you can build one manually.

<?php

use Bitty\Http\Response;

// Defaults to a 200 OK response.
$response = new Response('Hello, world!');

// Use a given status code.
$response = new Response('', 204);

// Send custom headers.
$response = new Response(
    'Goodbye, world!',
    302,
    ['Location' => '/bye-bye']
);

Available Methods

In addition to all of the methods inherited from AbstractMessage, the following methods are available:

getStatusCode()

Can be used to get the HTTP status code of the response (e.g., 200 or 404).

getReasonPhrase()

Can be used to get the associated text for the status code (e.g., OK or Not Found).

withStatus()

Allows you to set the status and, optionally, the reason phrase of the response and returns the changes in a new response object.

<?php

use Bitty\Http\Response;

$response = new Response(...);

$newResponse = $response->withStatus(204);
$newResponse = $response->withStatus(204, 'No Content');

JsonResponse

The JsonResponse is a convenience extension of the Response class to make returning JSON data easier. It automatically encodes whatever data is given to it as JSON and sets the Content-Type header to application/json.

<?php

use Bitty\Http\JsonResponse;

// Defaults to a 200 OK response.
$response = new JsonResponse(['message' => 'Hello, world!']);

// Custom 404 response.
$response = new JsonResponse(
    ['error' => 'Page not found'],
    404
);

// Include additional headers.
$response = new JsonResponse(
    ['error' => 'Invalid credentials'],
    401,
    ['X-Auth' => 'Failed']
);

RedirectResponse

The RedirectResponse is a convenience extension of the Response class to make redirects easier. It automatically sets the Location header and includes a link in the body for the URI being redirected to.

<?php

use Bitty\Http\RedirectResponse;

// Defaults to a 302 redirect.
$redirect = new RedirectResponse('/some/path');

// Use a given status code.
$redirect = new RedirectResponse('/some/path', 301);

// Send custom headers.
$redirect = new RedirectResponse(
    '/some/path',
    302,
    ['X-Message' => 'Bye-bye']
);

File Uploads

The UploadedFile class attempts to fix issues with how PHP structures the $_FILES global.

Building an UploadedFile

The UploadedFileFactory is the most consistent way to build an UploadedFile, regardless of the framework being used. All PSR-17 implementations share this method signature.

<?php

use Bitty\Http\UploadedFileFactory;
use Psr\Http\Message\StreamInterface;
use Psr\Http\Message\UploadedFileInterface;

$factory = new UploadedFileFactory();

/** @var StreamInterface */
$stream = ...;

/** @var UploadedFileInterface */
$file = $factory->createUploadedFile($stream);
$file = $factory->createUploadedFile($stream, $size, $error, $clientFilename, $clientMediaType);

Available Methods

The following methods are available:

getStream()

Gets a Psr\Http\Message\StreamInterface representing the file upload.

moveTo($targetPath)

Moves the file to the target path. Internally, this uses move_uploaded_file() or rename(), depending on whether it's called in a SAPI or non-SAPI environment.

getSize()

Gets the size of the file.

getError()

Gets any error codes associated to the file. This will return one of the UPLOAD_ERR_* constants.

getClientFilename()

Gets the filename sent by the client. The value of this should not be trusted, as it can easily be faked.

getClientMediaType()

Gets the media type sent by the client. The value of this should not be trusted, as it can easily be faked.

Streams

Streams provide a standardized way of accessing streamable data, such as request/response bodies and file uploads. However, the might be useful in any other part of your code.

Building a Stream

The StreamFactory is the most consistent way to build a Stream, regardless of the framework being used. All PSR-17 implementations share this method signature.

<?php

use Bitty\Http\StreamFactory;
use Psr\Http\Message\StreamInterface;

$factory = new StreamFactory();

/** @var StreamInterface */
$stream = $factory->createStream('string of data');
$stream = $factory->createStreamFromFile('/path/to/file', 'r');
$stream = $factory->createStreamFromResource($resource);

Alternatively, you can build a Stream manually:

<?php

use Bitty\Http\Stream;

$stream = new Stream('string of data');
$stream = new Stream($resource);

Available Methods

The following methods are available:

close()

Closes the stream and any underlying resources.

detach()

Separates the underlying resource from the stream and returns it.

getSize()

Get the size of the stream, if known.

tell()

Returns the current position of the file pointer.

eof()

Returns true if the stream is at the end of the stream.

isSeekable()

Returns whether or not the stream is seekable.

seek($offset, $whence = SEEK_SET)

Seek to a position in the stream. $whence should be one of PHP' SEEK_* constants.

rewind()

Seek to the beginning of the stream.

isWritable()

Returns whether or not the stream is writable.

write($string)

Write data to the stream.

isReadable()

Returns whether or not the stream is readable.

read($length)

Read data from the stream.

getContents()

Returns the remaining contents of the stream.

getMetadata($key = null)

Get stream metadata as an associative array or retrieve a specific key. The keys returned are identical to the keys returned from PHP's stream_get_meta_data() function.

URIs

The Uri class makes working with URI values easier, as you can easily get or set only certain parts of the URI.

Building a Uri

The UriFactory is the most consistent way to build a Uri, regardless of the framework being used. All PSR-17 implementations share this method signature.

<?php

use Bitty\Http\UriFactory;
use Psr\Http\Message\UriInterface;

$factory = new UriFactory();

/** @var UriInterface */
$uri = $factory->createUri('/some/path?foo=bar');
$uri = $factory->createUri('https://example.com/search?q=test');

Alternatively, you can build a Uri manually:

<?php

use Bitty\Http\Uri;

$uri = new Uri('/some/path?foo=bar');
$uri = new Uri('https://example.com/search?q=test');

Available Methods

The following methods are available:

getScheme()

Retrieve the scheme component of the URI.

getAuthority()

Retrieve the authority component of the URI. The authority syntax of the URI is [user-info@]host[:port].

getUserInfo()

Retrieve the user information component of the URI. The syntax is username[:password].

getHost()

Retrieve the host component of the URI.

getPort()

Retrieve the port component of the URI. If the port is a standard port (e.g., 80 for HTTP or 443 for HTTPS), this will return null.

getPath()

Retrieve the path component of the URI.

getQuery()

Retrieve the query string of the URI.

getFragment()

Retrieve the fragment component of the URI.

withScheme($scheme)

Returns a new instance with the specified scheme.

withUserInfo($user, $password = null)

Returns a new instance with the specified user information.

withHost($host)

Returns a new instance with the specified host.

withPort($port)

Returns a new instance with the specified port.

withPath($path)

Returns a new instance with the specified path.

withQuery($query)

Returns a new instance with the specified query.

withFragment($fragment)

Returns a new instance with the specified fragment.