### Problem/Motivation `FilterDownloadLinkLabeler` does almost everything itself: it finds links with a regular expression, decides which ones are downloads, works out whether a link points to this site, reads local file sizes from disk, builds the label and removes labels typed after links. Only the remote size request has its own class, `HttpDownloadLinkLabeler`. That makes the filter hard to read and test, and several bugs come from the regular expression and from how the pieces depend on each other. This issue first planned to merge `HttpDownloadLinkLabeler` into the filter. That plan is reversed: the HTTP class is the easiest part to test, so the filter should be split further instead. The filter also always removes labels typed after links, such as ` (PDF) (1.2 MB)`. There is no setting to turn this off, and it removes any two bracketed phrases after a link, even ones that aren't a label. #### Steps to reproduce Enable the Download Link Labeler filter on a text format with its default settings, then save content containing each of these: 1. `<p>Before <a href="">empty</a> after</p>`: the link is removed from the output completely. 2. `<a href='/sites/default/files/report.pdf'>Report</a>` (single-quoted `href`): no label. 3. `<a href="https://example.com/page">Page</a> (see) (this)`: the text ` (see) (this)` is removed, even though the link isn't a download. 4. `<a href="/sites/default/files/missing.pdf">Report</a> (PDF) (9 KB)`, where the file doesn't exist: the typed label is removed and nothing replaces it. 5. Set the filter's included extensions to `PDF`, then link to `/sites/default/files/report.pdf`: no label, because the setting isn't lowercased before it's compared. 6. `<a href="/../../../../etc/some-file.pdf">File</a>`: the label shows the size of a file outside the Drupal root. Anyone who can use the text format can find out whether a file with an included extension exists outside the root, and how large it is. 7. Link to an external file while its host is unreachable: the "Unknown Size" label is cached until the next cache clear, even after the host comes back. The result also depends on the current request's host and base path, but it declares no cache contexts. 8. Look at the text format's filter tips: they always name PDF, DOC(X), XLS(X), PPT(X) and ZIP, whatever the settings are, and the long and short tips list different types. ### Proposed resolution #### Structure Split the filter into small services, each with its own tests. The filter keeps only the link loop, the label markup, the library attachment and cacheability. | Class | Responsibility | |-------|----------------| | `Plugin\Filter\FilterDownloadLinkLabeler` | Finds the links, asks the services about each one, adds labels, removes typed labels if enabled, and sets attachments and cacheability. | | `DownloadLink` | Readonly value object: the URL, its extension, and the local file path when the link points to this site. | | `DownloadLinkDetector` | Turns an `href`, the included extensions and the current request into a `DownloadLink`, or `NULL` when the link isn't a download. | | `FileSize\FileSizeInterface` | `bytes(DownloadLink $link): ?int`, the size in bytes or `NULL` when it's unknown. | | `FileSize\LocalFileSize` | Reads a local file's size, only for files inside the Drupal root. | | `FileSize\RemoteFileSize` | Today's `HttpDownloadLinkLabeler`: a `HEAD` request with a 5-second timeout that follows redirects and uses only a 2xx response's `Content-Length`. Returns `?int`. | The services are registered by class name with `autowire: true`. The plugin ID stays `download_link_labeler`, so existing text formats keep working. #### Behavior - Find links with `Html::load()` and `Html::serialize()` instead of a regular expression, as core's caption and align filters do. This fixes the empty and single-quoted `href` cases. Text without `<a` is still returned unchanged. Text with links is re-serialized, which can normalize its markup (entity encoding, attribute quoting), as with core's other DOM-based filters. - Resolve local paths with `realpath()`, and only report a size for files whose real path is inside `DRUPAL_ROOT`. Keep the current handling of sites served from a subdirectory. - Normalize the included extensions when they're read: lowercase them, split on spaces and commas, and drop empty entries. Validate the settings field so it only accepts file extensions. - Keep sizes separate from how they're displayed: the services return `?int`, and only the filter turns that into `ByteSizeMarkup` or "Unknown Size". - Add the `url.site` cache context to the result. When any label says "Unknown Size", limit the result's max-age to one hour so a temporary failure isn't cached indefinitely. - Build the filter tips from the configured extensions. - Leave the label markup unchanged (the `link-label label-file label-file-<ext>` classes and the label content), so themes aren't affected. #### Replacing typed labels becomes an opt-in setting Add a checkbox to the filter's settings on the text format's configuration page: **Replace labels typed after download links**, off by default. When it's on, the filter removes a label typed after a download link only when all of these are true: - The link gets a generated label. A link to a missing local file keeps its typed text. - The text right after the link is two bracketed parts separated by spaces or non-breaking spaces, such as ` (PDF) (1.2 MB)`. - The first bracketed part is the link's file extension, ignoring case and a leading dot. For example, `(PDF)` or `(.pdf)` for a `.pdf` link. Any other text after a link is kept. On existing sites, typed labels have always been removed. A post-update function turns the setting on for every text format that already uses the filter, so their output stays the same. New text formats start with it off. #### Code standards Use `declare(strict_types=1)`, typed and readonly promoted properties, and no public mutable state. Remove the filter's unused or internal public properties (`$text`, `$safeText`, `$filter`, `$format`, `$includedExtensions`, `$pattern`) and its duplicate `StringTranslationTrait`. phpcs (Drupal and DrupalPractice) stays clean. Add a phpstan configuration for the GitLab CI phpstan job. ### Remaining tasks - [x] Add characterization tests that pin the current label markup, subdirectory handling and removal of typed labels. - [x] Make the filter's external-link tests use a mocked `http_client` instead of a live web server reached through `SIMPLETEST_BASE_URL`. Keep one real HTTP test for `RemoteFileSize`. - [x] Rename `HttpDownloadLinkLabeler` to `FileSize\RemoteFileSize`, returning `?int`, and move its tests. - [x] Add `DownloadLink`, `DownloadLinkDetector`, `FileSize\FileSizeInterface` and `FileSize\LocalFileSize`, with unit tests for the detector. - [x] Rewrite the filter to use them, with the label markup unchanged. - [x] Replace the regular expression with DOM parsing. Add tests for empty and single-quoted `href` values. - [x] Only report local sizes for files inside the Drupal root. Add a test for a path outside it. - [x] Normalize and validate the included extensions. Add a test for an uppercase setting. - [x] Add the `replace_typed_labels` setting, its schema, its form element and the extension check. Test the setting off and on, a first part that doesn't match the extension, a missing file, and text after a link that isn't a label. - [x] Add the post-update function that turns the setting on for existing text formats, with a test. - [x] Add the `url.site` cache context and the one-hour max-age for "Unknown Size", with tests. - [x] Build the filter tips from the settings. - [x] Clean up types and properties. phpcs and phpstan pass. - [x] Update README.md with the new setting and how "Unknown Size" is cached. - [x] Open follow-up issues for: - A themable label template and an accessible label. The `aria-label` on a plain `<span>` isn't allowed by ARIA, and it isn't translated. - Caching remote sizes per URL, and requesting the sizes of several external links at once instead of one after another. ### User interface changes - New checkbox in the filter's settings on the text format page: **Replace labels typed after download links**. It's off by default, and the update turns it on for text formats that already use the filter. - The included extensions field is validated. - The filter tips list the configured extensions. - The generated label looks the same as before. ### API changes - `RemoteFileSize` replaces the `download_link_labeler.http` service and the `HttpDownloadLinkLabeler` class. Its method returns `?int` instead of a string or "Unknown Size" markup. - The filter's public `getFileLabel()` and `remoteFileSize()` methods and its public properties are removed. - New services: `DownloadLinkDetector`, `FileSize\LocalFileSize` and `FileSize\RemoteFileSize`. ### Data model changes - New filter setting `replace_typed_labels` (boolean, default `FALSE`) in `filter_settings.download_link_labeler`. - A post-update function sets it to `TRUE` for existing text formats that use the filter. - `included_extensions` stays a space-separated string, so its stored config doesn't change.