{"id":18407534,"url":"https://github.com/simplecomplex/php-http","last_synced_at":"2025-04-12T21:14:16.267Z","repository":{"id":57051261,"uuid":"104545205","full_name":"simplecomplex/php-http","owner":"simplecomplex","description":"High-level HTTP client and (Slim) service utility. Client provides response validation and mocking; service provides standardized and predictable responses. ","archived":false,"fork":false,"pushed_at":"2020-07-02T10:08:25.000Z","size":163,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-12T21:14:12.618Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simplecomplex.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.txt","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-23T05:59:00.000Z","updated_at":"2020-07-02T10:08:01.000Z","dependencies_parsed_at":"2022-08-24T05:10:43.166Z","dependency_job_id":null,"html_url":"https://github.com/simplecomplex/php-http","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplecomplex%2Fphp-http","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplecomplex%2Fphp-http/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplecomplex%2Fphp-http/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplecomplex%2Fphp-http/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simplecomplex","download_url":"https://codeload.github.com/simplecomplex/php-http/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248631682,"owners_count":21136562,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T03:14:24.822Z","updated_at":"2025-04-12T21:14:16.242Z","avatar_url":"https://github.com/simplecomplex.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Http ##\n\nHigh-level HTTP client and (Slim) service utility.  \nClient provides response validation and mocking.  \nService provides standardized and predictable responses.\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\n### ▹ Client ###\n\u003c/summary\u003e\n\n#### Request options ####\n\nThe ```HttpClient-\u003erequest()``` method accepts it's own options  \nas well as options for the underlying [RestMini Client](https://github.com/simplecomplex/restmini#client-options).\n\n##### Own options #####\n\n- (bool) **debug_dump**: log request and response\n- (bool|arr) **cacheable**: cache response/load response from [cache](https://github.com/simplecomplex/php-cache)\n- (bool|arr) **validate_response**: validate the response body against a [validation rule set](https://github.com/simplecomplex/php-validate)\n- (bool|arr) **mock_response**: don't send the request, return predefined mock response\n- (int) **retry_on_unavailable**: millisecs; try again later upon  \n     503 Service Unavailable|host not found|connection failed\n- (arr) **require_response_headers**: list of response header keys required\n- (bool) **err_on_endpoint_not_found**: err on 404 + HTML response\n- (bool) **err_on_resource_not_found**: err on 204 or 404 + JSON response\n- (arr) **log_warning_on_status**: key is status code, value is true\n\n##### Options processing #####\n\nApart from options passed directly to ```HttpClient-\u003erequest()```  \nthere may also exist settings (see [Config](https://github.com/simplecomplex/php-config)) for the:\n- **provider**: the service host\n- **service**: a group of endpoints\n- **endpoint**: the actual endpoint\n- **method**: literal HTTP method or an alias (like GET aliases index and retrieve)\n\nDuring request preparations settings and options get merged, so that  \n– _options_ override _method_ settings, which override _endpoint_ settings, which override... (you get it).  \nSounds like a lot of work, but it isn't really.\n\n\n  \u003cdetails\u003e\n  \u003csummary\u003e\n  \n  #### ▹▹ Client CLI commands ####\n  \u003c/summary\u003e\n\n##### (remote) Service configuration #####\n\n```bash\n# Show provider settings.\nphp cli.php config-get -a global http-provider.prvdr\n\n# Show service settings.\nphp cli.php config-get -a global http-service.prvdr.example-service\n\n# Show endpoint settings.\nphp cli.php config-get -a global http-endpoint.prvdr.example-service.ndpnt\n\n# Show method settings.\nphp cli.php config-get -a global http-method.prvdr.example-service.ndpnt.GET\n```\n\n##### Validation rule sets #####\n\n```bash\n# Show cached validation rule set.\nphp cli.php cache-get http-response_validation-rule-set prvdr.example-service.ndpnt.GET\n\n# Delete cached validation rule set.\nphp cli.php cache-delete http-response_validation-rule-set prvdr.example-service.ndpnt.GET\n```\n\n##### Mock responses #####\n\n```bash\n# Show cached mock response.\nphp cli.php cache-get http-response_mock prvdr.example-service.ndpnt.GET\n\n# Delete cached mock response.\nphp cli.php cache-delete http-response_mock prvdr.example-service.ndpnt.GET\n```\n  \u003c/details\u003e\n\n  \u003cdetails\u003e\n  \u003csummary\u003e\n  \n  #### ▹▹ Client error codes ####\n  \u003c/summary\u003e\n  \n  For every error code there's an equivalent prefab safe and user-friendly (localizable) error message.\n  \n  - ```unknown```: overall error fallback\n  - ```local-unknown```: local error fallback\n  - ```local-algo```: in-package logical error\n  - ```local-use```: invalid argument et al.\n  - ```local-configuration```: bad config var\n  - ```local-option```: bad option var\n  - ```local-init```: RestMini Client or cURL cannot request\n  - ```host-unavailable```: DNS or actually no such host\n  - ```service-unavailable```: status 503 Service Unavailable\n  - ```too-many-redirects```: too many redirects\n  - ```timeout```: cURL 504\n  - ```timeout-propagated```: status 504 Gateway Timeout\n  - ```response-none```: cURL 500 (RestMini Client 'response-false')\n  - ```remote```: status 500 Internal Server Error\n  - ```remote-propagated```: remote says 502 Bad Gateway\n  - ```malign-status-unexpected```: unsupported 5xx status\n  - ```endpoint-not-found```: status 404 + Content-Type not JSON (probably HTML); no such endpoint\n  - ```resource-not-found```: status 204, status 404 + Content-Type JSON; no such resource (object)\n  - ```remote-validation-bad```: 400 Bad Request \n  - ```remote-validation-failed```: 412 Precondition Failed, 422 Unprocessable Entity\n  - ```response-type```: content type mismatch\n  - ```response-format```: parse error\n  - ```benign-status-unexpected```: unsupported non-5xx status\n  - ```header-missing```: setting/option _require_response_headers_\n  - ```response-validation```: response body validation failure; service will send X-Http-Response-Invalid header\n  \n  \u003c/details\u003e\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\n### ▹ Service ###\n\u003c/summary\u003e\n\nProducing a service response is not as hard as requesting a remote service,  \nso the service part of **Http** is not as rich as the client part.  \nIt is assumed that one will simply echo something and send some headers\n– or use a service framework like [Slim](https://www.slimframework.com/).\n\nThe ```HttpServiceSlim``` class suggest means of interacting with Slim, and **Http** includes a simple example.\n@todo  \nAnd **Http** also provides a few other service utilities.\n\n#### Allowing Cross Origin requests ####\n\nPreferably only at development site. Necessary when developing Angular-based frontend.\n\nPlace a ```.cross_origin_allow_sites``` text file in document root, containing list allowed sites, like:  \n```http://localhost:4200,http://my-project.build.local.host:80```\n\n  \u003cdetails\u003e\n  \u003csummary\u003e\n  \n  #### ▹▹ Service error codes ####\n  \u003c/summary\u003e\n  \n  For every error code there's an equivalent prefab safe and user-friendly (localizable) error message.\n  \n  - ```unknown```: overall fallback\n  - ```request-unacceptable```: (some kind of) bad request; ```HttpResponseRequestUnacceptable```\n  - ```unauthenticated```: authentication (login) failure; ```HttpResponseRequestUnauthenticated```\n  - ```unauthorized```: authorization (permission) failure; ```HttpResponseRequestUnauthorized```\n  - ```request-validation```: request header/argument validation failure; ```HttpResponseRequestInvalid```\n  - ```frontend-response-format```: frontend only; parse error\n  - ```frontend-response-validation```: frontend only; response validation failure\n  \n  \u003c/details\u003e\n\n\u003c/details\u003e\n\n### Service and client combined ###\n\n#### Standardized wrapped response body ####\n\nA service requestor should never be in doubt whether a request to your service went alltogether well.  \n```HttpClient-\u003erequest()``` returns ```HttpResponse``` object:\n\n- status ```int```: suggested status to send to requestor\n- headers ```array```: suggested headers to send\n- body ```HttpResponseBody```\n  - **success** ```bool```\n  - **status** ```int```: status received from remote service\n  - **data** ```mixed|null```: that actual data (on success)\n  - **message** ```string|null```: safe and user-friendly message (on failure)\n  - **code** ```int```: error code (on failure), or optionally some other flag (on success)\n- originalHeaders ```array```: headers received – _not_ to be sent to requestor\n- validated ```bool|null```: whether the response was validated, and then the outcome\n\nThe general idea is to always send a response body containing _metadata_ about the procedings – success, status, code.  \nAnd – on failure – a prefab safe and user-friendly message, which the client can use to inform the visitor  \n(instead of just failing silently/ungracefully).\n\nWhen exposing a service that does a remote request, the service should however have access to more detailed info\nabout the remote request/response  \n– therefore the further wrapping in an object that suggests status and headers (et al.).\n\n\u003cdetails\u003e\n  \u003csummary\u003e\n  \n#### ▹ Service response headers ####\n\u003c/summary\u003e\n\n**Http** uses a number of custom response headers, to flag stuff to the client.  \nSome are issued by ```HttpClient``` upon every remote request (the original/final statuses).  \nOthers are only issued if a service uses/sends one of the prefab ```HttpResponse``` extensions.\n\n- \u003csup\u003e(int)\u003c/sup\u003e```X-Http-Original-Status```: status received from remote service (or interpretated ditto)\n- \u003csup\u003e(int)\u003c/sup\u003e```X-Http-Final-Status```: final status to be sent to client\n- ```X-Http-Response-Invalid```: response validation failure; ```HttpResponseResponseInvalid```\n- ```X-Http-Mock-Response```: ```HttpClient``` never called remote service; used prefab mock response\n- ```X-Http-Request-Invalid```: request header/argument validation failure; ```HttpResponseRequestInvalid```\n- ```X-Http-Request-Unacceptable```: (some kind of) bad request; ```HttpResponseRequestUnacceptable```\n- ```X-Http-Request-Unauthenticated```: authentication (login) failure; ```HttpResponseRequestUnauthenticated```\n- ```X-Http-Request-Unathorized```: authorization (permission) failure; ```HttpResponseRequestUnauthorized```\n\n\u003c/details\u003e\n\n### Requirements ###\n\n- PHP \u003e=7.0\n- [PSR-3 Log](https://github.com/php-fig/log)\n- [SimpleComplex Utils](https://github.com/simplecomplex/php-utils)\n- [SimpleComplex Cache](https://github.com/simplecomplex/php-cache)\n- [SimpleComplex Config](https://github.com/simplecomplex/php-config)\n- [SimpleComplex Locale](https://github.com/simplecomplex/php-locale)\n- [SimpleComplex Validate](https://github.com/simplecomplex/php-validate)\n- [SimpleComplex RestMini](https://github.com/simplecomplex/restmini)\n- [SimpleComplex Inspect](https://github.com/simplecomplex/inspect)\n\n#### Suggestions ####\n- [Slim](https://github.com/slimphp/Slim) \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimplecomplex%2Fphp-http","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimplecomplex%2Fphp-http","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimplecomplex%2Fphp-http/lists"}