|
|
Maxious
|
1 |
protobuf-php(3) -- The framework |
|
|
|
2 |
================================ |
|
|
|
3 |
|
|
|
|
4 |
## SYNOPSIS |
|
|
|
5 |
|
|
|
|
6 |
<?php |
|
|
|
7 |
require_once 'DrSlump\Protobuf.php'; |
|
|
|
8 |
|
|
|
|
9 |
use DrSlump\Protobuf; |
|
|
|
10 |
|
|
|
|
11 |
$data = file_get_contents('data.pb'); |
|
|
|
12 |
$person = new Tutorial\Person($data); |
|
|
|
13 |
echo $person->getName(); |
|
|
|
14 |
|
|
|
|
15 |
|
|
|
|
16 |
## DESCRIPTION |
|
|
|
17 |
|
|
|
|
18 |
Protobuf-PHP is a library to generate, parse and serialize data structures |
|
|
|
19 |
compatible with Google's Protocol Buffers using the PHP language. |
|
|
|
20 |
|
|
|
|
21 |
## CODECS |
|
|
|
22 |
|
|
|
|
23 |
The library is designed to work with a pluggable mechanism for encoding and decoding |
|
|
|
24 |
messages, allowing it to be used not only to communicate using the standard binary |
|
|
|
25 |
format but also with Json or XML based formats. |
|
|
|
26 |
|
|
|
|
27 |
You can create your own codecs by either extending a provided one or implementing the |
|
|
|
28 |
`Protobuf\CodecInterface`. Creating custom codecs offers the possibility to use |
|
|
|
29 |
Protobuf-PHP code generation tool to work with legacy formats or even as a simple |
|
|
|
30 |
way to interact with database adapters. |
|
|
|
31 |
|
|
|
|
32 |
### Standard Binary |
|
|
|
33 |
|
|
|
|
34 |
This is the standard binary format supported by the official libraries distributed |
|
|
|
35 |
by Google. It's pretty much compatible with the official implementations although |
|
|
|
36 |
there are some known issues, mostly regarding big integer numbers, which are documented |
|
|
|
37 |
in the readme file that comes with the library. |
|
|
|
38 |
|
|
|
|
39 |
### Standard TextFormat |
|
|
|
40 |
|
|
|
|
41 |
The official libraries also support a text based format for debugging purposes. The |
|
|
|
42 |
current implementation of this codec only supports encoding or serialization. |
|
|
|
43 |
|
|
|
|
44 |
### PhpArray |
|
|
|
45 |
|
|
|
|
46 |
This is more of an internal codec to ease the implementation of some others. It is |
|
|
|
47 |
able to serializa message objects to PHP's associative arrays and intantiate message |
|
|
|
48 |
objects from them. |
|
|
|
49 |
|
|
|
|
50 |
Since most serialization libraries in PHP will natively support associative arrays, this |
|
|
|
51 |
codec can be used as an easy way to incorporate those formats for their use |
|
|
|
52 |
with Protobuf messages. The Json and XML codecs are examples of this use case. |
|
|
|
53 |
|
|
|
|
54 |
### JSON |
|
|
|
55 |
|
|
|
|
56 |
It allows to generate or consume JSON formatted strings, which is a very popular |
|
|
|
57 |
format for REST based web services for example. This codec can be used to communicate |
|
|
|
58 |
with JavaScript in the browser or with third party REST web services. |
|
|
|
59 |
|
|
|
|
60 |
### ProtoJson |
|
|
|
61 |
|
|
|
|
62 |
[ProtoJson](https://github.com/drslump/ProtoJson) allows to apply some payload |
|
|
|
63 |
minification strategies when working with JSON formatted messages. Taking advantatge |
|
|
|
64 |
of Protobuf's property names mapping to a integer number, it offers two encoding |
|
|
|
65 |
variants (_TagMap_ and _Indexed_) that use that number instead of the field name |
|
|
|
66 |
as key in the messages to reduce the total size of the payload. |
|
|
|
67 |
|
|
|
|
68 |
### XML |
|
|
|
69 |
|
|
|
|
70 |
A very simple codec to work with XML based messages. It has no knowledge of namespaces |
|
|
|
71 |
and other advanced XML features but should be enough to integrate with third parties |
|
|
|
72 |
that are restricted to simple XML payloads. It can also serve as a base for more |
|
|
|
73 |
customized integrations, by extendind this codec to consume and generate XML messages |
|
|
|
74 |
specific to your service. |
|
|
|
75 |
|
|
|
|
76 |
|
|
|
|
77 |
|
|
|
|
78 |
## ANNOTATED MESSAGES |
|
|
|
79 |
|
|
|
|
80 |
While the most common use case is to use the protoc-gen-php(1) `protoc` plugin to |
|
|
|
81 |
generate source code representing the messages defined in .proto files, it's also |
|
|
|
82 |
possible to define messages at runtime without the code generation step. |
|
|
|
83 |
|
|
|
|
84 |
An easy way to define messages directly in your code is to use the `Protobuf\AnnotatedMessage` |
|
|
|
85 |
abstract class, which allows to annotate your classes so that the _codecs_ know how |
|
|
|
86 |
to parse and serialize those messages. |
|
|
|
87 |
|
|
|
|
88 |
class Person extends \DrSlump\Protobuf\AnnotatedMessage { |
|
|
|
89 |
/** @protobuf(tag=1, type=string, required) */ |
|
|
|
90 |
public $name; |
|
|
|
91 |
/** @protobuf(tag=2, type=int32, required) */ |
|
|
|
92 |
public $id; |
|
|
|
93 |
/** @protobuf(tag=3, type=string, optional) */ |
|
|
|
94 |
public $email; |
|
|
|
95 |
/** @protobuf(tag=4, repeated, type=message, reference=Person) */ |
|
|
|
96 |
public $friends = array(); |
|
|
|
97 |
} |
|
|
|
98 |
|
|
|
|
99 |
|
|
|
|
100 |
## EXAMPLES |
|
|
|
101 |
|
|
|
|
102 |
|
|
|
|
103 |
|
|
|
|
104 |
## BUGS |
|
|
|
105 |
|
|
|
|
106 |
Please report bugs using GitHub's issue tracker at http://github.com/drslump/protobuf-php/issues |
|
|
|
107 |
|
|
|
|
108 |
|
|
|
|
109 |
## COPYRIGHT |
|
|
|
110 |
|
|
|
|
111 |
Protobuf for PHP is Copyright (C) 2011 Ivan -DrSlump- Montes <http://pollinimini.net> |
|
|
|
112 |
|
|
|
|
113 |
|
|
|
|
114 |
## SEE ALSO |
|
|
|
115 |
|
|
|
|
116 |
protoc-gen-php(1), protobuf-php(5), |
|
|
|
117 |
<http://github.com/drslump/protobuf-php> |
|
|
|
118 |
|