Skip to content

Commit 03c8275

Browse files
hollodotmehollodotme
committed
Update documentation, #53 
1 parent 035c24c commit 03c8275

File tree

1 file changed

+220
-5
lines changed

1 file changed

+220
-5
lines changed

‎README.md‎

Lines changed: 220 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ Please see the following links for earlier releases:
2020

2121
* PHP >= 7.0 (EOL) [v1.0.0], [v1.0.1], [v1.1.0], [v1.2.0], [v1.3.0], [v1.4.0], [v1.4.1], [v1.4.2]
2222
* PHP >= 7.1 [v2.0.0], [v2.0.1], [v2.1.0], [v2.2.0], [v2.3.0], [v2.4.0], [v2.4.1], [v2.4.2], [v2.4.3], [v2.5.0], [v2.6.0], [v2.7.0], [v2.7.1],
23-
[v2.7.2], [v3.0.0-alpha], [v3.0.0-beta]
23+
[v2.7.2], [v3.0.0-alpha], [v3.0.0-beta], [v3.0.0], [v3.0.1]
2424

2525
Read more about the journey to and changes in `v2.6.0` in [this blog post](https://github.com/hollodotme/fast-cgi-client/wiki/Background-Info-FastCgiClient-Version-2.6.0).
2626

@@ -522,7 +522,7 @@ Output: End
522522

523523
### Requests
524524

525-
Request are defined by the following interface:
525+
Requests are defined by the following interface:
526526

527527
```php
528528
<?php declare(strict_types=1);
@@ -531,6 +531,8 @@ namespace hollodotme\FastCGI\Interfaces;
531531

532532
interface ProvidesRequestData
533533
{
534+
public static function newWithRequestContent( string $scriptFilename, ComposesRequestContent $requestContent );
535+
534536
public function getGatewayInterface() : string;
535537

536538
public function getRequestMethod() : string;
@@ -594,6 +596,217 @@ The abstract request class defines several default values which you can optional
594596
| REQUEST_URI | <empty string> | |
595597
| CUSTOM_VARS | empty array | You can use the methods `setCustomVar`, `addCustomVars` to add own key-value pairs |
596598

599+
#### Request contents
600+
601+
In order to make the composition of different request content types easier there are classes covering the
602+
typical content types:
603+
604+
* [UrlEncodedFormData](./src/RequestContents/UrlEncodedFormData.php)
605+
* [MultipartFormData](./src/RequestContents/MultipartFormData.php)
606+
* [JsonData](./src/RequestContents/JsonData.php)
607+
608+
You can create your own request content type composer by implementing the following interface:
609+
610+
[**ComposesRequestContent**](./src/Interfaces/ComposesRequestContent.php)
611+
```php
612+
interface ComposesRequestContent
613+
{
614+
public function getContentType() : string;
615+
616+
public function getContent() : string;
617+
}
618+
```
619+
620+
##### Request content example: URL encoded form data (application/x-www-form-urlencoded)
621+
622+
```php
623+
<?php declare(strict_types=1);
624+
625+
use hollodotme\FastCGI\RequestContents\UrlEncodedFormData;
626+
use hollodotme\FastCGI\SocketConnections\NetworkSocket;
627+
use hollodotme\FastCGI\Requests\PostRequest;
628+
use hollodotme\FastCGI\Client;
629+
630+
$client = new Client();
631+
$connection = new NetworkSocket( '127.0.0.1', 9000 );
632+
633+
$urlEncodedContent = new UrlEncodedFormData(
634+
[
635+
'nested' => [
636+
'one',
637+
'two' => 'value2',
638+
'three' => [
639+
'value3',
640+
],
641+
],
642+
]
643+
);
644+
645+
$postRequest = PostRequest::newWithRequestContent( '/path/to/target/script.php', $urlEncodedContent );
646+
647+
$response = $client->sendRequest( $connection, $postRequest );
648+
```
649+
650+
This example produces the following `$_POST` array at the target script:
651+
652+
```
653+
Array
654+
(
655+
[nested] => Array
656+
(
657+
[0] => one
658+
[two] => value2
659+
[three] => Array
660+
(
661+
[0] => value3
662+
)
663+
664+
)
665+
)
666+
```
667+
668+
##### Request content example: multipart form data (multipart/form-data)
669+
670+
Multipart form-data can be used to transfer any binary data as files to the target script just like a file upload in a browser does.
671+
672+
**PLEASE NOTE:** Multipart form-data content type works with POST requests only.
673+
674+
```php
675+
<?php declare(strict_types=1);
676+
677+
use hollodotme\FastCGI\RequestContents\MultipartFormData;
678+
use hollodotme\FastCGI\SocketConnections\NetworkSocket;
679+
use hollodotme\FastCGI\Requests\PostRequest;
680+
use hollodotme\FastCGI\Client;
681+
682+
$client = new Client();
683+
$connection = new NetworkSocket( '127.0.0.1', 9000 );
684+
685+
$multipartContent = new MultipartFormData(
686+
# POST data
687+
[
688+
'simple' => 'value',
689+
'nested[]' => 'one',
690+
'nested[two]' => 'value2',
691+
'nested[three][]' => 'value3',
692+
],
693+
# FILES
694+
[
695+
'file1' => __FILE__,
696+
'files[1]' => __FILE__,
697+
'files[three]' => __FILE__,
698+
]
699+
);
700+
701+
$postRequest = PostRequest::newWithRequestContent( '/path/to/target/script.php', $multipartContent );
702+
703+
$response = $client->sendRequest( $connection, $postRequest );
704+
```
705+
706+
This example produces the following `$_POST` and `$_FILES` array at the target script:
707+
708+
```
709+
# $_POST
710+
Array
711+
(
712+
[simple] => value
713+
[nested] => Array
714+
(
715+
[0] => one
716+
[two] => value2
717+
[three] => Array
718+
(
719+
[0] => value3
720+
)
721+
722+
)
723+
724+
)
725+
726+
# $_FILES
727+
Array
728+
(
729+
[file1] => Array
730+
(
731+
[name] => multipart.php
732+
[type] => application/octet-stream
733+
[tmp_name] => /tmp/phpiIdCNM
734+
[error] => 0
735+
[size] => 1086
736+
)
737+
738+
[files] => Array
739+
(
740+
[name] => Array
741+
(
742+
[1] => multipart.php
743+
[three] => multipart.php
744+
)
745+
746+
[type] => Array
747+
(
748+
[1] => application/octet-stream
749+
[three] => application/octet-stream
750+
)
751+
752+
[tmp_name] => Array
753+
(
754+
[1] => /tmp/phpAjHINL
755+
[three] => /tmp/phpicAmjN
756+
)
757+
758+
[error] => Array
759+
(
760+
[1] => 0
761+
[three] => 0
762+
)
763+
764+
[size] => Array
765+
(
766+
[1] => 1086
767+
[three] => 1086
768+
)
769+
770+
)
771+
772+
)
773+
```
774+
775+
##### Request content example: JSON encoded data (application/json)
776+
777+
```php
778+
<?php declare(strict_types=1);
779+
780+
use hollodotme\FastCGI\RequestContents\JsonData;
781+
use hollodotme\FastCGI\SocketConnections\NetworkSocket;
782+
use hollodotme\FastCGI\Requests\PostRequest;
783+
use hollodotme\FastCGI\Client;
784+
785+
$client = new Client();
786+
$connection = new NetworkSocket( '127.0.0.1', 9000 );
787+
788+
$jsonContent = new JsonData(
789+
[
790+
'nested' => [
791+
'one',
792+
'two' => 'value2',
793+
'three' => [
794+
'value3',
795+
],
796+
],
797+
]
798+
);
799+
800+
$postRequest = PostRequest::newWithRequestContent( '/path/to/target/script.php', $jsonContent );
801+
802+
$response = $client->sendRequest( $connection, $postRequest );
803+
```
804+
805+
This example produces the following content for `php://input` at the target script:
806+
807+
```json
808+
{"nested":{"0":"one","two":"value2","three":["value3"]}}
809+
```
597810

598811
### Responses
599812

@@ -758,7 +971,7 @@ if ('File not found.' === trim($response->getBody()))
758971

759972
## Run examples
760973

761-
docker-compose exec php73 php bin/examples.php
974+
docker-compose exec php74 php bin/examples.php
762975

763976
## Run all tests
764977

@@ -768,15 +981,17 @@ if ('File not found.' === trim($response->getBody()))
768981

769982
Run a call through a network socket:
770983

771-
docker-compose exec php73 php bin/fcgiget localhost:9001/status
984+
docker-compose exec php74 php bin/fcgiget localhost:9001/status
772985

773986
Run a call through a Unix Domain Socket
774987

775-
docker-compose exec php73 php bin/fcgiget unix:///var/run/php-uds.sock/status
988+
docker-compose exec php74 php bin/fcgiget unix:///var/run/php-uds.sock/status
776989

777990
This shows the response of the php-fpm status page.
778991

779992

993+
[v3.0.1]: https://github.com/hollodotme/fast-cgi-client/blob/v3.0.1/README.md
994+
[v3.0.0]: https://github.com/hollodotme/fast-cgi-client/blob/v3.0.0/README.md
780995
[v3.0.0-beta]: https://github.com/hollodotme/fast-cgi-client/blob/v3.0.0-beta/README.md
781996
[v3.0.0-alpha]: https://github.com/hollodotme/fast-cgi-client/blob/v3.0.0-alpha/README.md
782997
[v2.7.2]: https://github.com/hollodotme/fast-cgi-client/blob/v2.7.2/README.md

0 commit comments

Comments
 (0)