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

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

152 lines 4.1 KB

Raw Download Zip

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