aboutsummaryrefslogtreecommitdiff
path: root/ratatoeskr/sys/pluginpackage.php
blob: 863df7168656ad0648406d9aa5ea0ad0959f2168 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
<?php

/*
 * File: ratatoeskr/sys/pluginpackage.php
 * Handle plugin packages easily.
 * 
 * License:
 * This file is part of Ratatöskr.
 * Unlike the other parts of Ratatöskr, *this* file ist *not* licensed under the
 * MIT / X11 License, but under the WTFPL, to make it even easier to use this
 * file in other projects.
 * See "ratatoeskr/licenses/wtfpl" for more information.
 */

/*
 * Function: dir2array
 * Pack a directory into an array.
 * 
 * Parameters:
 * 	$dir - The directory to pack.
 * 
 * Returns:
 * 	Associative array. Keys are filenames, values are either the file's content as a string or another array, if it's a directory.
 */
function dir2array($dir)
{
	$rv = array();
	foreach(scandir($dir) as $fn)
	{
		if(($fn == ".") or ($fn == ".."))
			continue;
		$fn_new = $dir . "/" . $fn;
		if(is_dir($fn_new))
			$rv[$fn] = dir2array($fn_new);
		elseif(is_file($fn_new))
			$rv[$fn] = file_get_contents($fn_new);
	}
	return $rv;
}

/*
 * Function: array2dir
 * Unpack an array into a directory.
 * 
 * Parameters:
 * 	$a   - Array to unpack.
 * 	$dir - Directory to unpack to.
 */
function array2dir($a, $dir)
{
	if(!is_dir($dir))
		mkdir($dir);
	
	foreach($a as $k => $v)
	{
		$k = "$dir/$k";
		if(is_array($v))
			array2dir($v, $k);
		else
			file_put_contents($k, $v);
	}
}

function validate_url     ($u) { return preg_match("/^http[s]{0,1}:\\/\\/.*$/", $u) != 0; }
function validate_arraydir($a)
{
	if(!is_array($a))
		return False;
	foreach($a as $k=>$v)
	{
		if(!is_string($k))
			return False;
		if(is_array($v) and (!validate_arraydir($v)))
			return False;
		elseif(!is_string($v))
			return False;
	}
	return True;
}	

/*
 * Class: InvalidPackage
 * An Exception that <PluginPackage>'s function can throw, if the package is invalid.
 */
class InvalidPackage extends Exception {}

/*
 * Class: PluginPackage
 * A plugin package representation.
 */
class PluginPackage
{
	public static $magic = "R7RPLGPACKV001";
	
	/*
	 * Variables: Mandatory values
	 * 
	 * $code              - The plugin code
	 * $classname         - The name of the plugins main class
	 * $name              - Name of the plugin (must be at least one character, allowed chars: a-z A-Z 0-9 - _)
	 * $author            - The author of the plugin (preferably in the format: Name<mail@address>)
	 * $versiontext       - A text to describe the current version, something like "1.1 Beta"
	 * $versioncount      - A number for this version, should be increased with every release
	 * $api               - The used API version
	 * $short_description - A short description.
	 */
	public $code              = NULL;
	public $classname         = NULL;
	public $name              = NULL;
	public $author            = NULL;
	public $versiontext       = NULL;
	public $versioncount      = NULL;
	public $api               = NULL;
	public $short_description = NULL;
	
	/*
	 * Variables: Optional values
	 *
	 * $updatepath - A URL that points to a update information resource (serialize'd array("current-version" => VERSIONCOUNT, "dl-path" => DOWNLOAD PATH); will get overwritten/set by the default repository software.
	 * $web        - A URL to the webpage for the plugin. If left empty, the default repository software will set this to the description page of your plugin.
	 * $license    - The license text of your plugin.
	 * $help       - A help / manual (formatted in HTML) for your plugin.
	 * $custompub  - <dir2array> 'd directory that contains custom public(i.e. can later be accessed from the web) data.
	 * $custompriv - <dir2array> 'd directory that contains custom private data.
	 * $tpls       - <dir2array> 'd directory containing custom STE templates.
	 */
	public $updatepath = NULL;
	public $web        = NULL;
	public $license    = NULL;
	public $help       = NULL;
	public $custompub  = NULL;
	public $custompriv = NULL;
	public $tpls       = NULL;
	
	/*
	 * Function: validate
	 * Validate, if the variables are set correctly.
	 * Will throw an <InvalidPackage> exception if invalid.
	 */
	public function validate()
	{
		if(!is_string($this->code))
			throw new InvalidPackage("Invalid code value.");
		if(!is_string($this->classname))
			throw new InvalidPackage("Invalid classname value.");
		if(preg_match("/^[a-zA-Z0-9_\\-]+$/", $this->name) == 0)
			throw new InvalidPackage("Invalid name value (must be at least 1 character, accepted chars: a-z A-Z 0-9 - _).");
		if(!is_string($this->author))
			throw new InvalidPackage("Invalid author value.");
		if(!is_string($this->versiontext))
			throw new InvalidPackage("Invalid versiontext value.");
		if(!is_numeric($this->versioncount))
			throw new InvalidPackage("Invalid versioncount value. Must be a number.");
		if(!is_numeric($this->api))
			throw new InvalidPackage("Invalid api value. Must be a number.");
		if(!is_string($this->short_description))
			throw new InvalidPackage("Invalid short_description value.");
		
		if((!empty($this->updatepath)) and (!validate_url($this->updatepath)))
			throw new InvalidPackage("Invalid updatepath value. Must be an URL. " .$this->updatepath);
		if((!empty($this->web)) and (!validate_url($this->web)))
			throw new InvalidPackage("Invalid web value. Must be an URL.");
		if(($this->license !== NULL) and (!is_string($this->license)))
			throw new InvalidPackage("Invalid license value.");
		if(($this->help !== NULL) and (!is_string($this->help)))
			throw new InvalidPackage("Invalid help value.");
		if(($this->custompub !== NULL) and (!validate_arraydir($this->custompub)))
			throw new InvalidPackage("Invalid custompub value.");
		if(($this->custompriv !== NULL) and (!validate_arraydir($this->custompriv)))
			throw new InvalidPackage("Invalid custompriv value.");
		if(($this->tpls !== NULL) and (!validate_arraydir($this->tpls)))
			throw new InvalidPackage("Invalid tpls value.");
		return True;
	}
	
	/*
	 * Function: load
	 * Load a plugin package from binary data.
	 * 
	 * Parameters:
	 * 	$plugin_raw - The raw package to load.
	 * 
	 * Returns:
	 * 	The <PluginPackage> object.
	 * 
	 * Throws:
	 * 	<InvalidPackage> if package is invalid.
	 */
	public static function load($plugin_raw)
	{
		/* Read and compare magic number */
		$magic = substr($plugin_raw, 0, strlen(self::$magic));
		if($magic != self::$magic)
			throw new InvalidPackage("Wrong magic number");
		
		/* Read sha1sum and uncompress serialized plugin, then compare the hash */
		$sha1sum   = substr($plugin_raw, strlen(self::$magic), 20);
		$pluginser = gzuncompress(substr($plugin_raw, strlen(self::$magic) + 20));
		if(sha1($pluginser, True) != $sha1sum)
			throw new InvalidPackage("Wrong SHA1 hash");
		
		$plugin = @unserialize($pluginser);
		if(!($plugin instanceof self))
			throw new InvalidPackage("Not the correct class or not unserializeable.");
		
		$plugin->validate();
		
		return $plugin;
	}
	
	/*
	 * Function: save
	 * Save the plugin.
	 * 
	 * Returns:
	 * 	A binary plugin package.
	 * 
	 * Throws:
	 * 	<InvalidPackage> if package is invalid.
	 */
	public function save()
	{
		$this->validate();
		$ser = serialize($this);
		return self::$magic . sha1($ser, True) . gzcompress($ser, 9);
	}
	
	/*
	 * Function: extract_meta
	 * Get just the metadata of this package.
	 * 
	 * Returns:
	 * 	A <PluginPackageMeta> object.
	 */
	public function extract_meta()
	{
		$meta = new PluginPackageMeta();
		
		$meta->name              = $this->name;
		$meta->author            = $this->author;
		$meta->versiontext       = $this->versiontext;
		$meta->versioncount      = $this->versioncount;
		$meta->api               = $this->api;
		$meta->short_description = $this->short_description;
		$meta->updatepath        = $this->updatepath;
		$meta->web               = $this->web;
		$meta->license           = $this->license;
		
		return $meta;
	}
}

/*
 * Class: PluginPackageMeta
 * Only the metadata of a <PluginPackage>.
 */
class PluginPackageMeta
{
	/*
	 * Variables: Mandatory values
	 * 
	 * $name              - Name of the plugin (must be at least one character, allowed chars: a-z A-Z 0-9 - _)
	 * $author            - The author of the plugin (preferably in the format: Name<mail@address>)
	 * $versiontext       - A text to describe the current version, something like "1.1 Beta"
	 * $versioncount      - A number for this version, should be increased with every release
	 * $api               - The used API version
	 * $short_description - A short description.
	 */
	public $name              = NULL;
	public $author            = NULL;
	public $versiontext       = NULL;
	public $versioncount      = NULL;
	public $api               = NULL;
	public $short_description = NULL;
	
	/*
	 * Variables: Optional values
	 *
	 * $updatepath - A URL that points to a update information resource (serialize'd array("current-version" => VERSIONCOUNT, "dl-path" => DOWNLOAD PATH); will get overwritten/set by the default repository software.
	 * $web        - A URL to the webpage for the plugin. If left empty, the default repository software will set this to the description page of your plugin.
	 * $license    - The license text of your plugin.
	 */
	public $updatepath = NULL;
	public $web        = NULL;
	public $license    = NULL;
}

?>