templately / modules / site-editor-views / ViewConfig.php

ViewConfig.php in Templately – Elementor & Gutenberg Template Library: 6500+ Free & Pro Ready Templates And Cloud! trunk, at modules/site-editor-views/ViewConfig.php

127 lines 4.0 KB

Raw Download Zip

1	<?php
2	/**
3	* The Pages screen contribution (spec 054, contracts/view-config.md).
4	*
5	* Three rules govern everything here, and each exists because breaking it fails
6	* quietly rather than loudly.
7	*
8	* 1. `merge()`, never `set()`. The host offers four write modes. `set()`
9	* swaps a whole top-level key wholesale — documented for a callback that "owns
10	* a key outright" — so using it on `default_view` would discard the site
11	* owner's sort order, layout and column selection. That is FR-008's exact
12	* prohibition, and because the host also offers `replace()` and `remove()`, the
13	* way to violate it is a named sibling method rather than a hypothetical. This
14	* class calls `merge()` and nothing else.
15	*
16	* 2. Declare the schema version. The second argument is a SCHEMA VERSION,
17	* not the priority the pre-release note described. A patch declaring a version
18	* the host does not support is rejected IN FULL with `_doing_it_wrong` — so the
19	* failure mode is a screen that silently lacks our fields, with nothing a user
20	* or a production log would show. When core's `LATEST_VERSION` moves past ours,
21	* this constant does not follow automatically: a patch authored against schema 1
22	* keeps working only while core still accepts schema 1.
23	*
24	* 3. Touch only documented keys. Anything written outside
25	* `default_view`/`default_layouts`/`view_list`/`form` is discarded by the host
26	* before the config is returned. We touch two: `default_view.fields` to make our
27	* fields available, and `view_list` to add our views. We contribute no layout
28	* and nothing to Quick Edit.
29	*
30	* PHP 7.2 SYNTAX ONLY.
31	*
32	* @package Templately
33	*/
34
35	namespace Templately\Modules\SiteEditorViews;
36
37	defined( 'ABSPATH' ) \|\| exit;
38
39	class ViewConfig {
40
41	/**
42	* The schema version our patch is authored against.
43	*
44	* `WP_View_Config_Data::LATEST_VERSION` was 1 when this was written and
45	* verified. See rule 2 above before changing it.
46	*/
47	const SCHEMA_VERSION = 1;
48
49	/**
50	* The one screen we contribute to.
51	*
52	* Pages, and nothing else (FR-009). Templates and Parts list the host's own
53	* template entities — our theme-builder templates are a different post type,
54	* so fields contributed there could never render — and catalog patterns are
55	* registered on demand rather than stored as pattern posts.
56	*/
57	const FILTER = 'get_entity_view_config_postType_page';
58
59	/**
60	* @var Fields
61	*/
62	protected $fields;
63
64	/**
65	* @var Views
66	*/
67	protected $views;
68
69	public function __construct( Provenance $provenance ) {
70	$this->fields = new Fields( $provenance );
71	$this->views = new Views();
72
73	add_filter( self::FILTER, [ $this, 'contribute' ], 10, 2 );
74	}
75
76	/**
77	* Add our fields and views to the Pages screen configuration.
78	*
79	* @param \WP_View_Config_Data $data The configuration container.
80	* @param array $entity The entity being configured.
81	* @return \WP_View_Config_Data
82	*/
83	public function contribute( $data, $entity = [] ) {
84	if ( ! is_object( $data ) \|\| ! method_exists( $data, 'merge' ) ) {
85	return $data;
86	}
87
88	$patch = $this->patch();
89
90	if ( empty( $patch ) ) {
91	return $data;
92	}
93
94	$data->merge( $patch, self::SCHEMA_VERSION );
95
96	return $data;
97	}
98
99	/**
100	* The patch itself, built separately so it can be asserted without a host.
101	*
102	* Note what is NOT here: no `sort`, no `layout`, no wholesale `fields`
103	* replacement, and no removal or reordering of the host's own views. Those
104	* absences are the requirement (FR-008), which is why this method is the
105	* unit under test rather than the rendered screen.
106	*
107	* @return array<string, mixed> Empty when there is nothing to contribute.
108	*/
109	public function patch(): array {
110	$views = $this->views->definitions();
111
112	if ( empty( $views ) ) {
113	// No Templately content on this site: contribute nothing at all, so
114	// the screen is indistinguishable from a site without the plugin
115	// (FR-011, SC-004).
116	return [];
117	}
118
119	return [
120	'default_view' => [
121	'fields' => $this->fields->ids(),
122	],
123	'view_list' => $views,
124	];
125	}
126	}
127