desktop-mode / includes / desktop-files / class-desktop-mode-file.php

class-desktop-mode-file.php in OpenStation: Desktop Windows, Dock & Virtual Desktops for WP Admin 0.9.1, at includes/desktop-files/class-desktop-mode-file.php

157 lines 4.2 KB

Raw Download Zip

1	<?php
2	/**
3	* Desktop Mode — `Desktop_Mode_File` abstract base class.
4	*
5	* Every "file" that a user can place on the Desktop Mode wallpaper
6	* (a post, a user, an attachment, a term, a comment, a folder, a
7	* bookmark — or anything a third-party plugin teaches the system
8	* about) is represented by a subclass of this base. The subclass
9	* adapts a WordPress entity (or any opaque reference string) to the
10	* shape the desktop UI expects: a title, an icon, a preview, and a
11	* capability gate.
12	*
13	* Files do NOT know how to open themselves. Opening is a separate
14	* concern delegated to the file-opener registry (Phase 1) so the
15	* same `post` file can be opened by Gutenberg, the Classic Editor,
16	* or any plugin's editor of choice — the user's per-type
17	* association decides which.
18	*
19	* @package WPDesktopMode
20	* @since 0.9.0
21	*/
22
23	defined( 'ABSPATH' ) \|\| exit;
24
25	/**
26	* Adapts a WordPress entity to the desktop "file" surface.
27	*
28	* Subclass contract: implement {@see ::title()} and the static
29	* {@see ::type()} slug; override {@see ::icon()}, {@see ::preview_url()},
30	* {@see ::can_read()}, or {@see ::serialize()} when the defaults
31	* don't fit.
32	*
33	* @since 0.9.0
34	*/
35	abstract class Desktop_Mode_File {
36
37	/**
38	* Opaque reference identifying the underlying entity.
39	*
40	* For most types this is a numeric id (post id, user id,
41	* attachment id, term id, comment id). For `bookmark` it's the
42	* URL itself. For `folder` it's the row id of the folder.
43	*
44	* Stored as a string because the placements table stores it as
45	* a varchar — type coercion happens in the subclass.
46	*
47	* @var string
48	*/
49	protected $ref = '';
50
51	/**
52	* @param string\|int $ref Entity reference.
53	*/
54	public function __construct( $ref = '' ) {
55	$this->ref = (string) $ref;
56	}
57
58	/**
59	* The file-type slug, e.g. `'post'`, `'user'`, `'folder'`.
60	*
61	* @return string
62	*/
63	abstract public static function type(): string;
64
65	/**
66	* Human-readable title displayed under the tile.
67	*
68	* @return string
69	*/
70	abstract public function title(): string;
71
72	/**
73	* Reference accessor — read-only on purpose.
74	*
75	* @return string
76	*/
77	public function ref(): string {
78	return $this->ref;
79	}
80
81	/**
82	* Dashicon class (or `data:` URI) rendered on the tile. Default
83	* is the generic media glyph; subclasses should override.
84	*
85	* @return string
86	*/
87	public function icon(): string {
88	return 'dashicons-media-default';
89	}
90
91	/**
92	* Optional preview-image URL (e.g. featured image, avatar,
93	* attachment thumbnail). Empty string when the tile should
94	* render the icon instead.
95	*
96	* @return string
97	*/
98	public function preview_url(): string {
99	return '';
100	}
101
102	/**
103	* Whether `$user_id` can see / open this file. Defaults to
104	* `true`; subclasses tighten the gate. For shared folders this
105	* is consulted PER PLACEMENT at snapshot time so a folder
106	* shared with role `editor` cannot expose individual files the
107	* viewer lacks the cap to read.
108	*
109	* @param int $user_id Viewer.
110	* @return bool
111	*/
112	public function can_read( int $user_id ): bool {
113	return true;
114	}
115
116	/**
117	* Whether the underlying entity still exists. The renderer uses
118	* this to flag dead references with a placeholder tile rather
119	* than rendering nothing (so the user can right-click → remove).
120	*
121	* @return bool
122	*/
123	public function exists(): bool {
124	return '' !== $this->ref;
125	}
126
127	/**
128	* Shape sent to JS. Subclasses extend by overriding and
129	* `array_merge`'ing on top of `parent::serialize()`.
130	*
131	* @return array
132	*/
133	public function serialize(): array {
134	$shape = array(
135	'type' => static::type(),
136	'ref' => $this->ref,
137	'title' => $this->title(),
138	'icon' => $this->icon(),
139	'previewUrl' => $this->preview_url(),
140	'exists' => $this->exists(),
141	);
142
143	/**
144	* Filters the serialized shape of a desktop file before it
145	* crosses the wire. Last-mile mutation point — plugins use
146	* this to attach badges, override labels, or splice in
147	* custom render hints without subclassing.
148	*
149	* @since 0.9.0
150	*
151	* @param array $shape The serialized file shape.
152	* @param Desktop_Mode_File $file The file being serialized.
153	*/
154	return apply_filters( 'desktop_mode_file_serialize', $shape, $this );
155	}
156	}
157