566E PHP包仓库
首页 包列表 提交包 常见问题 关于

定制 philharmony/http-enum 二次开发

按需修改功能、优化性能、对接业务系统，提供一站式技术支持

邮箱：yvsm@zunyunkeji.com | QQ：316430983 | 微信：yvsm316

philharmony/http-enum

最新稳定版本：v1.3.0

Composer 安装命令：

composer require philharmony/http-enum

包简介

Type-safe HTTP enums for methods, status codes, headers, content types, schemes, caching and protocol utilities

关键字：

# php # http # enum # content-type # psr # cache-control # HTTP-header # samesite # http-method # status-code # content-encoding

README 文档

README

Validate Static Analysis Test codecov PHP Version Latest Stable Version Total Downloads License

Type-safe HTTP enums for PHP: methods, status codes, headers, content types, schemes and protocol utilities — designed for modern applications and libraries.

📖 Description

philharmony/http-enum provides a set of strictly typed, PSR-compliant enums for common HTTP concepts:

  • HttpMethod — standard HTTP request methods
  • StatusCode — HTTP status codes with semantic grouping
  • ContentType — common media types for responses and requests
  • Scheme — URI schemes with default port mapping (RFC 3986 compliant)
  • HttpHeader — common HTTP headers with semantic grouping and utilities
  • AuthScheme — HTTP authentication schemes (Basic, Bearer, Digest, OAuth, etc.)
  • HttpVersion — HTTP protocol versions with parsing utilities
  • CacheDirective — Cache-Control directives for HTTP caching behavior
  • ContentEncoding — HTTP compression algorithms (gzip, br, deflate, etc.)
  • SameSite — cookie SameSite policies for cross-site request protection

Built for clean, expressive, and safe code, this lightweight library requires PHP 8.1+ and has zero runtime dependencies.
It is ideal for frameworks, middleware, SDKs, and reusable components.

📚 Included Enums

  • HttpMethod
  • StatusCode
  • ContentType
  • Scheme
  • HttpHeader
  • AuthScheme
  • HttpVersion
  • CacheDirective
  • ContentEncoding
  • SameSite

✨ Why Use This Library?

Working with HTTP often involves raw strings and magic numbers:

if ($method === 'POST') { ... }
if ($status >= 400) { ... }
if ($header === 'Content-Type') { ... }

This library replaces them with type-safe enums:

if ($method === HttpMethod::POST) { ... }
if ($status->isError()) { ... }
if ($header === HttpHeader::CONTENT_TYPE) { ... }

Benefits:

  • ✅ Type safety — eliminates invalid values
  • ✅ Better IDE autocompletion
  • ✅ Self-documenting code
  • ✅ RFC-aligned semantics
  • ✅ Zero runtime dependencies

🚀 Features

  • 🧩 10 HTTP enums
  • ⚡ Zero dependencies
  • 🧬 Strict typing
  • 🔌 Framework agnostic
  • 🧠 Semantic helper methods
  • 📏 RFC-aligned behavior
  • ✅ Fully tested
  • 🧰 Developer-friendly utilities

📦 Installation

Install via Composer:

composer require philharmony/http-enum

⚙️ Requirements

  • PHP 8.1 or higher

🛠 Usage

HTTP Methods

use Philharmony\Http\Enum\HttpMethod;

$method = HttpMethod::POST;

if ($method->isSafe()) { /* Handle GET, HEAD... */ }
if ($method->isIdempotent()) { /* Handle PUT, DELETE... */ }
if ($method->isCacheable()) { /* Handle GET, HEAD */ }
if ($method->isReadOnly()) { /* Handle GET, HEAD, OPTIONS, TRACE */ }
if ($method->isWriteOnly()) { /* Handle POST, PUT, PATCH, DELETE, CONNECT */ }
if ($method->usuallyHasBody()) { /* POST, PUT, PATCH -> true, other false */ }
if ($method->allowsBody()) { /* POST, PUT, PATCH, DELETE -> true, other false */ }

Status Codes

use Philharmony\Http\Enum\StatusCode;

$status = StatusCode::NOT_FOUND;

if ($status->isInformational()) { /* 1xx */ }
if ($status->isSuccess()) { /* 2xx */ }
if ($status->isRedirection()) { /* 3xx */ }
if ($status->isClientError()) { /* 4xx */ }
if ($status->isServerError()) { /* 5xx */ }
if ($status->isError()) { /* 4xx and 5xx */ }
if ($status->isCacheable()) { /* Cacheable by default (RFC 9111) */ }
if ($status->statusClass() === 4) { /* client error */ }
if ($status->category() === 'server_error') { /* 5xx */ }
if ($status->phrase() === 'Not Found') { /* Semantic phrases */ }

echo StatusCode::NOT_FOUND->toStatusLine(); // 404 Not Found

Content Types

use Philharmony\Http\Enum\ContentType;

$contentType = ContentType::JSON;
header('Content-Type: ' . $contentType->value);

if ($contentType->isTextBased()) { /* Handle text-like responses (JSON, HTML, etc.) */ }
if ($contentType->isJson()) { /* Handle json types */ }
if ($contentType->isXml()) { /* Handle xml types */ }
if ($contentType->isImage()) { /* Handle image types */ }
if ($contentType->isAudio()) { /* Handle audio types */ }
if ($contentType->isVideo()) { /* Handle video types */ }
if ($contentType->isMedia()) { /* Handle audio, video and image types */ }
if ($contentType->isFont()) { /* Handle font types */ }
if ($contentType->isForm()) { /* Handle for form types */ }
if ($contentType->isBinary()) { /* Handle for binary types */ }
if ($contentType->isScript()) { /* Handle for script type */ }
if ($contentType->isArchive()) { /* Handle for archive type */ }
if ($contentType->isCompressible()) { /* Enable gzip/br compression */ }

$type = ContentType::fromHeader('application/json; charset=utf-8');
if ($type?->isJson()) { /* Handle JSON */ }

$type = ContentType::fromExtension('txt');
header('Content-Type: ' . $type->value);

$type = ContentType::fromExtension('.json');
header('Content-Type: ' . $type->value);

$type = ContentType::fromFilename('image.png');
header('Content-Type: ' . $type->value);

echo ContentType::JSON->baseType(); // 'json'
echo ContentType::MP4->category(); // 'video'
echo ContentType::JSON->is('application/json'); // true
echo ContentType::JSON->is('APPLICATION/JSON'); // true
echo ContentType::JSON->matches('application/*');  // true
echo ContentType::PNG->matches('image/*');        // true

$best = ContentType::negotiate(
    'application/json, text/html;q=0.9',
    [ContentType::JSON, ContentType::HTML, ContentType::XML]
);

URI Schemes & Ports

use Philharmony\Http\Enum\Scheme;

$scheme = Scheme::HTTPS;
echo $scheme->defaultPort(); // 443

if ($scheme->isSecure()) { /* Logic for secure connection (SSL/TLS) */ }
if ($scheme->requiresHost()) { /* Logic for requires host */ }
if ($scheme->isHttp()) { /* Handle HTTP, HTTPS */ }
if ($scheme->isWebSocket()) { /* Handle WS, WSS */ }
if ($scheme->isMail()) { /* Handle IMAP, POP, SMTP */ }
if ($scheme->isLdap()) { /* Handle LDAP, LDAPS */ }

HTTP Headers

use Philharmony\Http\Enum\HttpHeader;

$header = HttpHeader::CONTENT_TYPE;

if ($header->isContentHeader()) { /* Handle content headers */ }
if ($header->isCacheHeader()) { /* Handle caching logic */ }
if ($header->isAuthHeader()) { /* Handle authentication */ }
if ($header->isSecurityHeader()) { /* Sensitive headers */ }
if ($header->isCors()) { /* CORS headers */ }
if ($header->isProxy()) { /* Proxy / forwarded headers */ }
if ($header->isConditional()) { /* Conditional requests */ }

$header = HttpHeader::fromString('content-type');

echo $header->value; // Content-Type

// HttpHeader::X_FORWARDED_FOR
$header = HttpHeader::tryFromString('x-forwarded-for');

Authentication Schemes

use Philharmony\Http\Enum\AuthScheme;

$scheme = AuthScheme::fromHeader('Bearer token123');

if ($scheme?->isTokenBased()) { /* Handle Bearer or OAuth tokens */ }
if ($scheme?->isPasswordBased()) { /* Handle Basic or Digest authentication */ }
if ($scheme?->isChallengeBased()) { /* Handle challenge-response auth */ }

$scheme = AuthScheme::fromString('basic'); // AuthScheme::BASIC

HTTP Versions

use Philharmony\Http\Enum\HttpVersion;

$version = HttpVersion::HTTP_1_1;

echo $version->toProtocolString(); // HTTP/1.1

$version = HttpVersion::fromProtocol('HTTP/2');

if ($version === HttpVersion::HTTP_2) { /* HTTP/2 logic */ }

$version = HttpVersion::tryFromString('1.1');

Cache-Control Directives

use Philharmony\Http\Enum\CacheDirective;

$directive = CacheDirective::MAX_AGE;

if ($directive->isExpiration()) { /* max-age, s-maxage */ }
if ($directive->isRestriction()) { /* no-cache, no-store */ }
if ($directive->isVisibility()) { /* public, private */ }

$directive = CacheDirective::fromString('no-cache');
echo $directive->value; // no-cache

$directive = CacheDirective::tryFromString('public');

Content Encoding

use Philharmony\Http\Enum\ContentEncoding;

$encoding = ContentEncoding::fromString('gzip');

if ($encoding->isCompressed()) { /* Handle compressed response */ }

$encoding = ContentEncoding::tryFromString('br');

SameSite Cookie Policy

use Philharmony\Http\Enum\SameSite;

$sameSite = SameSite::STRICT;

if ($sameSite->isStrict()) { /* Strict cookie policy */ }
if ($sameSite->allowsCrossSite()) { /* Allows cross-site cookies */ }

$sameSite = SameSite::fromString('lax');

$sameSite = SameSite::tryFromString('none');

✨ Enum Methods

Each enum provides a set of utility methods for semantic checks, parsing, and grouping — enabling expressive, safe, and framework-agnostic HTTP handling.

🏷️ HttpMethod

Represents standard HTTP request methods as a backed enum (string).

Method Description
isSafe(): bool Returns true for safe methods: GET, HEAD, OPTIONS, TRACE
isIdempotent(): bool Returns true for idempotent methods: GET, HEAD, PUT, DELETE, OPTIONS, TRACE, CONNECT
isCacheable(): bool Returns true for cacheable methods: GET, HEAD
isReadOnly(): bool Returns true for read only methods: GET, HEAD, OPTIONS, TRACE
isWriteOnly(): bool Returns true for write only methods: POST, PUT, PATCH, DELETE, CONNECT
usuallyHasBody(): bool Returns true for methods that typically include a request body: POST, PUT, PATCH
allowsBody(): bool Returns true for write only methods: POST, PUT, PATCH, DELETE
isValid(string $method): bool Checks if the given string is a valid HTTP method (case-sensitive)
fromString(string $value) Creates an instance from a valid method string - used strtoupper for value and from()
tryFromString(string $value) Creates an instance from a valid method string - used strtoupper for value and tryFrom()
from(string $value) Built-in (PHP 8.1+) — creates an instance from a valid method string
tryFrom(string $value) Built-in (PHP 8.1+) — returns null if invalid

Example: HttpMethod::isValid('POST') → true Example: HttpMethod::tryFromString('post') → HttpMethod::POST

🔢 StatusCode

Represents HTTP status codes as a backed enum (int) with semantic grouping and standard reason phrases.

Method Description
isInformational(): bool 1xx (100–199)
isSuccess(): bool 2xx (200–299)
isRedirection(): bool 3xx (300–399)
isClientError(): bool 4xx (400–499)
isServerError(): bool 5xx (500–599)
isError(): bool 4xx or 5xx — indicates an error condition
phrase(): string Returns the standard reason phrase (e.g., OK → "OK", I_M_A_TEAPOT → "I'm a teapot")
toStatusLine(): string Returns full status line fragment like 404 Not Found
from(int $code) Built-in — creates from status code
tryFrom(int $code) Built-in — returns null if invalid

Static Group Methods (return StatusCode[]):

  • informational() — all 1xx
  • success() — all 2xx
  • redirection() — all 3xx
  • clientError() — all 4xx
  • serverError() — all 5xx
  • error() — all 4xx and 5xx

Example: StatusCode::NOT_FOUND->isClientError() → true

📝 ContentType

Represents media types as a backed enum (string) with parsing and detection utilities.

Method Description
isTextBased(): bool text/*, application/json, application/xml, application/javascript, etc.
isJson(): bool application/json, application/hal+json, application/problem+json, etc.
isXml(): bool application/xml, application/atom+xml, application/rss+xml, application/xhtml+xml, etc.
isImage(): bool image/*
isAudio(): bool audio/*
isVideo(): bool video/*
isMedia(): bool image/*, audio/*, video/*
isFont(): bool font/woff, font/woff2, font/ttf, font/otf
isForm(): bool application/x-www-form-urlencoded, multipart/form-data
isBinary(): bool Includes media, fonts, PDF, ZIP, Protobuf, etc.
isScript(): bool application/javascript
isArchive(): bool application/zip
isCompressible(): bool Returns true for types suitable for compression
defaultCharset(): ?string Returns default charset for text-like types (heuristic)
baseType(): string Returns base subtype (e.g. application/json → json)
category(): string Returns MIME category (e.g. json, image, video, audio, text)
is(): bool Case-insensitive exact match for MIME type
matches(): bool Pattern match like image/*, application/*
fromHeader(string $header): ?self Parses from Content-Type header (ignores parameters like ; charset=utf-8)
fromExtension(string $extension): ?self Maps file extension (e.g., .json, .png) to content type
fromFilename(string $filename): ?self Maps filename to content type by extension
negotiate(string $accept, array $available): ?self Chooses best type from Accept header (q + specificity)
from(string $value) Built-in — creates from MIME type
tryFrom(string $value) Built-in — returns null if invalid

Static Group Methods (return ContentType[]):

  • textBased(),
  • json(),
  • xml(),
  • image(),
  • audio(),
  • video(),
  • media(),
  • font(),
  • form(),
  • binary()

Example: ContentType::fromHeader('application/json; charset=utf-8') → ContentType::JSON

🌍 Scheme

Represents URI schemes as a backed enum (string) with port mapping.

Method Description
defaultPort(): ?int Returns standard port (e.g., HTTP → 80, HTTPS → 443, LDAPS → 636)
isSecure(): bool Returns true for secure protocols: HTTPS, WSS, SFTP, LDAPS, SSH
requiresHost(): bool Returns true for schemes that require a host: HTTP, HTTPS, WS, WSS, FTP, SFTP
isHttp(): bool Returns true for HTTP, HTTPS
isWebSocket(): bool Returns true for WS, WSS
isMail(): bool Returns true for SMTP, IMAP, POP
isLdap(): bool Returns true for LDAP, LDAPS
fromString(string $scheme) Creates enum from scheme string (case-insensitive, trims input)
tryFromString(string $scheme) Safe version returning null if invalid

📨 HttpHeader

Represents common HTTP headers as a backed enum (string) with semantic grouping and normalization utilities.

Method Description
isRequestHeader(): bool Returns true if header is typically used in HTTP requests
isResponseHeader(): bool Returns true if header is typically used in HTTP responses
isContentHeader(): bool Content-* headers (Content-Type, Content-Length, etc.)
isCors(): bool Access-Control-* headers
isProxy(): bool Proxy headers (X-Forwarded-*, X-Real-IP)
isCacheHeader(): bool Cache-related headers (Cache-Control, ETag, Expires, etc.)
isAuthHeader(): bool Authentication headers (Authorization, WWW-Authenticate, etc.)
isSecurityHeader(): bool Security-sensitive headers (Authorization, Cookie, Set-Cookie)
isConditional(): bool Conditional request headers (If-Match, If-None-Match, etc.)
isGeneralHeader(): bool General headers (Cache-Control, Connection, Date, etc.)
isRequestOnly(): bool Returns true if header is request-only (excludes response/general)
isResponseOnly(): bool Returns true if header is response-only (excludes general)
isHopByHop(): bool Hop-by-hop headers (RFC 7230, includes TE and Trailer)
fromString(string $header): self Creates enum from header name (case-insensitive, trims input)
tryFromString(string $header): ?self Safe version returning null if header is unknown
from(string $value) Built-in — creates from header string
tryFrom(string $value) Built-in — returns null if invalid

Example: HttpHeader::fromString('content-type') → HttpHeader::CONTENT_TYPE Example: HttpHeader::isRequestOnly() / HttpHeader::isResponseOnly() for request/response-only checks

🔐 AuthScheme

Represents HTTP authentication schemes used in the Authorization and WWW-Authenticate headers.

Method Description
isTokenBased(): bool Returns true for token-based authentication (Bearer, OAuth)
isChallengeBased(): bool Returns true for challenge-response schemes (Basic, Digest, Negotiate, HOBA, Mutual)
isPasswordBased(): bool Returns true for password-based schemes (Basic, Digest)
fromHeader(string $header): ?self Extracts authentication scheme from Authorization header (case-insensitive)
fromString(string $scheme) Creates enum from scheme name (case-insensitive, trims input)
tryFromString(string $scheme) Same as above but returns null if invalid
from(string $value) Built-in — creates enum from valid string
tryFrom(string $value) Built-in — returns null if invalid

Example: AuthScheme::fromHeader('Bearer token123') → AuthScheme::BEARER Example: AuthScheme::fromString('basic') → AuthScheme::BASIC

🌐 HttpVersion

Represents HTTP protocol versions.

✅ StatusCode Helpers

Method Description
statusClass(): int Returns the status code class (1..5)
category(): string Returns semantic category (success, etc.)
isCacheable(): bool Returns true if cacheable by default (RFC 9111)
Method Description
toProtocolString(): string Returns protocol string like HTTP/1.1, HTTP/2
fromProtocol(string $protocol) Parses version from protocol string (HTTP/1.1, HTTP/2)
fromString(string $version) Creates enum from version string (1.1, 2, 3)
tryFromString(string $version) Safe version returning null if invalid
from(string $value) Built-in — creates enum from version string
tryFrom(string $value) Built-in — returns null if invalid

Example: HttpVersion::fromProtocol('HTTP/1.1') → HttpVersion::HTTP_1_1

🗄️ CacheDirective

Represents Cache-Control directives used to control HTTP caching behavior.

Method Description
isRestriction(): bool Returns true for cache restrictions (no-cache, no-store)
isExpiration(): bool Returns true for expiration directives (max-age, s-maxage)
isVisibility(): bool Returns true for cache visibility (public, private)
fromString(string $directive) Creates enum from directive string (case-insensitive)
tryFromString(string $directive) Safe version returning null if directive is unknown
from(string $value) Built-in — creates enum from valid string
tryFrom(string $value) Built-in — returns null if invalid

Example: CacheDirective::fromString('no-cache') → CacheDirective::NO_CACHE

🗜 ContentEncoding

Represents compression algorithms used in Content-Encoding and Accept-Encoding headers.

Method Description
isCompressed(): bool Returns true for compression algorithms (all except identity)
fromString(string $encoding) Creates enum from encoding string
tryFromString(string $encoding) Safe version returning null if invalid
from(string $value) Built-in — creates enum from valid string
tryFrom(string $value) Built-in — returns null if invalid

🍪 SameSite

Represents cookie SameSite policies used in Set-Cookie headers to control cross-site request behavior.

Method Description
isStrict(): bool Returns true if policy is Strict
allowsCrossSite(): bool Returns true if cookies may be sent with cross-site requests
fromString(string $value) Creates enum from SameSite string
tryFromString(string $value) Safe version returning null if invalid
from(string $value) Built-in — creates enum from valid string
tryFrom(string $value) Built-in — returns null if invalid

📜 RFC Compliance

This library follows behavior defined in several HTTP specifications:

  • RFC 9110 — HTTP Semantics
  • RFC 9111 — HTTP Caching
  • RFC 9112 — HTTP/1.1
  • RFC 7231 — HTTP Methods
  • RFC 6265 — HTTP Cookies (SameSite)
  • RFC 6454 — Web Origin Concept

🧪 Testing

The package is strictly tested with PHPUnit 10 to ensure full compliance with HTTP standards and RFCs.

Run Tests

composer test

Code Coverage

composer test:coverage

🏗️ Static Analysis & Code Style

Verified with PHPStan Level 9 to ensure total type safety and prevent runtime errors.

composer phpstan

Check and fix code style (PSR-12):

composer cs-check
composer cs-fix

📄 License

This package is open-source and licensed under the MIT License. See the LICENSE file for details.

🤝 Contributing

Contributions, issues, and feature requests are welcome.

If you find a bug or have an idea for improvement, please open an issue or submit a pull request.

⭐ Support

If you find this package useful, please consider giving it a star on GitHub. It helps the project grow and reach more developers.

统计信息

  • 总下载量： 380
  • 月度下载量： 0
  • 日度下载量： 0
  • 收藏数： 1
  • 点击次数： 6
  • 依赖项目数： 2
  • 推荐数： 0

GitHub 信息

  • Stars： 1
  • Watchers： 0
  • Forks： 0
  • 开发语言： PHP
访问仓库

其他信息

  • 授权协议： MIT
  • 更新时间： 2026-02-16

承接程序开发

PHP开发

VUE

Vue开发

前端开发

小程序开发

公众号开发

系统定制

数据库设计

云部署

网站建设

安全加固