AGENTS.md

1# Agent Guidelines
2 
3## Code and tooling
4 
5- All code must remain compatible with PHP 7.4. Run PHPStan and PHP-CS-Fixer
6  only under a PHP 7.4.x runtime; never run either tool under any other PHP
7  major.minor version.
8- Use fully qualified `#[\SensitiveParameter]` on concrete executable
9  parameters when their established role normally carries a secret,
10  credential-bearing aggregate, or confidential Guzzle-owned container, and
11  the active frame can throw or invoke throwing code.
12- Repeat the attribute on every qualifying owned caller, callee, concrete trait
13  method, and closure parameter. Do not add it to interfaces, abstract-only
14  declarations, pure/no-realistic-throw helpers, assignment-only sites,
15  arbitrary generic payloads, or completed non-recoverable derivatives.
16- For PHP 7.4 compatibility, put `#[\SensitiveParameter]` on its own line and
17  the parameter on the following line, expand the complete parameter list, and
18  never add a comma after the final parameter. Native trace redaction starts on
19  PHP 8.2 and does not redact logs, messages, properties, wire traffic, captured
20  variables, return values, or the separate backtrace `$this`/`object`.
21- Always pass an explicit character list to `trim()`, `ltrim()`, and `rtrim()`;
22  never rely on the default characters.
23- Handle `preg_*` engine failures: when the result is used as data, test for
24  `false` or `null` and throw a `\RuntimeException` including
25  `preg_last_error_msg()`; boolean validation guards must compare strictly, such
26  as `=== 1`, so an engine failure can only ever fail closed. Diagnostic
27  escaping is the narrow exception: use a deterministic bytewise fallback rather
28  than throwing, so it cannot obscure the original exception.
29- Anchor validation patterns to the true end of input with the `D` modifier or
30  `\z`; a bare `$` accepts a trailing newline.
31- Never embed raw control bytes in exception messages and other diagnostics;
32  escape or redact the offending value first.
33- Helper classes that expose only public static methods are `final` and have a
34  private constructor.
35- Resist native PHP serialization when a class holds live state (streams,
36  resources, handles, callbacks, credentials) or when magic methods such as
37  `__destruct()` have side effects that untrusted unserialized data could
38  redirect, as with the file and session write fixes in Guzzle's persisting
39  cookie jars. Plain data holders, such as Guzzle's in-memory cookie jar, remain
40  serializable.
41- To resist, `__serialize()` and `__unserialize()` both throw
42  `\LogicException(static::class.' should never be serialized')` and its
43  unserialized counterpart, usually via the `@internal` `NonSerializableTrait`.
44  Where a `__destruct()` has such a side effect, it is enabled only by the
45  constructor and disabled in `__wakeup()` and `__unserialize()` before
46  throwing, so the protection holds even if the exception is swallowed.
47- In general, numeric inputs should not accept non-finite floats. In situations
48  where they are accepted and we need to cast to a string, we should branch on
49  `\is_finite($value)`, using `(string) $value` for the finite case and
50  `\is_nan($value) ? 'NAN' : ($value > 0 ? 'INF' : '-INF')` otherwise.
51- Never call `strtolower()`, `strtoupper()`, `strcasecmp()`, `stripos()`, or
52  other locale-sensitive case functions; use the locale-independent
53  `GuzzleHttp\Psr7\Utils::asciiToLower()`, `asciiToUpper()`,
54  `caselessEquals()`, and `caselessContains()` helpers instead.
55- Changes in behavior need a `CHANGELOG.md` entry in the unreleased section of
56  the target branch and an `UPGRADING.md` note when the behavior differs between
57  major versions.
58 
59## Contributor references
60 
61- Read the [exception guidelines](docs/contributing/exception-guidelines.md)
62  before deciding which exception a change should throw.
63- Read the
64  [cURL connection reuse reference](docs/contributing/curl-connection-reuse.md)
65  before working on the cURL handlers or connection reuse and sharing behavior.
66 
67## Documentation
68 
69- Wrap markdown prose and PHPDoc text to 80 columns using greedy wrapping. Never
70  split a markdown link or an inline code span across a line break; a line that
71  cannot be broken may exceed the limit. Avoid em dashes.
72- Keep PHPDoc and the corresponding `docs/` pages in sync: shared prose is
73  deliberately word-for-word identical, including boilerplate copied verbatim
74  between related functions, so apply the same edit to every copy. Only
75  formatting and linking may differ, such as a docs link becoming a PHPDoc
76  `@see` tag; the wording must never drift.
77