55* [ Overview] ( #overview )
66* [ Installation] ( #installation )
77* [ How to use] ( #how-to-use )
8+ * [ Using the status code] ( #status_code )
9+ * [ Creating a response] ( #response )
810* [ License] ( #license )
911* [ Contributing] ( #contributing )
1012
1113<div id =' overview ' ></div >
1214
1315## Overview
1416
15- Common implementations for HTTP protocol.
17+ Common implementations for HTTP protocol. The library exposes concrete implementations that follow the PSR standards,
18+ specifically designed to operate with [ PSR-7] ( https://www.php-fig.org/psr/psr-7 )
19+ and [ PSR-15] ( https://www.php-fig.org/psr/psr-15 ) , providing solutions for building HTTP responses, requests, and other
20+ HTTP-related components.
1621
1722<div id =' installation ' ></div >
1823
@@ -26,46 +31,95 @@ composer require tiny-blocks/http
2631
2732## How to use
2833
29- The library exposes concrete implementations for the HTTP protocol, such as status codes, methods, etc.
30-
31- ### Using the HttpCode
32-
33- The library exposes a concrete implementation through the ` HttpCode ` enum. You can get the status codes, and their
34- corresponding messages.
35-
36- ``` php
37- $httpCode = HttpCode::CREATED;
38-
39- $httpCode->name; # CREATED
40- $httpCode->value; # 201
41- $httpCode->message(); # 201 Created
42- ```
43-
44- ### Using the HttpMethod
45-
46- The library exposes a concrete implementation via the ` HttpMethod ` enum. You can get a set of HTTP methods.
47-
48- ``` php
49- $method = HttpMethod::GET;
50-
51- $method->name; # GET
52- $method->value; # GET
53- ```
54-
55- ### Using the HttpResponse
56-
57- The library exposes a concrete implementation for HTTP responses via the ` HttpResponse ` class. Responses are of the
58- [ ResponseInterface] ( https://github.com/php-fig/http-message/blob/master/src/ResponseInterface.php ) type, according to
59- the specifications defined in [ PSR-7] ( https://www.php-fig.org/psr/psr-7 ) .
60-
61- ``` php
62- $data = new Xyz(value: 10);
63- $response = HttpResponse::ok(data: $data);
64-
65- $response->getStatusCode(); # 200
66- $response->getReasonPhrase(); # 200 OK
67- $response->getBody()->getContents(); # {"value":10}
68- ```
34+ The library exposes interfaces like ` Headers ` and concrete implementations like ` Response ` , ` ContentType ` , and others,
35+ which facilitate construction.
36+
37+ <div id =' status_code ' ></div >
38+
39+ ### Using the status code
40+
41+ The library exposes a concrete implementation through the ` Code ` enum. You can retrieve the status codes, their
42+ corresponding messages, and check for various status code ranges using the methods provided.
43+
44+ - ** Get message** : Returns the [ HTTP status message] ( https://developer.mozilla.org/en-US/docs/Web/HTTP/Messages )
45+ associated with the enum's code.
46+
47+ ``` php
48+ use TinyBlocks\Http\Code;
49+
50+ Code::OK->message(); # 200 OK
51+ Code::IM_A_TEAPOT->message(); # 418 I'm a teapot
52+ Code::INTERNAL_SERVER_ERROR->message(); # 500 Internal Server Error
53+ ```
54+
55+ - ** Check if the code is valid** : Determines if the given code is a valid HTTP status code represented by the enum.
56+
57+ ``` php
58+ use TinyBlocks\Http\Code;
59+
60+ Code::isValidCode(code: 200); # true
61+ Code::isValidCode(code: 999); # false
62+ ```
63+
64+ - ** Check if the code is an error** : Determines if the given code is in the error range (** 4xx** or ** 5xx** ).
65+
66+ ``` php
67+ use TinyBlocks\Http\Code;
68+
69+ Code::isErrorCode(code: 500); # true
70+ Code::isErrorCode(code: 200); # false
71+ ```
72+
73+ - ** Check if the code is a success** : Determines if the given code is in the success range (** 2xx** ).
74+
75+ ``` php
76+ use TinyBlocks\Http\Code;
77+
78+ Code::isSuccessCode(code: 500); # false
79+ Code::isSuccessCode(code: 200); # true
80+ ```
81+
82+ <div id =' response ' ></div >
83+
84+ ### Creating a response
85+
86+ The library provides an easy and flexible way to create HTTP responses, allowing you to specify the status code,
87+ headers, and body. You can use the ` Response ` class to generate responses, and the result will always be a
88+ ` ResponseInterface ` from the PSR, ensuring compatibility with any framework that adheres
89+ to the [ PSR-7] ( https://www.php-fig.org/psr/psr-7 ) standard.
90+
91+ - ** Creating a response with a body** : To create an HTTP response, you can pass any type of data as the body.
92+ Optionally, you can also specify one or more headers. If no headers are provided, the response will default to
93+ ` application/json ` content type.
94+
95+ ``` php
96+ use TinyBlocks\Http\Response;
97+
98+ Response::ok(body: ['message' => 'Resource created successfully.']);
99+ ```
100+
101+ - ** Creating a response with a body and custom headers** : You can also add custom headers to the response. For instance,
102+ if you want to specify a custom content type or any other header, you can pass the headers as additional arguments.
103+
104+ ``` php
105+ use TinyBlocks\Http\Response;
106+ use TinyBlocks\Http\ContentType;
107+ use TinyBlocks\Http\CacheControl;
108+ use TinyBlocks\Http\ResponseCacheDirectives;
109+
110+ $body = 'This is a plain text response';
111+
112+ $contentType = ContentType::textPlain();
113+
114+ $cacheControl = CacheControl::fromResponseDirectives(
115+ maxAge: ResponseCacheDirectives::maxAge(maxAgeInWholeSeconds: 10000),
116+ staleIfError: ResponseCacheDirectives::staleIfError()
117+ );
118+
119+ Response::ok($body, $contentType, $cacheControl)
120+ ->withHeader(name: 'X-ID', value: 100)
121+ ->withHeader(name: 'X-NAME', value: 'Xpto');
122+ ```
69123
70124<div id =' license ' ></div >
71125
0 commit comments