UWAGA: witryna została wycofana. Po 31 stycznia 2023 roku witryna zostanie wyłączona, a ruch będzie kierowany do nowej witryny na https://protobuf.dev. Do tego czasu aktualizacje będą dotyczyć tylko protobuf.dev.

Wygenerowany kod PHP

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Na tej stronie znajduje się kod PHP generowany przez kompilator bufora protokołu w przypadku danej definicji protokołu. Zanim przeczytasz ten dokument, przeczytaj przewodnik po języku proto3. Kompilator buforów protokołu obsługuje obecnie tylko generowanie kodu proto3 dla PHP.

Wywołanie kompilatora

Kompilator bufora protokołu generuje polecenie PHP po wywołaniu flagą --php_out=. Parametr opcji --php_out= to katalog, w którym kompilator ma zapisać dane wyjściowe PHP. Aby zapewnić zgodność z PSR-4, kompilator tworzy podkatalog odpowiadający pakietowi zdefiniowanemu w pliku proto. Ponadto dla każdej wiadomości w pliku proto kompilator tworzy oddzielny plik w podkatalogu pakietu. Nazwy plików wyjściowych wiadomości składają się z 3 części:

  • Katalog podstawowy: ścieżka proto (określona flagą --proto_path= lub -I) jest zastępowana ścieżką wyjściową (oznaczoną flagą --php_out=).
  • Podkatalog: . w nazwie pakietu jest zastępowany separatorem katalogu systemu operacyjnego. Każdy komponent nazwy pakietu pisany jest wielkimi literami.
  • Plik: nazwa wiadomości jest dołączona do pliku .php.

Załóżmy na przykład, że wywołujesz kompilator w ten sposób:

protoc --proto_path=src --php_out=build/gen src/example.proto
src/example.proto to definicja:
package foo.bar;
message MyMessage {}

Kompilator odczyta pliki src/foo.proto i wygeneruje plik wyjściowy: build/gen/Foo/Bar/MyMessage.php. Kompilator automatycznie utworzy katalog build/gen/Foo/Bar, ale nie utworzy build ani build/gen – muszą one już istnieć.

Pakiety

Nazwa pakietu zdefiniowana w pliku .proto służy do wygenerowania struktury modułu dla wygenerowanych klas PHP. Podany plik ma postać:

package foo.bar;

message MyMessage {}

Kompilator protokołów generuje klasę danych wyjściowych o nazwie Foo\Bar\MyMessage.

Wiadomości

Oto prosta deklaracja wiadomości:

message Foo {}

Kompilator buforów protokołu generuje klasę PHP o nazwie Foo. Ta klasa dziedziczy ze wspólnej klasy podstawowej Google\Protobuf\Internal\Message, która zapewnia metody kodowania i dekodowania typów wiadomości, jak w tym przykładzie:

$from = new Foo();
$from->setInt32(1);
$from->setString('a');
$from->getRepeatedInt32()[] = 1;
$from->getMapInt32Int32()[1] = 1;
$data = $from->serializeToString();
try {
  $to->mergeFromString($data);
} catch (Exception $e) {
  // Handle parsing error from invalid data.
  ...
}

Nie twórz własnych podkategorii Foo. Wygenerowane zajęcia nie są przeznaczone do stosowania podklasy i mogą prowadzić do problemów z klasą podstawową.

W wyniku zagnieżdżonych wiadomości pojawia się klasa PHP o tej samej nazwie, poprzedzona komunikatem, który zawiera, a PHP nie obsługuje zagnieżdżonych klas. Jeśli na przykład masz taki element w komórce .proto:

message TestMessage {
  optional int32 a = 1;
  message NestedMessage {...}
}
Kompilator wygeneruje te klasy:
class TestMessage {
  public a;
}

// PHP doesn’t support nested classes.
class TestMessage_NestedMessage {...}
Jeśli nazwa klasy wiadomości jest zarezerwowana (np. Empty), do nazwy klasy zostanie dodany prefiks PB:
class PBEmpty {...}
Udostępniliśmy też opcję poziomu pliku php_class_prefix. Jeśli ta zasada jest określona, jest dołączana do wszystkich wygenerowanych klas wiadomości.

Pola

Dla każdego pola w typie wiadomości dostępne są metody dostępu, które można ustawić i pobrać. Biorąc pod uwagę pole x, możesz napisać:

$m = new MyMessage();
$m->setX(1);
$val = $m->getX();

$a = 1;
$m->setX($a);

Za każdym razem, gdy ustawisz pole, wartość jest sprawdzana pod kątem zadeklarowanego typu tego pola. Jeśli wartość jest nieprawidłowego typu lub jest poza zakresem, zostanie zgłoszony wyjątek. Domyślnie konwersje typu (np. podczas przypisywania wartości do pola lub dodawania elementu do pola powtarzanego) mogą mieć postać liczb całkowitych, zmiennoprzecinkowych i ciągów liczbowych. Niedozwolone konwersje obejmują wszystkie konwersje z tablicy lub obiektów. Konwersje rozszerzone dotyczące zmiany liczby zmiennoprzecinkowej na końcu nie są zdefiniowane.

W tabeli typów wartości skalarnych znajdziesz odpowiedni typ PHP dla każdego bufora protokołu skalarnego.

Pojedyncze pola wiadomości

Pole typu wiadomości domyślnie przyjmuje wartość nil i nie jest tworzone automatycznie po uzyskaniu dostępu do tego pola. Musisz utworzyć wiadomości podrzędne w ten sposób:

$m = new MyMessage();
$m->setZ(new SubMessage());
$m->getZ()->setFoo(42);

$m2 = new MyMessage();
$m2->getZ()->setFoo(42);  // FAILS with an exception

Do pola wiadomości możesz przypisać dowolną instancję, nawet jeśli jest ona także blokowana gdzie indziej (na przykład jako wartość pola w innej wiadomości).

Pola powtarzane

Kompilator bufora protokołu generuje specjalne RepeatedField dla każdego pola powtarzanego. Na przykład w tym polu:

repeated int32 foo = 1;
Możesz użyć wygenerowanego kodu:
$m->getFoo()[] =1;
$m->setFoo($array);

Pola mapy

Kompilator bufora protokołu generuje MapField dla każdego pola mapy. Biorąc pod uwagę to pole:

map<int32, int32> weight = 1;

Za pomocą wygenerowanego kodu możesz wykonać te czynności:

$m->getWeight()[1] = 1;

Wyliczenia

PHP nie ma natywnych wartości typu enum, więc kompilator bufora generuje klasę PHP dla każdego typu wyliczenia w pliku .proto, tak jak w przypadku wiadomości, z wartościami zdefiniowanymi dla każdej wartości. Biorąc pod uwagę te wyliczenie:
enum TestEnum {
  Default = 0;
  A = 1;
}
Kompilator generuje tę klasę:
class TestEnum {
  const DEFAULT = 0;
  const A = 1;
}
Podobnie jak w przypadku wiadomości zagnieżdżona enum będzie przyczyną klasy JavaScript o tej samej nazwie, po której następuje wiadomość i rozdzielonych znakami podkreślenia, ponieważ PHP nie obsługuje zagnieżdżonych klas.
class TestMessage_NestedEnum {...}
Jeśli nazwa klasy lub wartości wyliczenia jest zarezerwowana (np. Empty), do nazwy klasy lub wartości dołączany jest prefiks PB:
class PBEmpty {
  const PBECHO = 0;
}
Dodaliśmy też opcję poziomu pliku php_class_prefix. Jeśli określisz tę wartość, zostanie ona dołączona do wszystkich wygenerowanych klas wyliczenia.

Oneof

W przypadku jednego z narzędzi kompilatora bufora protokołu generuje ten sam kod co w przypadku pojedynczych pojedynczych pól, ale dodaje też specjalną metodę dostępu, która daje możliwość sprawdzenia, które pole jest ustawione. Biorąc pod uwagę tę wiadomość:

message TestMessage {
  oneof test_oneof {
    int32 oneof_int32 = 1;
    int64 oneof_int64 = 2;
  }
}

Kompilator generuje te pola i specjalną metodę:

class TestMessage {
  private oneof_int32;
  private oneof_int64;
  public function getOneofInt32();
  public function setOneofInt32($var);
  public function getOneofInt64();
  public function setOneofInt64($var);
  public function getTestOneof();  // Return field name
}

Nazwa metody dostępu jest oparta na nazwie i zwraca wartość enum odpowiadającą polu, które jest obecnie ustawione.