From e6dd8ebad3da514d997f11796c30952a7b8a562e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Frank=20Br=C3=BCckner?= Date: Wed, 4 Dec 2024 12:46:36 +0100 Subject: [PATCH] Standardize headings across documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit standardizes the capitalization of section headings in the documentation to improve consistency and readability. Descriptive information sections are marked with category tags (INFO or WARNING) to distinguish them more clearly. These changes do not alter any functional content or code. Signed-off-by: Frank Brückner --- docs/book/client/adapters.md | 65 +++++++++++++++--------------------- docs/book/client/advanced.md | 44 ++++++++++-------------- docs/book/client/cookies.md | 4 +-- docs/book/client/intro.md | 16 ++++----- docs/book/headers.md | 6 ++-- docs/book/intro.md | 10 +++--- docs/book/request.md | 8 ++--- docs/book/response.md | 9 ++--- 8 files changed, 69 insertions(+), 93 deletions(-) diff --git a/docs/book/client/adapters.md b/docs/book/client/adapters.md index 2693941f..28eba5c5 100644 --- a/docs/book/client/adapters.md +++ b/docs/book/client/adapters.md @@ -20,7 +20,7 @@ the value of the `adapter` option may be one of: - an adapter instance - the fully qualified class name of an adapter -## The Socket adapter +## The Socket Adapter The default connection adapter used when none is specified is the `Laminas\Http\Client\Adapter\Socket` adapter. The `Socket` adapter is based on @@ -43,8 +43,7 @@ Parameter | Description `sslusecontext` | Enables proxied connections to use SSL even if the proxy connection itself does not. | boolean | `FALSE` `sslverifypeername` | Whether to verify the peer name | boolean | `TRUE` -> ### Persistent TCP connections -> +> INFO: **Persistent TCP Connections** > Using persistent TCP connections can potentially speed up HTTP requests, but > in most use cases, will have little positive effect and might overload the > HTTP server you are connecting to. It is recommended to use persistent TCP @@ -58,15 +57,12 @@ Parameter | Description > Keep-Alive HTTP requests as described in [the client configuration section](intro.md#configuration); > otherwise persistent connections might have little or no effect. -> ### HTTPS SSL stream parameters -> -> `ssltransport`, `sslcert` and `sslpassphrase` are only relevant when -> connecting using HTTPS. While the default SSL/TLS settings should work for -> most applications, you might need to change them if the server you are -> connecting to requires special client setup. If so, please read the -> [PHP manual chapter on SSL and TLS transport options](http://php.net/transports.inet). +INFO: **HTTPS SSL Stream Parameters** +`ssltransport`, `sslcert` and `sslpassphrase` are only relevant when connecting using HTTPS. +While the default SSL/TLS settings should work for most applications, you might need to change them if the server you are connecting to requires special client setup. +If so, please read the [PHP manual chapter on SSL and TLS transport options](http://php.net/transports.inet). -### Changing the HTTPS transport layer +### Changing the HTTPS Transport Layer ```php use Laminas\Http\Client; @@ -91,7 +87,7 @@ using the following PHP command: fsockopen('tls://www.example.com', 443); ``` -### Customizing and accessing the Socket adapter stream context +### Customizing and Accessing the Socket Adapter Stream Context `Laminas\Http\Client\Adapter\Socket` provides direct access to the underlying [stream context](http://php.net/stream.contexts) used to connect to the remote @@ -112,7 +108,7 @@ You can access the stream context using the following methods of return it. You can then set or get the value of different context options using regular PHP stream context functions. -#### Setting stream context options for the Socket adapter +#### Setting Stream Context Options for the Socket Adapter ```php use Laminas\Http\Client; @@ -158,15 +154,12 @@ $opts = stream_context_get_options($adapter->getStreamContext()); echo $opts['ssl']['peer_certificate']; ``` -> #### Set stream context options prior to requests -> -> Note that you must set any stream context options before using the adapter to -> perform actual requests. If no context is set before performing HTTP requests -> with the `Socket` adapter, a default stream context will be created. This -> context resource could be accessed after performing any requests using the -> `getStreamContext()` method. +INFO: **Set Stream Context Options Prior to Requests** +Note that you must set any stream context options before using the adapter to perform actual requests. +If no context is set before performing HTTP requests with the `Socket` adapter, a default stream context will be created. +This context resource could be accessed after performing any requests using the `getStreamContext()` method. -## The Proxy adapter +## The Proxy Adapter `Laminas\Http\Client\Adapter\Proxy` is similar to the default `Socket` adapter; the primary difference is that the connection is made through an HTTP proxy server @@ -200,7 +193,7 @@ authentication. Possible values are similar to the ones accepted by the `Laminas\Http\Client::setAuth()` method. Currently, only basic authentication (`Laminas\Http\Client::AUTH_BASIC`) is supported. -### Using Laminas\\Http\\Client behind a proxy server +### Using Laminas\\Http\\Client Behind a Proxy Server ```php use Laminas\Http\Client; @@ -225,12 +218,8 @@ connection will fall back to a regular direct connection. This allows you to write your application in a way that allows a proxy to be used optionally, according to a configuration parameter. -> ### Access to stream context -> -> Since the proxy adapter inherits from `Laminas\Http\Client\Adapter\Socket`, you -> can use the stream context access method (see -> [above](#setting-stream-context-options-for-the-socket-adapter)) to set stream -> context options on `Proxy` connections. +INFO: **Access to Stream Context** +Since the proxy adapter inherits from `Laminas\Http\Client\Adapter\Socket`, you can use the stream context access method (see> [above](#setting-stream-context-options-for-the-socket-adapter)) to set stream context options on `Proxy` connections. ## The cURL Adapter @@ -241,13 +230,11 @@ choice for a HTTP adapter. It supports secure connections, proxies, and multiple authentication mechanisms. In particular, it is very performant with regards to transfering large files. -> ### Known issue with libcurl prior to 7.30.0 -> -> There is an issue with [incorrect headers length detection in libcurl](https://github.com/bagder/curl/pull/60) -> prior to 7.30.0. It leads to problems with removing the Transfer-Encoding -> header from the response. We encourage to update libcurl. +WARNING: **Known Issue with libcurl Prior to 7.30.0** +There is an issue with [incorrect headers length detection in libcurl](https://github.com/bagder/curl/pull/60) prior to 7.30.0. +It leads to problems with removing the Transfer-Encoding header from the response. We encourage to update libcurl. -### Setting cURL options +### Setting cURL Options ```php use Laminas\Http\Client; @@ -278,7 +265,7 @@ Parameter | Description `proxyport` | Passphrase for the SSL certificate file | string | `NULL` `sslverifypeer` | Whether to verify the SSL peer | string | `TRUE` -### Transfering files by handle +### Transfering Files by Handle You can use cURL to transfer very large files over HTTP by filehandle. @@ -301,7 +288,7 @@ $adapter->setOptions([ $client->send(); ``` -## The Test adapter +## The Test Adapter Testing code that relies on HTTP connections poses difficulties. For example, testing an application that pulls an RSS feed from a remote server will require @@ -320,7 +307,7 @@ an individual response to always return from any request; `addResponse()` allows aggregating a sequence of responses. In both cases, responses are returned without performing actual HTTP requests. -### Testing against a single HTTP response stub +### Testing Against a Single HTTP Response Stub ```php use Laminas\Http\Client; @@ -419,7 +406,7 @@ this. The initial 302 response is set up with the `setResponse()` method and the configuring the test adapter, inject the HTTP client containing the adapter into your object under test and test its behavior. -### Forcing the adapter to fail +### Forcing the Adapter to Fail If you need the adapter to fail on demand you can use `setNextRequestWillFail($flag)`. The method will cause the next call to @@ -451,7 +438,7 @@ try { // you call setNextRequestWillFail(true) again ``` -## Creating your own connection adapters +## Creating Your Own Connection Adapters `Laminas\Http\Client` has been designed so that you can create and use your own connection adapters. You could, for example, create a connection adapter that diff --git a/docs/book/client/advanced.md b/docs/book/client/advanced.md index 165a7f67..65b948e2 100644 --- a/docs/book/client/advanced.md +++ b/docs/book/client/advanced.md @@ -1,6 +1,6 @@ # Advanced Usage -## HTTP redirections +## HTTP Redirections `Laminas\Http\Client` automatically handles HTTP redirections, and by default will follow up to 5 redirections. This can be changed by setting the @@ -26,7 +26,7 @@ $client->setOptions(['strictredirects' => false]); You can always get the number of redirections done after sending a request using the `getRedirectionsCount()` method. -## Adding cookies and using cookie persistence +## Adding Cookies and Using Cookie Persistence `Laminas\Http\Client` provides an interface for adding cookies to your request, so that no direct header modification is required. Cookies can be added using @@ -96,7 +96,7 @@ $client->setMethod('GET'); See the chapter on [cookies](cookies.md) for more detail. -## Setting custom request headers +## Setting Custom Request Headers Setting custom headers is performed by first fetching the header container from the client's `Laminas\Http\Request` instance. This `Headers` container offers a @@ -150,7 +150,7 @@ $client->setHeaders([ ]); ``` -## File uploads +## File Uploads You can upload files through HTTP using the `setFileUpload()` method. This method takes a file name as the first parameter, a form name as the second @@ -185,14 +185,11 @@ file `/tmp/Backup.tar.gz` is uploaded to the server and will be available as `$_FILES['bufile']`. The content type will be guessed automatically if possible, defaulting to `application/octet-stream`. -> ### Uploading files -> -> When uploading files, the HTTP request `Content-Type` is automatically set to -> `multipart/form-data`. Keep in mind that you must send a POST or PUT request -> in order to upload files; most servers will ignore the request body on other -> request methods. +INFO: **Uploading files** +When uploading files, the HTTP request `Content-Type` is automatically set to `multipart/form-data`. +Keep in mind that you must send a POST or PUT request in order to upload files; most servers will ignore the request body on other request methods. -## Sending raw POST data +## Sending Raw POST Data You can send raw POST data via `Laminas\Http\Client` using the `setRawBody()` method. This method takes one parameter: the data to send in the request body. @@ -214,14 +211,11 @@ $client->send(); The data should be available on the server side through PHP's `php://input` stream. -> ### Raw POST data overrides other content -> -> Setting raw POST data for a request will override any POST parameters or file -> uploads; you should not try to use both on the same request. Keep in mind -> that most servers will ignore the request body unless you send a POST -> request. +INFO: **Raw Post Data Overrides Other Content** +Setting raw POST data for a request will override any POST parameters or file uploads; you should not try to use both on the same request. +Keep in mind that most servers will ignore the request body unless you send a POST request. -## HTTP authentication +## HTTP Authentication Currently, `Laminas\Http\Client` only supports basic HTTP authentication. This feature is utilized using the `setAuth()` method, or by specifying a username and a password in the URI. The `setAuth()` @@ -241,7 +235,7 @@ $client->setAuth('shahar', 'myPassword!'); $client->setUri('http://christer:secret@example.com'); ``` -## Sending multiple requests with the same client +## Sending Multiple Requests with the Same Client `Laminas\Http\Client` was also designed specifically to handle several consecutive requests with the same object. This is useful in cases where a script requires @@ -259,11 +253,9 @@ all the request-specific parameters are cleared, you should use the `resetParameters()` method. This ensures that GET and POST parameters, request body, and request headers are reset and are not reused in the next request. -> ### Resetting parameters -> -> Note that cookies are not reset by default when the `resetParameters()` -> method is used. To clean all cookies as well, use `resetParameters(true)`, or -> call `clearCookies()` after calling `resetParameters()`. +INFO: **Resetting parameters** +Note that cookies are not reset by default when the `resetParameters()` method is used. +To clean all cookies as well, use `resetParameters(true)`, or call `clearCookies()` after calling `resetParameters()`. Another feature designed specifically for consecutive requests is the `Laminas\Http\Cookies` object. This "Cookie Jar" allow you to save cookies set by @@ -277,7 +269,7 @@ application, it might be a good idea to store the `Cookies` object in the user's session. This way, you will only need to authenticate the user once every session. -### Performing consecutive requests with one client +### Performing Consecutive Requests with One Client ```php use Laminas\Http\Client; @@ -319,7 +311,7 @@ $response = $client->setMethod('GET')->send(); $_SESSION['cookiejar'] = $cookieJar; ``` -## Data streaming +## Data Streaming By default, `Laminas\Http\Client` accepts and returns data as PHP strings. However, in many cases there are big files to be received, thus keeping them in diff --git a/docs/book/client/cookies.md b/docs/book/client/cookies.md index cc9e2e2f..aa19a002 100644 --- a/docs/book/client/cookies.md +++ b/docs/book/client/cookies.md @@ -57,7 +57,7 @@ After the request, don't forget to add any cookies returned! Essentially, `Cookies` aggregates all cookies for our client interactions, and allows us to send only those relevant to a given request. -## Serializing and caching cookies +## Serializing and Caching Cookies To cache cookies — e.g., to store in `$_SESSION`, or between job invocations — you will need to serialize them. `Laminas\Http\Cookies` @@ -95,7 +95,7 @@ if (is_array($cachedCookies)) { } ``` -## Public methods +## Public Methods Besides the methods demonstrated in the examples, `Laminas\Http\Cookies` defines the following: diff --git a/docs/book/client/intro.md b/docs/book/client/intro.md index 9f880d8a..6235dd18 100644 --- a/docs/book/client/intro.md +++ b/docs/book/client/intro.md @@ -59,11 +59,9 @@ $client = new Client(); $response = $client->send($request); ``` -> ### URL validation -> -> `Laminas\Http\Client` uses `Laminas\Uri\Http` to validate URLs. See the -> [laminas-uri](https://docs.laminas.dev/laminas-uri/) -> documentation for more information. +INFO: **URL validation** +`Laminas\Http\Client` uses `Laminas\Uri\Http` to validate URLs. +See the [laminas-uri](https://docs.laminas.dev/laminas-uri/) documentation for more information. ## Configuration @@ -94,7 +92,7 @@ options available. ## Examples -### Performing a GET request +### Performing a GET Request GET is the default method used, and requires no special configuration. @@ -105,7 +103,7 @@ $client = new Client('http://example.org'); $response = $client->send(); ``` -### Using request methods other than GET +### Using Request Methods Other than GET The request method can be set using `setMethod()`. If no method is specified, the method set by the last `setMethod()` call is used. If `setMethod()` was @@ -136,7 +134,7 @@ $client->setMethod(Request::METHOD_POST); $response = $client->send(); ``` -### Setting query parameters +### Setting Query Parameters Adding query parameters to an HTTP request can be done either by specifying them as part of the URL, or by using the `setParameterGet()` method. This method @@ -158,7 +156,7 @@ $client->setParameterGet([ ]); ``` -### Setting form-encoded body parameters +### Setting form-encoded Body Parameters While query parameters can be sent with every request method, other methods can accept parameters via the request body. In many cases, these are diff --git a/docs/book/headers.md b/docs/book/headers.md index 246d9e58..db7c993a 100644 --- a/docs/book/headers.md +++ b/docs/book/headers.md @@ -504,7 +504,7 @@ string when multiple values are present. ## Examples -### Retrieving headers from a Headers object +### Retrieving Headers from a Headers Object ```php // $client is an instance of Laminas\Http\Client @@ -530,7 +530,7 @@ There are three possibilities for the return value of the above call to the `get return an `ArrayIterator` containing one `Laminas\Http\Header\ContentType` instance per header. -### Adding headers to a Headers object +### Adding Headers to a Headers Object ```php use Laminas\Http\Header; @@ -565,7 +565,7 @@ $headers->addHeaders([ ]); ``` -### Removing headers from a Headers object +### Removing Headers from a Headers Object We can remove all headers of a specific type using the `removeHeader` method, which accepts a single object implementing `Laminas\Http\Header\HeaderInterface` diff --git a/docs/book/intro.md b/docs/book/intro.md index 13d9dba6..19f33821 100644 --- a/docs/book/intro.md +++ b/docs/book/intro.md @@ -14,13 +14,11 @@ abstractions: - A client implementation with various adapters that allow for sending requests and introspecting responses. -> ## Not PSR-7 -> -> This library **does not** support [PSR-7](http://www.php-fig.org/psr/psr-7), as -> it predates that specification. For PSR-7 support, please see our -> [Diactoros component](https://docs.laminas.dev/laminas-diactoros/). +WARNING: **Not PSR-7** +This library **does not** support [PSR-7](http://www.php-fig.org/psr/psr-7), as it predates that specification. +For PSR-7 support, please see our [Diactoros component](https://docs.laminas.dev/laminas-diactoros/). -## Laminas\Http Request, Response and Headers +## Request, Response and Headers The request, response and headers implementations of the laminas-http component provides a fluent, object-oriented interface for introspecting information from diff --git a/docs/book/request.md b/docs/book/request.md index 6ef98661..6139bc5b 100644 --- a/docs/book/request.md +++ b/docs/book/request.md @@ -107,7 +107,7 @@ Method signature | De ## Examples -### Generating a Request object from a string +### Generating a Request Object from a String ```php use Laminas\Http\Request; @@ -122,7 +122,7 @@ $request->getVersion(); // returns Request::VERSION_11 or '1.1' $request->getContent(); // returns 'Some Content' ``` -### Retrieving and setting headers +### Retrieving and Setting Headers ```php use Laminas\Http\Request; @@ -136,7 +136,7 @@ foreach ($request->getHeaders() as $header) { } ``` -### Retrieving and setting GET and POST values +### Retrieving and Setting GET and POST Values ```php use Laminas\Http\Request; @@ -151,7 +151,7 @@ $request->getPost('foo'); // returns 'Foo value' $request->getQuery()->offsetGet('bar'); // returns 'Bar value' ``` -### Generating a formatted HTTP Request from a Request object +### Generating a Formatted HTTP Request from a Request Object ```php use Laminas\Http\Request; diff --git a/docs/book/response.md b/docs/book/response.md index 16a563f1..58fa02a5 100644 --- a/docs/book/response.md +++ b/docs/book/response.md @@ -103,7 +103,7 @@ Method signature | Descrip ## Examples -### Generating a Response object from a string +### Generating a Response Object from a String ```php use Laminas\Http\Response; @@ -120,7 +120,7 @@ HeaderField2: header-field-value2 EOS); ``` -### Generating a formatted HTTP Response from a Response object +### Generating a Formatted HTTP Response from a Response Object ```php use Laminas\Http\Response; @@ -139,9 +139,10 @@ $response->setContent(<< Available since version 2.13.0 +INFO: **New Feature** +Available since version 2.13.0 By default, laminas-http's `Laminas\Http\PhpEnvironment\Response` class, which is used in laminas-mvc applications, tests to see if PHP has already emitted