Http Laravel Package

Getting Started

yiisoft/http is a constants-only utility package: no service provider, no config, no runtime behavior. It gives you Yiisoft\Http\Method, Yiisoft\Http\StatusCode, and (depending on version) Yiisoft\Http\Header classes full of public const values.

composer require yiisoft/http

Where to look first:

1. vendor/yiisoft/http/src/Method.php — HTTP verb constants (Method::GET, Method::POST, …).
2. vendor/yiisoft/http/src/StatusCode.php — status code constants (StatusCode::OK, StatusCode::NOT_FOUND, …).
3. composer.json — confirm the PHP version floor and whether Header is included in your installed tag.

First use case: replace magic strings and integers in HTTP-facing code. For example, a middleware that only accepts POST:

use Yiisoft\Http\Method;
use Yiisoft\Http\StatusCode;

public function handle(Request $request, Closure $next)
{
    if (! $request->isMethod(Method::POST)) {
        return response()->json(['error' => 'Method Not Allowed'], StatusCode::METHOD_NOT_ALLOWED);
    }

    return $next($request);
}

That is the honest scope of the package. It will not change how Laravel routes, validates, or responds — it only makes the literals self-documenting and greppable.

Implementation Patterns

Controller responses. Use status constants where you already return integer codes, especially for non-200 responses:

return response()->json($resource, StatusCode::CREATED);
return response()->noContent(StatusCode::NO_CONTENT);

Middleware and guards. Method constants read better than strings and pair naturally with Laravel's isMethod():

if ($request->isMethod(Method::PUT) || $request->isMethod(Method::PATCH)) {
    // ...
}

Route definitions. Laravel's router accepts string verbs, so Route::match([Method::GET, Method::HEAD], ...) works, but it is marginal value because the router already validates verbs. Use it only if your team wants one vocabulary across routes, middleware, and tests.

Tests. Constants make assertions less ambiguous:

$response->assertStatus(StatusCode::UNPROCESSABLE_ENTITY);

This is arguably the highest-value place to adopt the package — test suites accumulate a lot of bare 422, 404, 201.

Custom exception handler / API error mapping. Centralize a mapping from domain exceptions to status constants so the handler reads declaratively:

protected $statusMap = [
    ModelNotFoundException::class => StatusCode::NOT_FOUND,
    ValidationException::class   => StatusCode::UNPROCESSABLE_ENTITY,
];

CORS and header middleware. If your installed version ships Header, use its constants when building Access-Control-Allow-Methods / Allow values or comparing incoming headers. Verify the class exists before depending on it; do not assume parity with every header name you need.

Gradual adoption. There is no migration cost, so introduce it file-by-file. A practical rule: adopt it in new middleware, API controllers, and tests; leave existing form requests and Blade alone rather than churning diffs.

Static analysis. The real payoff in a large Laravel codebase is PHPStan/Psalm catching a typo like StatusCode::NOT_FOUNDD at analysis time instead of at runtime. If you already run static analysis in CI, this package becomes more attractive.

Gotchas and Tips

• Overlap with Symfony. Laravel already ships Symfony\Component\HttpFoundation\Response::HTTP_OK and Request::METHOD_GET. Do not mix both vocabularies in one codebase — pick one and enforce it with a code-review note or a PHP-CS-Fixer rule.
• Naming differs from Symfony. StatusCode::NOT_FOUND vs Response::HTTP_NOT_FOUND; Method::GET vs Request::METHOD_GET. Copy-pasting between the two will produce undefined-constant errors.
• Constants only, no helpers. Do not expect StatusCode::isSuccess() or similar predicates. If you want isSuccessful($code), write a small helper or use Symfony's Response::isSuccessful().
• No Laravel integration surface. There is no facade, config file, or package discovery entry. If you see auto-discovery output, it is coming from something else.
• Header class availability. Yiisoft\Http\Header may not exist, or may not cover every header you need, depending on the tagged version. Check src/ before writing code against it, and be prepared to fall back to literals.
• PSR-7 vs Laravel header casing. Laravel normalizes header names differently than PSR-7 implementations. Header-name constants are still just strings; they do not fix case-sensitivity mismatches in $request->header() lookups.
• Maintenance risk is low but real. ~29 stars and a single-maintainer ecosystem (Yii) means you should not expect rapid additions. Because the package is only constants, the blast radius of abandonment is effectively zero — vendor it mentally as "a typed list of numbers."
• Debugging. If a constant is undefined, run composer show yiisoft/http to confirm the installed version, then grep -n "const YOUR_NAME" vendor/yiisoft/http/src/*.php. There is nothing else to debug.
• Extension point. There is none. If you need project-specific codes (e.g., StatusCode::TEAPOT is there, but custom 4xx business codes are not), define your own App\Http\Status class and optionally reference the package constants inside it.
• Recommendation. Worth adding if your team writes a lot of raw status integers and wants one consistent vocabulary; skip it if you already standardize on Symfony's constants. It is a readability and static-analysis convenience, not an architectural decision.