Hướng dẫn dùng rfc 3986 trong PHP

Các thông điệp HTTP là căn bản của việc lập trình web. Trình duyệt web và các HTTP client như là cURL tạo các thông điệp HTTP với mục đích yêu câu để gửi về server, khi đó server sẽ trả về thông điệp phản hồi. Phias server sẽ nhận các yêu cầu và gửi trả phản hồi.

Các thông điệp HTTP thường được ẩn đi đối với người dùng cuối, nhưng với tư cách là nhà phát triển, chúng ta cần hiểu được cấu trúc và cách thức nó hoạt động và các để truy cập hoặc điều khiển các thông điệp ấy để thực hiện các nhiệm vụ, có thể là gửi yêu cầu tới 1 HTTP API hoặc là tiếp nhận 1 yêu cầu được gửi đến.

Các thông điệp HTTP đều có 1 định dạng sau

POST /path HTTP/1.1
Host: example.com

foo=bar&baz=bat

Dòng đầu tiên của thông điệp là dòng "reuquest line"[dòng yêu cầu], chứa các thành phần sau theo thứ tự: phương thức request HTTP, mục tiêu của yêu cầu[thường là 1 URI hoặc là 1 đường dẫn ở web server] và phiên bản của thủ tục HTTP. Tiếp theo dòng đó sẽ là 1 hay nhiều HTTP header, dòng trống và cuối cùng là thân của thông điệp.

Thông điệp phản hồi có định dạng tương tự:

HTTP/1.1 200 OK
Content-Type: text/plain

This is the response body

Dòng đầu tiên là "trạng thái", chứa các thành phần sau theo thứ tự: phiên bản của thủ tục HTTP, mã trạng thái của HTTP, dòng "lí do", mô tả đọc được với người của mã HTTP. Tiếp theo dòng đó sẽ là 1 hay nhiều HTTP header, dòng trống và cuối cùng là thân của thông điệp y như thông điệp yêu cầu bên trên.

Các interface mô tả trong document này đều về các cách trừu tượng hóa thông điệp HTTP và các phần tử chứa đựng chúng.

Đặc tả

Thông điệp

1 thông điệp HTTP có thể là yêu cầu từ client tới server hoặc phản hồi cỉa server cho client. Đây là định nghĩa cho các interface cho thông điệp HTTP là Psr\Http\Message\RequestInterface và Psr\Http\Message\ResponseInterface.

Cả Psr\Http\Message\RequestInterface và Psr\Http\Message\ResponseInterface đều mở rộng từ Psr\Http\Message\MessageInterface. CÓ THỂ triển khai trực tiếp Psr\Http\Message\MessageInterface, nhưng NÊN triển khai cả Psr\Http\Message\RequestInterface và Psr\Http\Message\ResponseInterface.

Từ đây đến hết bài viết, namespace Psr\Http\Message sẽ được bỏ qua khi đề cập các interface trên.

HTTP header

Các trường tên header không phân biệt chữ hoa chữ thường

Các thông điệp HTTP bao gồm các trường tên header không phân biệt chữ hoa chữ thường. Header được lấy theo tên từ các lớp thực hiện MessageInterface theo cách không phân biệt chữ hoa chữ thường. Ví dụ, việc lấy tiêu đề foo sẽ trả lại kết quả tương tự như lấy tiêu đề FoO. Tương tự, đặt tiêu đề Foo sẽ ghi đè lên bất kỳ giá trị tiêu đề foo nào được đặt trước đó.

Mặc dù các tiêu đề đó có thể được truy xuất phân biệt chữ hoa chữ thường, trường hợp ban đầu PHẢI được bảo quản trong việc triển khai, đặc biệt khi được truy xuất với getHeaders[]

Các ứng dụng HTTP không phù hợp CÓ THỂ phụ thuộc vào một trường hợp nhất định, vì vậy nó hữu ích cho người dùng để có thể ra lệnh cho trường hợp của các tiêu đề HTTP khi tạo một yêu cầu hoặc phản hồi.

$message = $message->withHeader['foo', 'bar'];

echo $message->getHeaderLine['foo'];
// Outputs: bar

echo $message->getHeaderLine['FOO'];
// Outputs: bar

$message = $message->withHeader['fOO', 'baz'];
echo $message->getHeaderLine['foo'];
// Outputs: baz

Header với nhiều giá trị

Để phù hợp với các tiêu đề có nhiều giá trị vẫn cung cấp sự tiện lợi khi làm việc với các tiêu đề như các chuỗi, các tiêu đề có thể được lấy ra từ một cá thể của một MessageInterface như một mảng hoặc một chuỗi. Sử dụng phương thức getHeaderLine[] để lấy ra một giá trị tiêu đề như là một chuỗi chứa tất cả các giá trị tiêu đề của một tiêu đề không phân biệt dạng chữ theo tên được nối với một dấu phẩy. Sử dụng getHeader[] để lấy một mảng của tất cả các giá trị tiêu đề cho một tiêu đề không phân biệt dạng chữ cụ thể theo tên.

$message = $message
    ->withHeader['foo', 'bar']
    ->withAddedHeader['foo', 'baz'];

$header = $message->getHeaderLine['foo'];
// $header contains: 'bar, baz'

$header = $message->getHeader['foo'];
// ['bar', 'baz']

Lưu ý: Không phải tất cả các giá trị tiêu đề đều có thể được ghép bằng dấu phẩy [ví dụ:Set-Cookie]. Khi làm việc với các tiêu đề như vậy, người tiêu dùng các lớp dựa trên MessageInterface NÊN dựa vào phương thức getHeader [] để lấy các tiêu đề đa giá trị như vậy.

Host header

Trong các yêu cầu, tiêu đề Host thường được dùng để phản chiếu lại thành phần chủ của URI, cũng như là phần chủ được sử dụng để biểu diễn kết nối TCP. Tuy nhiên, đặc tả HTTP cho pháp tiêu đề Host phân biệt 2 chức năng trên với nhau.

Trong quá trình xây dựng ứng dụng, việc triển khai PHẢI cố gắng đặt tiêu đề Host từ 1 URI được cung cấp trong trường hợp chưa có tiêu đề Host.

RequestInterface::withUri[] sẽ thay thế tiêu đề Host của yêu cầu bằng tiêu đề Host mà phù hợp với thành phần chủ của cái UriInterface được chấp nhận theo mặc định.

Bạn có thể chọn việc duy trì trạng thái ban đầu của tiêu đề Host bằng cách truyền giá trị true cho tham số [$preserveHost] thứ 2. Khi giá trị này được đặt là true, thông điệp yêu cầu sẽ không cập nhật tiêu đề Host của thông điệp trả về, trừ phi thông điệp yêu cầu không có tiêu đề Host.

Bảng này minh họa những gì getHeaderLine['Host'] sẽ trả về cho một yêu cầu được trả về bởi withUri[] với tham số $preserveHost được đặt thành true cho các yêu cầu ban đầu và URI khác nhau.

• 1: Tiêu đề Host trước khi hoạt động
• 2: Thành phần máy chủ lưu trữ của URI được soạn trong yêu cầu trước khi hoạt động.
• 3: Thành phần chứa URI được đưa vào thông qua withUri[]

Các dòng dữ liệu

Các thông điệp HTTP bao gồm dòng bắt đầu, các tiêu đề và phần thân. Phần thân thông điệp có thể vô cùng nhỏ nhưng cũng có thể to khủng khiếp. Cố gắng để có thể đưa ra thông điệp dưới dạng 1 chuỗi sẽ dẫn tới việc tốn nhiều bộ nhớ hơn dự tính vì phần thân cần được chứa trọn vẹn trong bộ nhớ. Cố gắng để lưu trữ phần thân của 1 yêu cầu hay phản hồi trong bộ nhớ có thể dẫn tới cản trở việc triển khai làm các thông điệp có dung lượng lớn hơn. StreamInterface được sử dụng để ẩn chi tiết triển khai khi luồng dữ liệu được đọc từ hoặc được ghi vào. Giải pháp khi 1 chuỗi cõ thể là thông điệp được triển khai đúng kiểu, các luồng được dựng sẵn là php://memory và php://temp có thể được đưa vào sử dụng.

StreamInterface đưa ra một số phương pháp cho phép các luồng được đọc từ, được ghi vào và đi qua một cách hiệu quả.

Các luồng thể hiện chức năng của chúng theo 3 cách:isReadable[],isWritable[] và isSeekable[]. Những phương thức này có thể được sử dụng bởi các cộng tác viên luồng để xác định liệu một luồng có khả năng đáp ứng yêu cầu của họ hay không.

Mỗi luồng có 3 khả năng khác nhau: nó có thể là chỉ đọc, chỉ ghi, hoặc đọc-ghi. Nó cũng có thể cho phép truy cập ngẫu nhiên tùy ý [tìm kiếm chuyển tiếp hoặc quay trở lại bất kỳ vị trí nào] hoặc chỉ truy cập tuần tự [ví dụ trong trường hợp của một socket, pipe hoặc luồng dựa trên call-back].

Cuối cùng, StreamInterface định nghĩa phương thức __toString[] để đơn giản hóa việc truy xuất hoặc đưa ra toàn bộ nội dung cùng một lúc.

Không giống như interface yêu cầu và phản hồi, StreamInterface không mô hình hóa bất biến. Trong trường hợp một luồng PHP thực sự được đsong gói, bất biến là không thể thực thi, vì bất kỳ mã nào tương tác với tài nguyên có thể thay đổi trạng thái của nó [bao gồm vị trí con trỏ, nội dung và nhiều thứ khác]. Đề xuất của chúng tôi là triển khai sử dụng luồng chỉ đọc cho các yêu cầu phía máy chủ và phản hồi phía máy khách. Người tiêu dùng nên nhận thức được thực tế rằng thể hiện luồng có thể có thể thay đổi và, như vậy, có thể thay đổi trạng thái của thông báo; khi nghi ngờ, hãy tạo một luồng mới và đính kèm nó vào một thông điệp để thực thi trạng thái.

Mục tiêu yêu cầu và URI

Theo RFC 7230, các thông điệp yêu cầu chứa “mục tiêu yêu cầu” làm phân đoạn thứ hai của dòng yêu cầu. Mục tiêu yêu cầu có thể là một trong các dạng sau:

• origin-form, bao gồm đường dẫn, và, nếu có, chuỗi truy vấn; điều này thường được gọi là URL tương đối. Thư được truyền qua TCP thường có dạng gốc; dữ liệu lược đồ và quyền hạn thường chỉ xuất hiện thông qua các biến CGI.
• absolute-form, bao gồm lược đồ, quyền hạn ["[user-info@]host[:port]", trong đó các mục trong ngoặc là tùy chọn], đường dẫn [nếu có], chuỗi truy vấn [nếu có] và đoạn [ nếu có]. Điều này thường được gọi là một URI tuyệt đối, và là biểu mẫu duy nhất để chỉ định một URI được mô tả chi tiết trong RFC 3986. Biểu mẫu này thường được sử dụng khi thực hiện các yêu cầu tới các proxy HTTP.
• authority-form, chỉ bao gồm thẩm quyền. Điều này thường được sử dụng trong các yêu cầu CONNECT, để thiết lập kết nối giữa máy khách HTTP và máy chủ proxy.
• asterisk-form, chỉ bao gồm chuỗi * và được sử dụng với phương pháp OPTIONS để xác định các khả năng thông thường của máy chủ web.

Ngoài các mục tiêu yêu cầu này, thường có ‘URL hiệu quả’ tách biệt với mục tiêu yêu cầu. URL hiệu quả không được truyền trong một thông báo HTTP, nhưng nó được sử dụng để xác định giao thức [http/https], cổng và tên máy chủ để thực hiện yêu cầu.

Các URL có hiệu quả được biểu diễn bởi UriInterface. UriInterface mô hình URI HTTP và HTTPS như được chỉ định trong RFC 3986 [trường hợp sử dụng chính]. Giao diện này cung cấp các phương thức để tương tác với các phần URI khác nhau, điều này sẽ làm giảm nhu cầu phân tích cú pháp lặp lại của URI. Nó cũng chỉ định phương thức __toString[] để đúc URI được mô hình hóa để biểu diễn chuỗi của nó.

Khi truy lục mục tiêu yêu cầu với getRequestTarget[], theo mặc định, phương thức này sẽ sử dụng đối tượng URI và trích xuất tất cả các thành phần cần thiết để xây dựng origin-form. Origin-form cho đến nay là mục tiêu yêu cầu phổ biến nhất.

Nếu người dùng cuối mong muốn sử dụng một trong ba biểu mẫu khác hoặc nếu người dùng muốn ghi đè rõ ràng mục tiêu yêu cầu, có thể làm như vậy với withRequestTarget[].

Gọi phương thức sẽ không ảnh hưởng tới URI, vì sẽ được trả lại với getUri[].

Ví dụ với yêu cầu asterisk-form:

$request = $request
    ->withMethod['OPTIONS']
    ->withRequestTarget['*']
    ->withUri[new Uri['//example.org/']];

Kết quả trả về

OPTIONS * HTTP/1.1

Nhưng đó là nếu máy khách HTTP sẽ có thể sử dụng URL hiệu quả [từ getUri[]], để xác định giao thức, tên máy chủ và cổng TCP.

Một máy khách HTTP PHẢI bỏ qua các giá trị của Uri::getPath[] và Uri::getQuery [], và thay vào đó sử dụng giá trị được trả về bởi getRequestTarget[], mặc định để nối hai giá trị này.

Máy khách chọn không triển khai 1 hoặc nhiều hơn trong số 4 biểu mẫu yêu cầu-mục tiêu, PHẢI vẫn sử dụng getRequestTarget[]. Các máy khách này PHẢI từ chối các mục tiêu yêu cầu mà chúng không hỗ trợ, và KHÔNG ĐƯỢC trả về các giá trị từ getUri[].

RequestInterface cung cấp các phương thức để truy xuất mục tiêu yêu cầu hoặc tạo một cá thể mới với mục tiêu yêu cầu được cung cấp. Theo mặc định, nếu không có mục tiêu yêu cầu nào được cấu tạo cụ thể trong cá thể, getRequestTarget[] sẽ trả về dạng gốc của URI được tạo [hoặc “/” nếu không có URI nào được tạo]. withRequestTarget[$requestTarget] tạo một cá thể mới với đích yêu cầu đã chỉ định, và do đó cho phép các nhà phát triển tạo các thông báo yêu cầu đại diện cho ba biểu mẫu yêu cầu khác [absolute-form, authority-form, và asterisk-form]. Khi được sử dụng, cá thể URI được tạo sẵn vẫn có thể được sử dụng, đặc biệt là trong các máy khách, nơi nó có thể được sử dụng để tạo kết nối đến máy chủ.

Yêu cầu phía server

RequestInterface cung cấp đại diện chung của thông báo yêu cầu HTTP. Tuy nhiên, các yêu cầu phía máy chủ cần xử lý bổ sung, do tính chất của môi trường phía máy chủ. Việc xử lý phía máy chủ cần phải tính đến Giao diện Cổng chung [CGI], và cụ thể hơn là việc trừu tượng hóa và mở rộng CGI của PHP thông qua API Máy chủ [SAPI] của nó. PHP đã cung cấp sự đơn giản hóa xung quanh marshaling đầu vào thông qua superglobals như:

• $_COOKIE
• $_GET
• $_POST
• $_FILES
• $_SERVER

ServerRequestInterface mở rộng RequestInterface để cung cấp một sự trừu tượng xung quanh các superglobals khác nhau này. Thực hành này giúp giảm sự liên kết với siêu người dùng của người tiêu dùng và khuyến khích và thúc đẩy khả năng kiểm tra người tiêu dùng yêu cầu.

Yêu cầu máy chủ cung cấp thêm một thuộc tính, "attributes", để cho phép người tiêu dùng có khả năng nhìn vào, phân tích và so khớp yêu cầu đối với các quy tắc cụ thể cho ứng dụng [chẳng hạn như đối sánh đường dẫn, đối sánh lược đồ, đối sánh lưu trữ, v.v.]. Như vậy, yêu cầu máy chủ cũng có thể cung cấp thông điệp giữa nhiều người tiêu dùng yêu cầu.

Tải file lên

ServerRequestInterface chỉ định một phương thức để lấy một cây các tệp tải lên trong một cấu trúc chuẩn hóa, với mỗi lá là một cá thể của tệp UploadedFileInterface.

Các superglobal $ _FILES có một số vấn đề phổ biến khi xử lý mảng đầu vào tập tin. Ví dụ: nếu bạn có biểu mẫu gửi một mảng tệp - ví dụ: tên đầu vào "files", gửi file[0] và file[1] - PHP sẽ đại diện cho điều này là:

array[
    'files' => array[
        'name' => array[
            0 => 'file0.txt',
            1 => 'file1.html',
        ],
        'type' => array[
            0 => 'text/plain',
            1 => 'text/html',
        ],
        /* etc. */
    ],
]

thay vì:

array[
    'files' => array[
        0 => array[
            'name' => 'file0.txt',
            'type' => 'text/plain',
            /* etc. */
        ],
        1 => array[
            'name' => 'file1.html',
            'type' => 'text/html',
            /* etc. */
        ],
    ],
]

Kết quả là người tiêu dùng cần biết chi tiết triển khai ngôn ngữ này và viết mã để thu thập dữ liệu cho một lần tải lên nhất định.

Ngoài ra, các tình huống tồn tại khi $_FILES không được điền khi tệp tải lên xảy ra:

• Không dùng phương thức POST của HTTP.
• Đang kiểm thử đơn vị
• Khi sử dụng 1 môi trường không SAPI như ReactPHP

Trong những trường hợp như vậy, dữ liệu phải được đưa vào cẩn thận:

• Một quá trình có thể phân tích cú pháp nội dung thư để khám phá các tệp tải lên. Trong những trường hợp như vậy, việc triển khai có thể chọn không ghi các tệp tải lên hệ thống tệp, mà thay vào đó, hãy đóng gói chúng trong một luồng để giảm bộ nhớ, I/O và lưu trữ trên cao.
• Trong các trường hợp thử nghiệm đơn vị, các nhà phát triển cần có khả năng lập và/hoặc giả lập siêu dữ liệu tải lên tệp để xác thực và xác minh các kịch bản khác nhau.

getUploadedFiles[] cung cấp cấu trúc chuẩn hóa cho người tiêu dùng. Triển khai dự kiến sẽ:

• Tổng hợp tất cả thông tin cho một tệp tải lên nhất định và sử dụng nó để điền một instance Psr\Http\Message\UploadedFileInterface.
• Tạo lại cấu trúc cây đã gửi, với mỗi lá là cá thể Psr\Http\Message\UploadedFileInterface thích hợp cho vị trí đã cho trong cây.

Cấu trúc cây được tham chiếu nên bắt chước cấu trúc đặt tên trong đó các tệp đã được gửi.

Trong ví dụ đơn giản nhất, đây có thể là một phần tử biểu mẫu được đặt tên được gửi dưới dạng:

Trong trường hợp này, $_FILES có cấu trúc:

array[
    'avatar' => array[
        'tmp_name' => 'phpUxcOty',
        'name' => 'my-avatar.png',
        'size' => 90996,
        'type' => 'image/png',
        'error' => 0,
    ],
]

Biểu mẫu thông thường được trả về bởi getUploadedFiles[] sẽ là:

array[
    'avatar' => /* UploadedFileInterface instance */
]

Trong trường hợp đầu vào sử dụng ký hiệu mảng cho tên:

$_FILES sẽ kết thúc như thế này:

array[
    'my-form' => array[
        'details' => array[
            'avatar' => array[
                'tmp_name' => 'phpUxcOty',
                'name' => 'my-avatar.png',
                'size' => 90996,
                'type' => 'image/png',
                'error' => 0,
            ],
        ],
    ],
]

Và cây trả về bởi getUploadedFiles[] có dạng:

array[
    'my-form' => array[
        'details' => array[
            'avatar' => /* UploadedFileInterface instance */
        ],
    ],
]

Trong vài trường hợp, bạn có thể thiết lập riêng mảng các tệp:

Upload an avatar: 
Upload an avatar: 

[Ví dụ: các điều khiển JavaScript có thể sinh ra các đầu vào tải lên tệp bổ sung để cho phép tải lên nhiều tệp cùng một lúc.]

Trong trường hợp này, việc triển khai đặc tả phải tổng hợp tất cả thông tin liên quan đến tệp tại chỉ mục đã cho. Lý do là vì $_FILES lệch khỏi cấu trúc bình thường của nó trong những trường hợp như vậy:

array[
    'my-form' => array[
        'details' => array[
            'avatars' => array[
                'tmp_name' => array[
                    0 => '...',
                    1 => '...',
                    2 => '...',
                ],
                'name' => array[
                    0 => '...',
                    1 => '...',
                    2 => '...',
                ],
                'size' => array[
                    0 => '...',
                    1 => '...',
                    2 => '...',
                ],
                'type' => array[
                    0 => '...',
                    1 => '...',
                    2 => '...',
                ],
                'error' => array[
                    0 => '...',
                    1 => '...',
                    2 => '...',
                ],
            ],
        ],
    ],
]

Mảng $_FILES ở trên sẽ tương ứng với cấu trúc sau được trả về bởi getUploadedFiles[]:

array[
    'my-form' => array[
        'details' => array[
            'avatars' => array[
                0 => /* UploadedFileInterface instance */,
                1 => /* UploadedFileInterface instance */,
                2 => /* UploadedFileInterface instance */,
            ],
        ],
    ],
]

Người tiêu dùng sẽ truy cập vào index 1 của mảng lồng nhau bằng cách sử dụng:

$request->getUploadedFiles[]['my-form']['details']['avatars'][1];

Bởi vì dữ liệu tệp được tải lên là bắt nguồn [bắt nguồn từ $_FILES hoặc phần thân yêu cầu], một phương thức biến thể, withUploadedFiles[], cũng có mặt trong giao diện, cho phép ủy nhiệm quá trình chuẩn hóa sang một tiến trình khác.

Trong trường hợp các ví dụ ban đầu, mức tiêu thụ tương tự như sau:

$file0 = $request->getUploadedFiles[]['files'][0];
$file1 = $request->getUploadedFiles[]['files'][1];

printf[
    "Received the files %s and %s",
    $file0->getClientFilename[],
    $file1->getClientFilename[]
];

// "Received the files file0.txt and file1.html"

Đề xuất này cũng nhận ra rằng việc triển khai có thể hoạt động trong môi trường không phải SAPI. Như vậy, UploadedFileInterface cung cấp các phương thức để đảm bảo các hoạt động sẽ hoạt động bất kể môi trường. Đặc biệt:

• moveTo[$targetPath] được cung cấp như là một thay thế an toàn và được đề nghị để gọi move_uploaded_file[] trực tiếp trên tệp tải lên tạm thời. Việc triển khai sẽ phát hiện hoạt động chính xác để sử dụng dựa trên môi trường.
• getStream[] sẽ trả về một cá thể StreamInterface. Trong môi trường không phải SAPI, một khả năng được đề xuất là phân tích các tệp tải lên cá nhân thành các luồng php://temp thay vì trực tiếp vào tệp; trong những trường hợp như vậy, không có tệp tải lên nào. getStream[] do đó được đảm bảo hoạt động bất kể môi trường.

Như ví dụ:

// Move a file to an upload directory
$filename = sprintf[
    '%s.%s',
    create_uuid[],
    pathinfo[$file0->getClientFilename[], PATHINFO_EXTENSION]
];
$file0->moveTo[DATA_DIR . '/' . $filename];

// Stream a file to Amazon S3.
// Assume $s3wrapper is a PHP stream that will write to S3, and that
// Psr7StreamWrapper is a class that will decorate a StreamInterface as a PHP
// StreamWrapper.
$stream = new Psr7StreamWrapper[$file1->getStream[]];
stream_copy_to_stream[$stream, $s3wrapper];

Gói thư viện

Các lớp và lớp giao diện được cung cấp dưới đây như 1 phần của gói psr/http-message

Các Interface

Psr\Http\Message\MessageInterface