{"id":21036430,"url":"https://github.com/nimbly/capsule","last_synced_at":"2025-05-15T14:31:46.634Z","repository":{"id":49475712,"uuid":"179744210","full_name":"nimbly/Capsule","owner":"nimbly","description":"Capsule is a simple PSR-7 HTTP message interface and PSR-17 HTTP factory implementation.","archived":false,"fork":false,"pushed_at":"2025-02-27T01:12:27.000Z","size":215,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-18T17:00:40.856Z","etag":null,"topics":["http-messages","http-requests","http-response","psr-17","psr-7"],"latest_commit_sha":null,"homepage":"","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/nimbly.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-04-05T19:40:51.000Z","updated_at":"2025-02-27T01:12:30.000Z","dependencies_parsed_at":"2024-12-10T20:28:23.095Z","dependency_job_id":null,"html_url":"https://github.com/nimbly/Capsule","commit_stats":{"total_commits":130,"total_committers":2,"mean_commits":65.0,"dds":0.007692307692307665,"last_synced_commit":"96b93df674ff8acb4f589f2cf56b3f45a84012f5"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nimbly%2FCapsule","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nimbly%2FCapsule/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nimbly%2FCapsule/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nimbly%2FCapsule/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nimbly","download_url":"https://codeload.github.com/nimbly/Capsule/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254358803,"owners_count":22057982,"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":["http-messages","http-requests","http-response","psr-17","psr-7"],"created_at":"2024-11-19T13:19:56.715Z","updated_at":"2025-05-15T14:31:46.625Z","avatar_url":"https://github.com/nimbly.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Capsule\n\n[![Latest Stable Version](https://img.shields.io/packagist/v/nimbly/capsule.svg?style=flat-square)](https://packagist.org/packages/nimbly/capsule)\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/nimbly/capsule/coverage.yml?style=flat-square)](https://github.com/nimbly/Capsule/actions/workflows/coverage.yml)\n[![Codecov branch](https://img.shields.io/codecov/c/github/nimbly/capsule/master?style=flat-square)](https://app.codecov.io/github/nimbly/Capsule)\n[![License](https://img.shields.io/github/license/nimbly/capsule.svg?style=flat-square)](https://packagist.org/packages/nimbly/capsule)\n\nCapsule is a simple [PSR-7](https://www.php-fig.org/psr/psr-7/) HTTP message interface and [PSR-17](https://www.php-fig.org/psr/psr-17) HTTP factory implementation.\n\n## Install\n```bash\ncomposer require nimbly/capsule\n```\n\n## HTTP Message (PSR-7)\n\n### Request\n\nThe `Request` object represents an *outbound* HTTP request your application would like to make, typically to be used with a PSR-18 compliant HTTP client.\n\n```php\n$request = new Request(\"get\", \"https://example.org/books\");\n\n$response = $httpClient-\u003esendRequest($request);\n```\n\n### ServerRequest\n\nThe `ServerRequest` object represents an *incoming* HTTP request into your application, to be used with a PSR-7 compliant HTTP framework or other library.\n\n```php\n$serverRequest = new ServerRequest(\"get\", \"https://example.org/books\");\n\n$response = $framework-\u003edispatch($serverRequest);\n```\n\n#### Creating from globals\n\nTypically, you will want to create a `ServerRequest` instance from the PHP globals space (`$_SERVER`, `$_POST`, `$_GET`, `$_FILES`, and `$_COOKIES`) for your incoming requests. The `ServerRequestFactory` provides a static method to create such an instance.\n\n```php\n$serverRequest = ServerRequestFactory::createFromGlobals();\n\n$response = $framework-\u003edispatch($serverRequest);\n```\n#### Helpers\n\nThe `ServerRequest` instance offers helpers to test for and access various request property parameters.\n\n#### Parsed body helpers\n\n```php\nif( $serverRequest-\u003ehasBodyParam(\"foo\") ){\n\t// Do the foo...\n}\n\n/**\n * Get a single param (\"bar\") from the parsed body.\n */\n$bar = $serverRequest-\u003egetBodyParam(\"bar\");\n\n/**\n * Get *only* the provided params from the parsed body.\n */\n$serverRequest-\u003eonlyBodyParams([\"foo\", \"bar\"]);\n\n/**\n * Get all params from the parsed body *except* those provided.\n */\n$serverRequest-\u003eexceptBodyParams([\"foo\", \"bar\"]);\n```\n\n#### Query param helpers\n\n```php\nif( $serverRequest-\u003ehasQueryParam(\"foo\") ){\n\t// Do the foo...\n}\n\n$foo = $serverRequest-\u003egetQueryParam(\"foo\");\n```\n\n#### Uploaded file helpers\n\n```php\nif( $serverRequest-\u003ehasUploadedFile(\"avatar\") ){\n\t// Do something\n}\n\n$avatar = $serverRequest-\u003egetUploadedFile(\"avatar\");\n```\n\n### Response\n\nThe `Response` object represents an HTTP response to either a `Request` or a `ServerRequest` action.\n\n```php\n$response = new Response(200, \\json_encode([\"foo\" =\u003e \"bar\"]), [\"Content-Type\" =\u003e \"application/json\"]);\n```\n\n### Response Status\n\nCapsule provides a `ResponseStatus` enum with HTTP response codes and reason phrases.\n\n```php\n$response = new Response(ResponseStatus::NOT_FOUND));\n```\n\n```php\n$phrase = ResponseStatus::NOT_FOUND-\u003egetPhrase();\n\necho $phrase; // Outputs \"Not Found\"\n```\n\n## HTTP Factory (PSR-17)\n\nCapsule includes a set of PSR-17 factory classes to be used to create `Request`, `ServerRequest`,  `Response`, `Stream`, `UploadedFile`, and `Uri` instances, found in the `Nimbly\\Capsule\\Factory` namespace. These factories are typically used with other libraries that are PSR-7 agnostic. They're also useful for creating mocked instances in unit testing.\n\n### RequestFactory\n```php\n$requestFactory = new RequestFactory;\n$request = $requestFactory-\u003ecreateRequest(\"get\", \"https://api.example.com\");\n```\n\n### ServerRequestFactory\n```php\n$serverRequestFactory = new ServerRequestFactory;\n$serverRequest = $serverRequestFactory-\u003ecreateServerRequest(\"post\", \"https://api.example.com/books\");\n```\n\nIn addition, the `ServerRequestFactory` provides several static methods for creating server requests.\n\n#### Creating ServerRequest from PHP globals\nYou can create a `ServerRequest` instance from the PHP globals space ($_POST, $_GET, $_FILES, $_SERVER, and $_COOKIES).\n\n```php\n$serverRequest = ServerRequestFactory::createFromGlobals();\n```\n\n#### Creating ServerRequest from another PSR-7 ServerRequest\nYou can create a Capsule `ServerRequest` instance from another PSR-7 ServerRequest instance:\n\n```php\n$serverRequest = ServerRequestFactory::createServerRequestFromPsr7($otherServerRequest);\n```\n\n### ResponseFactory\n\n```php\n$responseFactory = new ResponseFactory;\n$response = $responseFactory-\u003ecreateResponse(404);\n```\n\n### StreamFactory\n\n#### Create a stream from string content\n\n```php\n$streamFactory = new StreamFactory;\n$stream = $streamFactory-\u003ecreateStream(\\json_encode($body));\n```\n\n#### Create a stream from a file\n\n```php\n$streamFactory = new StreamFactory;\n$stream = $streamFactory-\u003ecreateStreamFromFile(\"/reports/q1.pdf\");\n```\n\n#### Create a stream from any resource\n\n```php\n$resource = \\fopen(\"https://example.com/reports/q1.pdf\", \"r\");\n\n$streamFactory = new StreamFactory;\n$stream = $streamFactory-\u003ecreateStreamFromResource($resource);\n```\n\nAlternatively, these methods are also available statically:\n\n```php\n// Create a stream from a string.\n$stream = StreamFactory::createFromString(\\json_encode($body));\n\n// Create a stream from a local file.\n$stream = StreamFactory::createFromFile(\"/reports/q1.pdf\");\n\n// Create a stream from a PHP resource.\n$resource = \\fopen(\"https://example.com/reports/q1.pdf\", \"r\");\n$stream = StreamFactory::createFromResource($resource);\n```\n\n### UploadedFileFactory\n\n#### Create an UploadedFile instance\n```php\n$uploadedFileFactory = new UploadedFileFactory;\n\n$stream = StreamFactory::createFromFile(\"/tmp/upload\");\n\n$uploadedFile = $uploadedFileFactory-\u003ecreateUploadedFile(\n    $stream,\n    $stream-\u003egetSize(),\n    UPLOAD_ERR_OK,\n    \"q1_report.pdf\",\n    \"application/pdf\"\n);\n```\n\n### UriFactory\n\nThe `UriFactory` allows you to create and parse URIs.\n\n```php\n$uriFactory = new UriFactory;\n$uri = $uriFactory-\u003ecreateUri(\"https://api.example.com/v1/books?a=Kurt+Vonnegut\");\n```\n\nThis method is also available statically:\n\n```php\n$uri = UriFactory::createFromString(\"https://api.example.com/v1/books?a=Kurt+Vonnegut\");","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnimbly%2Fcapsule","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnimbly%2Fcapsule","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnimbly%2Fcapsule/lists"}