Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
CRAP
0.00% covered (danger)
0.00%
0 / 1
ContentMetadataCollectorCompat
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
0.00% covered (danger)
0.00%
0 / 1
 setTOCData
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
1<?php
2declare( strict_types = 1 );
3
4namespace Wikimedia\Parsoid\Core;
5
6/**
7 * Helper trait for implementations of ContentMetadataCollector.
8 *
9 * This trait is ideally empty.  However, all implementations of
10 * ContentMetadataCollector should `use` it.  Then, when a method is
11 * changed in the ContentMetadataCollector implementation, compatibility
12 * code can be temporarily added to this trait in order to facilitate
13 * migration.
14 *
15 * For example, suppose that the method `getFoo()` in ContentMetadataCollector`
16 * was renamed to `getBar()`.  Before, third-party code contains:
17 * ```
18 * class MyCollector implements ContentMetadataCollector {
19 *   use ContentMetadataCollectorCompat;
20 *
21 *   public function getFoo() { ... }
22 * }
23 * ```
24 * When the method is renamed in the `ContentMetadataCollector` interface
25 * we then add the following to `ContentMetadataCollectorCompat`:
26 * ```
27 * trait ContentMetadataCollectorCompat {
28 *   public function getBar() {
29 *     return $this->getFoo();
30 *   }
31 * }
32 * ```
33 *
34 * This prevents `MyCollector` from failing to implement
35 * `ContentMetadataCollector` when Parsoid is upgraded to the latest version.
36 * Over time, `MyCollector` will rename the method in its own implementation
37 * and that will override the default implementation inherited from the
38 * `ContentMetadataCollectorCompat` class.  Then eventually the
39 * compatibility method can be removed from this trait and we're back
40 * where we started.
41 *
42 * Similarly, if we want to collect some new type of metadata, the
43 * collection method can be added to `ContentMetadataCollector` at the
44 * same time a default implementation is added to
45 * `ContentMetadataCollectorCompat`; again ensuring that we don't
46 * unnecessarily break classes which implement
47 * `ContentMetadataCollector`.  The default implementation could do
48 * nothing, effectively ignoring the collection request, or it could
49 * record portions of the metadata using other collection methods.
50 */
51trait ContentMetadataCollectorCompat {
52    /* This trait is empty, in an ideal world. */
53
54    /**
55     * Retrofit new method into existing (legacy) interface
56     * till implementations support this on their own.
57     * For now, nothing to do here.
58     *
59     * @param TOCData $tocData
60     */
61    public function setTOCData( TOCData $tocData ): void {
62        /* Nothing to do here; in theory we'd call ParserOutput::setSections()
63         * but that interface was never added to ContentMetadataCollector. */
64    }
65}