1	<?php
2	declare( strict_types = 1 );
3
4	namespace 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	*/
51	trait ContentMetadataCollectorCompat {
52	/* This trait is empty, in an ideal world. */
53	}