source: project/wiki/php-s11n @ 4812

Last change on this file since 4812 was 4812, checked in by arto, 13 years ago

php-s11n: Documented the exported parameters on the wiki page.

File size: 10.3 KB
Line 
1[[tags: eggs s11n php php-s11n]]
2
3[[toc:]]
4
5== Introduction
6
7This egg provides serialization/unserialization of Scheme values in a format
8compatible with the ubiquitous [[http://php.net/|PHP]] scripting language.
9This can be useful for communicating with PHP applications (such as the
10popular [[http://drupal.org/|Drupal]] or WordPress) over a socket
11connection, or for reading and writing existing serialized PHP application
12data in files or DBMS columns.
13
14
15== Examples
16
17=== Serializing to PHP format
18
19<enscript highlight=scheme>
20
21#;1> (use php-s11n)
22
23#;2> (php-serialize #t)
24"b:1;"
25
26#;3> (php-serialize 3.1415)
27"d:3.1415;"
28
29#;4> (php-serialize '#("a" "b" "c"))
30"a:3:{i:0;s:1:\"a\";i:1;s:1:\"b\";i:2;s:1:\"c\";}"
31
32#;5> (php-serialize '((first_name . "Random") (last_name . "Hacker")))
33"a:2:{s:10:\"first_name\";s:6:\"Random\";s:9:\"last_name\";s:6:\"Hacker\";}"
34
35#;6> (php-serialize (void))
36"N;"
37
38</enscript>
39
40
41=== Unserializing from PHP format
42
43<enscript highlight=scheme>
44
45#;1> (use php-s11n)
46
47#;2> (php-unserialize "a:3:{i:1;s:1:\"a\";i:2;s:1:\"b\";i:3;s:1:\"c\";}")
48((1 . "a") (2 . "b") (3 . "c"))
49
50#;3> (php-unserialize (php-serialize '((a . orange) (b . banana) (c . apple))))
51(("a" . "orange") ("b" . "banana") ("c" . "apple"))
52
53#;4> (php-unserialize (php-serialize '#(1 2 3 5 8 13 21 34)))
54#(1 2 3 5 8 13 21 34)
55
56</enscript>
57
58
59=== Mapping PHP associative arrays to Scheme key-value lists
60
61Because the interpretation of PHP's
62[[http://php.net/manual/en/language.types.array.php|associative arrays]] can
63be ambigious and application-dependent, the {{php-s11n}} egg provides a
64number of parameters for hooking into and extending the
65serialization/unserialization process.
66
67As an example of how to use this, say that you wanted to represent
68associative arrays using key-value lists as provided by the [[kvlists]] egg.
69First, you would define a custom writer and reader as follows:
70
71<enscript highlight=scheme>
72
73(use php-s11n kvlists)
74
75(define (php-s11n-write-array/kvlist value port)
76  (if (kvlist? value)
77      (php-s11n-write (kvlist->alist value))
78      (error 'php-s11n-write "unable to serialize object" value)))
79
80(define (php-s11n-read-array/kvlist port)
81  (alist->kvlist (map (lambda (pair)
82                        (cons (string->symbol (->string (car pair)))
83                              (cdr pair)))
84                      (php-s11n-read-array/alist port))))
85
86(php-s11n-writer php-s11n-write-array/kvlist)
87(php-s11n-array-reader php-s11n-read-array/kvlist)
88
89</enscript>
90
91Now, after loading the above code, you could use key-value lists like
92follows:
93
94<enscript highlight=scheme>
95
96#;1> (php-unserialize (php-serialize '(a: orange b: banana c: apple)))
97(a: "orange" b: "banana" c: "apple")
98
99</enscript>
100
101
102== Author
103
104[[Arto Bendiken]]
105
106
107== Requires
108
109* [[regex-literals]] (compile-time only)
110
111
112== Data types
113
114PHP's [[http://es.php.net/manual/en/language.types.php|native data types]]
115are rather limited, meaning that only some of the basic Scheme types can be
116serialized into and from this format. Scheme values are mapped to PHP
117equivalents (or substitutes) as follows:
118
119<table>
120<tr>
121<th>Scheme</th>
122<th>PHP</th>
123</tr>
124<tr>
125<td>void</td>
126<td>[[http://php.net/manual/en/language.types.null.php|NULL]]</td>
127</tr>
128<tr>
129<td>boolean</td>
130<td>[[http://php.net/manual/en/language.types.boolean.php|boolean]]</td>
131</tr>
132<tr>
133<td>integer</td>
134<td>[[http://php.net/manual/en/language.types.integer.php|integer]] (platform-dependent, but assume 32-bit signed)</td>
135</tr>
136<tr>
137<td>flonum</td>
138<td>[[http://php.net/manual/en/language.types.float.php|float]] (platform-dependent, but assume 64-bit double precision)</td>
139</tr>
140<tr>
141<td>string</td>
142<td>[[http://php.net/manual/en/language.types.string.php|string]]</td>
143</tr>
144<tr>
145<td>character</td>
146<td>string</td>
147</tr>
148<tr>
149<td>symbol</td>
150<td>string</td>
151</tr>
152<tr>
153<td>vector</td>
154<td>[[http://php.net/manual/en/language.types.array.php|array]] (contiguous numerical indexing from 0..n-1)</td>
155</tr>
156<tr>
157<td>alist</td>
158<td>[[http://php.net/manual/en/language.types.array.php|array]] (associative, numeric or string keys)</td>
159</tr>
160<tr>
161<td>hash-table</td>
162<td>array (associative, numeric or string keys)</td>
163</tr>
164<tr>
165<td>N/A</td>
166<td>[[http://php.net/manual/en/language.types.object.php|object]]</td>
167</tr>
168</table>
169
170As the table above demonstrates, Scheme types such as characters and symbols
171must be coerced into strings since PHP lacks the requisite equivalent types,
172and Scheme's numeric types may be truncated or lose precision when
173serialized into PHP format.
174
175In other words, PHP's native types form a minimal subset of Scheme's, so
176while unserializing PHP data in Scheme will always work, you have to be
177mindful when serializing out of Scheme.
178
179Special consideration is due PHP's arrays. In PHP, there are no different
180indexed and associative array types; there is only one array type, which can
181contain both integer and string indices. This means PHP's arrays are
182actually ordered maps of keys to values, and can serve both as vectors and
183as hash tables depending on what you put into them.
184
185There is also a special caveat in that while keys can be integers and
186strings both, those strings which can be read as integers are automagically
187coerced into a numeric type (e.g. "7" becomes 7). {{php-s11n-write}} follows
188this behavior so as to produce output as identical as possible to what PHP's
189native {{serialize()}} function would spew out.
190
191The obvious Scheme equivalent to PHP's associative arrays is the association
192list (i.e., lists of the form {{((k1 . v1) (k2 . v2) ...)}}), which is what
193{{php-s11n-read}} will return by default when unserializing a PHP array.
194
195There is one exception to the above: if all the indices of the array being
196unserialized are numerical and form a contiguous range from 0..n-1, then the
197PHP array will be returned as a Scheme vector. This allows dealing with
198vector-like PHP arrays in a half-way sane manner. As {{php-s11n-write}} also
199takes care to serialize Scheme vectors into PHP arrays indexed using this
200very same method, it follows that a read-write equivalence holds for Scheme
201vectors.
202
203If this default behavior is undesirable, array handling in the serialization
204and unserialization process can be fully customized and extended through the
205parameters {{php-s11n-writer}} and {{php-s11n-array-reader}}. (See the
206Examples section, above.)
207
208Not wishing to be tied into any particular add-on object system for Scheme,
209serialization and unserialization of PHP
210[[http://php.net/manual/en/language.types.object.php|object types]] is not
211handled by default, and attempting to unserialize a PHP object will raise an
212error. However, the parameters {{php-s11n-writer}} and
213{{php-s11n-object-reader}} allow you to bolt on application-specific object
214type support in a seamless and facile manner.
215
216
217== Serialization and unserialization
218
219=== php-serialize
220
221 [procedure] (php-serialize VALUE)
222
223Returns a serialized string representation of {{VALUE}} in PHP format.
224Internally, this procedure will call {{php-s11n-write}} to do all the actual
225work.
226
227=== php-unserialize
228
229 [procedure] (php-unserialize STRING)
230
231Converts {{STRING}}, which is expected to be a PHP format serialized string,
232into a Scheme value. Internally, this procedure will call {{php-s11n-read}}
233to do all the actual work.
234
235
236== Parameters
237
238=== php-s11n-writer
239
240 [parameter] php-s11n-writer
241
242Procedure to call for serializing any Scheme values that are not included in
243the data type mappings built into the {{php-s11n}} egg. The procedure will
244be invoked with two arguments, {{VALUE}} and {{PORT}}.
245
246The parameter defaults to {{#f}}, raising an error when trying to serialize
247an unsupported data type.
248
249=== php-s11n-reader
250
251 [parameter] php-s11n-reader
252
253Procedure to call for unserializing any encountered unknown data type
254specifiers in the input. The procedure will be invoked with one argument,
255{{PORT}}. You should never need to handle this case unless PHP's
256serialization format changes.
257
258The parameter defaults to {{#f}}, raising an error if the serialized format
259contains unknown data type specifiers.
260
261=== php-s11n-array-reader
262
263 [parameter] php-s11n-array-reader
264
265Procedure to call for unserializing a PHP array encountered in the input.
266The procedure will be invoked with one argument, {{PORT}}.
267
268The parameter defaults to {{php-s11n-read-array}}.
269
270=== php-s11n-object-reader
271
272 [parameter] php-s11n-object-reader
273
274Procedure to call for unserializing a PHP object encountered in the input.
275The procedure will be invoked with one argument, {{PORT}}.
276
277The parameter defaults to {{php-s11n-read-object}}.
278
279
280== Output
281
282=== php-s11n-write
283
284 [procedure] (php-s11n-write VALUE [PORT])
285
286
287== Input
288
289=== php-s11n-read
290
291 [procedure] (php-s11n-read [PORT])
292
293=== php-s11n-read-null
294
295 [procedure] (php-s11n-read-null PORT)
296
297=== php-s11n-read-boolean
298
299 [procedure] (php-s11n-read-boolean PORT)
300
301=== php-s11n-read-integer
302
303 [procedure] (php-s11n-read-integer PORT)
304
305=== php-s11n-read-float
306
307 [procedure] (php-s11n-read-float PORT)
308
309=== php-s11n-read-string
310
311 [procedure] (php-s11n-read-string PORT)
312
313=== php-s11n-read-array
314
315 [procedure] (php-s11n-read-array PORT)
316
317=== php-s11n-read-array/alist
318
319 [procedure] (php-s11n-read-array/alist PORT)
320
321=== php-s11n-read-array/hash-table
322
323 [procedure] (php-s11n-read-array/hash-table PORT)
324
325=== php-s11n-read-object
326
327 [procedure] (php-s11n-read-object PORT)
328
329
330== License
331
332  Copyright (c) 2006-2007 Arto Bendiken.
333 
334  Permission is hereby granted, free of charge, to any person obtaining a copy
335  of this software and associated documentation files (the "Software"), to
336  deal in the Software without restriction, including without limitation the
337  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
338  sell copies of the Software, and to permit persons to whom the Software is
339  furnished to do so, subject to the following conditions:
340 
341  The above copyright notice and this permission notice shall be included in
342  all copies or substantial portions of the Software.
343 
344  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
345  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
346  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
347  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
348  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
349  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
350  IN THE SOFTWARE.
351
352
353== Version history
354
355;1.0.0 : Initial release of the {{php-s11n}} egg.
Note: See TracBrowser for help on using the repository browser.