--- a/lib/Protobuf-PHP/man/protobuf-php.3.ronn +++ b/lib/Protobuf-PHP/man/protobuf-php.3.ronn @@ -1,1 +1,118 @@ +protobuf-php(3) -- The framework +================================ +## SYNOPSIS + + <?php + require_once 'DrSlump\Protobuf.php'; + + use DrSlump\Protobuf; + + $data = file_get_contents('data.pb'); + $person = new Tutorial\Person($data); + echo $person->getName(); + + +## DESCRIPTION + +Protobuf-PHP is a library to generate, parse and serialize data structures +compatible with Google's Protocol Buffers using the PHP language. + +## CODECS + +The library is designed to work with a pluggable mechanism for encoding and decoding +messages, allowing it to be used not only to communicate using the standard binary +format but also with Json or XML based formats. + +You can create your own codecs by either extending a provided one or implementing the +`Protobuf\CodecInterface`. Creating custom codecs offers the possibility to use +Protobuf-PHP code generation tool to work with legacy formats or even as a simple +way to interact with database adapters. + +### Standard Binary + +This is the standard binary format supported by the official libraries distributed +by Google. It's pretty much compatible with the official implementations although +there are some known issues, mostly regarding big integer numbers, which are documented +in the readme file that comes with the library. + +### Standard TextFormat + +The official libraries also support a text based format for debugging purposes. The +current implementation of this codec only supports encoding or serialization. + +### PhpArray + +This is more of an internal codec to ease the implementation of some others. It is +able to serializa message objects to PHP's associative arrays and intantiate message +objects from them. + +Since most serialization libraries in PHP will natively support associative arrays, this +codec can be used as an easy way to incorporate those formats for their use +with Protobuf messages. The Json and XML codecs are examples of this use case. + +### JSON + +It allows to generate or consume JSON formatted strings, which is a very popular +format for REST based web services for example. This codec can be used to communicate +with JavaScript in the browser or with third party REST web services. + +### ProtoJson + +[ProtoJson](https://github.com/drslump/ProtoJson) allows to apply some payload +minification strategies when working with JSON formatted messages. Taking advantatge +of Protobuf's property names mapping to a integer number, it offers two encoding +variants (_TagMap_ and _Indexed_) that use that number instead of the field name +as key in the messages to reduce the total size of the payload. + +### XML + +A very simple codec to work with XML based messages. It has no knowledge of namespaces +and other advanced XML features but should be enough to integrate with third parties +that are restricted to simple XML payloads. It can also serve as a base for more +customized integrations, by extendind this codec to consume and generate XML messages +specific to your service. + + + +## ANNOTATED MESSAGES + +While the most common use case is to use the protoc-gen-php(1) `protoc` plugin to +generate source code representing the messages defined in .proto files, it's also +possible to define messages at runtime without the code generation step. + +An easy way to define messages directly in your code is to use the `Protobuf\AnnotatedMessage` +abstract class, which allows to annotate your classes so that the _codecs_ know how +to parse and serialize those messages. + + class Person extends \DrSlump\Protobuf\AnnotatedMessage { + /** @protobuf(tag=1, type=string, required) */ + public $name; + /** @protobuf(tag=2, type=int32, required) */ + public $id; + /** @protobuf(tag=3, type=string, optional) */ + public $email; + /** @protobuf(tag=4, repeated, type=message, reference=Person) */ + public $friends = array(); + } + + +## EXAMPLES + + + +## BUGS + +Please report bugs using GitHub's issue tracker at http://github.com/drslump/protobuf-php/issues + + +## COPYRIGHT + +Protobuf for PHP is Copyright (C) 2011 Ivan -DrSlump- Montes <http://pollinimini.net> + + +## SEE ALSO + +protoc-gen-php(1), protobuf-php(5), +<http://github.com/drslump/protobuf-php> +