• Home
Name
Date
Size
#Lines
LOC

..--

ext/google/protobuf/12-May-2024-17,78612,966

src/12-May-2024-19,6829,449

tests/12-May-2024-9,6187,461

README.mdD12-May-20243.7 KiB140106

composer.jsonD12-May-2024739 3029

generate_descriptor_protos.shD12-May-2024401 1710

phpunit.xmlD12-May-2024676 1918

release.shD12-May-2024665 3823

README.md

1 This directory contains the Protocol Buffers runtime implementation via both a
2 pure PHP package and a native c extension. The pure PHP package is intended to
3 provide usability to wider range of PHP platforms, while the c extension is
4 intended to provide higher performance. Both implementations provide the same
5 runtime APIs and share the same generated code. Users don’t need to re-generate
6 code for the same proto definition when they want to switch the implementation
7 later.
8 
9 Both implementations make use of generated PHP code that defines message and
10 enum types in PHP. We strongly recommend using protoc's PHP generation support
11 with .proto files. The build process in this directory only installs the
12 extension/package; you need to install protoc as well to have PHP code
13 generation functionality.
14 
15 ## Requirements
16 
17 To use PHP runtime library requires:
18 
19 - C extension: PHP 5.5, 5.6, or 7.
20 - [PHP package](http://php.net/downloads.php): PHP 5.5, 5.6 or 7.
21 
22 ## Installation
23 
24 ### C Extension
25 
26 #### Prerequirements
27 
28 To install the c extension, the following tools are needed:
29 * autoconf
30 * automake
31 * libtool
32 * make
33 * gcc
34 * pear
35 * pecl
36 
37 On Ubuntu, you can install them with:
38 ```
39 sudo apt-get install -y php-pear php5-dev autoconf automake libtool make gcc
40 ```
41 On other platforms, please use the corresponding package managing tool to
42 install them before proceeding.
43 
44 #### Installation from Source (Building extension)
45 
46 To build the c extension, run the following command:
47 ```
48 cd ext/google/protobuf
49 pear package
50 sudo pecl install protobuf-{VERSION}.tgz
51 ```
52 
53 #### Installation from PECL
54 
55 When we release a version of Protocol Buffers, we will upload the extension to
56 [PECL](https://pecl.php.net/). To use this pre-packaged extension, simply
57 install it as you would any other extension:
58 
59 ```
60 sudo pecl install protobuf-{VERSION}
61 ```
62 
63 ### PHP Package
64 
65 #### Installation from composer
66 
67 Simply add "google/protobuf" to the 'require' section of composer.json in your
68 project.
69 
70 ### Protoc
71 
72 Once the extension or package is installed, if you wish to generate PHP code
73 from a `.proto` file, you will also want to install the Protocol Buffers
74 compiler (protoc), as described in this repository's main `README` file.  The
75 version of `protoc` included in the latest release supports the `--php_out`
76 option to generate PHP code:
77 ```
78 protoc --php_out=out_dir test.proto
79 ```
80 
81 ## Usage
82 
83 For generated code:
84   https://developers.google.com/protocol-buffers/docs/reference/php-generated
85 
86 Known Issues
87 ------------
88 
89 * Missing native support for well known types.
90 * Missing support for proto2.
91 * No API provided for clear/copy messages.
92 * No API provided for encoding/decoding with stream.
93 * Map fields may not be garbage-collected if there is cycle reference.
94 * No debug information for messages in c extension.
95 * HHVM not tested.
96 * C extension not tested on windows, mac, php 7.0.
97 * Message name cannot be Empty.
98 
99 ## Development
100 
101 ### Docker Image
102 
103 We provide a docker image for php development, which is also used in our automatic tests:
104 ```
105 docker run --security-opt seccomp=unconfined -it protobuftesting/php_8dbe419c6df1a8b3af0ae3a267c112efb436b45c
106 ```
107 
108 ### Test Native PHP
109 
110 ```
111 # Download protobuf
112 git clone https://github.com/protocolbuffers/protobuf.git
113 cd protobuf
114 
115 # Build protoc
116 ./autogen.sh
117 ./configure
118 make -j4
119 
120 # Test native php
121 cd php
122 composer install
123 composer test
124 ```
125 
126 ### Test C Extension
127 
128 After you have finished testing the native php, you can test the c extension:
129 ```
130 cd tests
131 ./test.sh 5.6 # The php runtime version.
132               # We provide 5.5, 5.5-zts, 5.6, 5.6-zts, 7.0, 7.0-zts, 7.1, 7.1-zts, 7.2, 7.2-zts, 7.3 and 7.3-zts
133               # ls /usr/local for more details
134 ```
135 
136 If you want to use gdb to debug the c extension, you can do:
137 ```
138 ./gdb_test.sh
139 ```
140