grpc / grpc/grpc.io

PHP Basics tutorial has multiple issues

Open
#1,274 3 comments 1 reaction 0 assignees View on GitHub
Dominant language
HTML
Stars
479
Forks
545
Avg merge
2d 7h
Merged PRs (30d)
5

Description

There are multiple issues with https://grpc.io/docs/languages/php/basics/.

### Instructions to build `grpc_php_plugin` appear to be outdated.

This section produces an error:

> ```
> $ cd grpc
> $ mkdir -p cmake/build
> $ pushd cmake/build
> $ cmake ../..
> $ make protoc grpc_php_plugin
> $ popd
> ```
>
> Then change to route guide directory and compile the example’s .proto files:
>
> ```
> $ cd examples/php/route_guide
> $ ./route_guide_proto_gen.sh
> ```

The script errors:

```
./route_guide_proto_gen.sh: line 25: bazel-bin/external/com_google_protobuf/protoc: No such file or directory
```

Instead, the instructions should say to use bazel as in https://github.com/grpc/grpc/issues/25350#issuecomment-773688947:

```
./tools/bazel build @com_google_protobuf//:protoc
./tools/bazel build src/compiler:grpc_php_plugin
```

### The node server has moved

This section produces an error:

> To try the sample app, we need a gRPC server running locally. Let’s compile and run, for example, the Node.js server in this repository:
>
> ```
> $ cd ../../node
> $ npm install
> ```

`nmp install` errors:

```
$ npm install
npm ERR! Cannot use 'in' operator to search for 'bundleDependencies' in These examples have been moved to https://github.com/grpc/grpc-node/tree/master/examples
```

This is because the package.json is just a string:

```
$ cat package.json
"These examples have been moved to https://github.com/grpc/grpc-node/tree/master/examples"
```

I'd suggest simply linking to https://github.com/grpc/grpc-node/tree/master/examples/routeguide but there are no instructions there for running the route guide example. So perhaps it would be better to give people specific instructions to run the node server inside the php examples directory:

```
$ git clone https://github.com/grpc/grpc-node.git
$ cd grpc-node/
$ npm install
$ cd dynamic_codegen/
$ node ./route_guide_server.js --db_path=route_guide_db.json
```

Note that the current instructions have the `node` command incorrectly written as `nodejs`:

```
$ nodejs ./route_guide_server.js --db_path=route_guide_db.json
fish: Unknown command: nodejs
```

#### Client script fails

```
$ ./run_route_guide_client.sh
```

eventually hits this error:

```
Running RecordRoute...
PHP Fatal error: Uncaught TypeError: count(): Argument #1 ($value) must be of type Countable|array, string given in grpc/examples/php/route_guide/route_guide_client.php:115
Stack trace:
#0 grpc/examples/php/route_guide/route_guide_client.php(203): runRecordRoute()
#1 grpc/examples/php/route_guide/route_guide_client.php(212): main()
#2 {main}
thrown in grpc/examples/php/route_guide/route_guide_client.php on line 115
```

This is because:

```
$ cat ../../node/static_codegen/route_guide/route_guide_db.json
"These examples have been moved to https://github.com/grpc/grpc-node/tree/master/examples"
```

Pointing `run_route_guide_client.sh` to `./grpc-node/examples/routeguide/static_codegen/route_guide_db.json` fixes the issue.

### Fix

I'd be happy to make a PR to fix these instructions if there's agreement that cloning `grpc-node` into the `examples/php/route_guide` directory makes sense.

Contributor guide

Open the contributing guide

Research direction

Start with the PHP Basics tutorial at grpc.io/docs/languages/php/basics/ and inspect examples/php/route_guide/route_guide_proto_gen.sh and run_route_guide_client.sh, along with the referenced grpc-node routeguide examples. Verify the documented build, server, and client commands against the reported errors; done means the tutorial points to current locations and the route guide flow runs successfully.

Written by the indexing model from the issue text.

Assessment

Tech stack
node.js, php, shell
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.