phpdbgのヘルプを和訳してみた

PHP 5.6からPHP本体に同梱になったデバッガphpdbgですが、PHPマニュアル内に詳細の記述がないなどドキュメントが不足している印象があります。そこで、PHP 7.1.0RC6に同梱のphpdbgのヘルプ（個別コマンドについては一部のみ）を和訳してみました。後述するようにGoogle翻訳で下訳を行い、必要分のみ修正したものです。

# help (概要)

```
prompt> help

phpdbgは軽量で強力で使いやすいPHP5.4+用のデバッグプラットフォームです。
次のコマンドをサポートしています：

情報
  list      PHPソースを一覧表示する
  info      デバッグセッションに関する情報を表示します
  print     オペコードを表示する
  frame     スタックフレームを選択し、スタックフレームサマリーを表示する
  generator アクティブなジェネレータを表示するか、ジェネレータフレームを選択する（訳注：PHP7.1以降）
  back      現在のバックトレースを表示します
  help      トピックに関するヘルプを提供する

実行の開始と停止
  exec      実行コンテキストを設定する
  stdin     標準入力から実行スクリプトを設定する（訳注：PHP7.1以降）
  run       実行を試みる
  step      別の行に到達するまで実行を続行する
  continue  実行を続ける
  until     指定された場所まで実行を続行する
  next      指定された場所まで実行を継続し、その後に最初の行で停止する
  finish    現在の実行フレームの最後まで継続する
  leave     現在の実行フレームの最後まで継続し、呼び出し命令の後で停止する
  break     指定されたターゲットにブレークポイントを設定する
  watch     $variableにウォッチポイントを設定する
  clear     1つまたはすべてのブレークポイントを消去する
  clean     実行環境をきれいにする

その他
  set       phpdbg設定の変更
  source    phpdbginitスクリプトを実行する
  register  phpdbginit関数をコマンドエイリアスとして登録する
  sh        シェル経由でコマンドを実行する（訳注：内部的にはpopen(3)する）
  ev        いくつかのコードを評価する
  quit      phpdbgを終了する

help <command>またはhelp <alias>と入力すると、上記のコマンドの詳細なヘルプを表示できます（例：help list または h l）。
一意であればhelpはコマンドの先頭部分とマッチします（また、一意でなければオプションを表示します）。つまり、help cleaは
cleanコマンドのヘルプを表示しますが、help clだとをcleanとclearのサマリを表示します。
（訳注：help cleaでもcleanとclearのサマリが表示されてしまいます。例が悪いですね）

help aliasと入力すると、登録済みのphpdginit関数を含め、エイリアスリスト全体を表示できます
help syntaxと入力すると、コマンド構文の一般的な説明が表示されます。
phpdbgコマンドラインオプションのリストについては、help optionsと入力してください。
help phpdbginitと入力すると、デバッガ環境をカスタマイズする方法を示します。
```

# help aliases

```
prompt> help aliases
以下はエイリアス（サポートされている全コマンドの短いバージョン）です。
 e     exec                  実行コンテキストを設定する
 s     step                  ステップスルー実行
 c     continue              実行を続ける
 r     run                   実行を試みる
 u     until                 現在の行が終了して別の行に行くまで実行を続行する
 F     finish                スタックが終わって別の関数に移るまで実行を続行する
 L     leave                 スタックの終わりまで実行を続行する
 g     generator             アクティブなジェネレータ一覧を表示、またはジェネレータフレームに移動する
 p     print                 何かを表示する
 p e   print exec            メイン実行コンテキストでオペコードを出力する
 p o   print opline          現在位置のオペコードを出力する
 p c   print class           指定されたクラスのオペコードを出力する
 p m   print method          指定されたメソッドのオペコードを出力する
 p f   print func            指定された関数のオペコードを出力する
 p s   print stack           現在のスタック内のオペコードを出力する
 b     break                 ブレークポイントを設定する
 b @   break at              場所と条件でブレークポイントを指定する
 b ~   break del             ブレークポイント番号でブレークポイントを削除する
 t     back                  バックトレースを表示する
 f     frame                 フレームを切り替える
 l     list                  ソースコードを表示する
 l l   list lines            指定された行のソースコードを表示する
 l c   list class            指定されたクラスのソースコードを表示する
 l m   list method           指定されたメソッドのソースコードを表示する
 l f   list func             指定された関数のソースコードを表示する
 i     info                  情報を表示する
 i b   info break            ブレークポイントを表示する
 i F   info files            インクルードファイルを表示する
 i c   info classes          ロードされたクラスを表示する
 i f   info funcs            ロードされた関数を表示する
 i e   info error            最後のエラーを表示
 i d   info constants        ユーザ定義の定数を表示する
 i v   info vars             アクティブ変数を表示する
 i g   info globals          スーパーグローバル変数を表示する
 i l   info literal          アクティブなリテラル定数を表示する
 i m   info memory           メモリマネージャの統計情報を表示する
 X     clean                 実行環境をきれいにする
 C     clear                 ブレークポイントをクリアする
 S     set                   phpdbg設定を設定する
 S p   set prompt            usage: set prompt [<string>]
 S P   set pagination        usage: set pagination [<on|off>]
 S c   set color             usage: set color  <element> <color>
 S C   set colors            usage: set colors [<on|off>]
 S O   set oplog             usage: set oplog  [<output>]
 S b   set break             usage: set break id [<on|off>]
 S B   set breaks            usage: set breaks [<on|off>]
 S q   set quiet             usage: set quiet [<on|off>]
 S s   set stepping          usage: set stepping [<line|op>]
 S r   set refcount          usage: set refcount [<on|off>]
 S l   set lines             usage: set lines [<number>]
 R     register              関数を登録する
 <     source                phpdbginitを読み込む
 >     export                ブレークポイントを.phpdbginitスクリプトにエクスポートする
 q     quit                  phpdbgを終了する
 W     wait                  他のプロセスを待つ
 w     watch                 ウォッチポイントを設定する
 w a   watch array           配列にウォッチポイントを作成する
 w d   watch delete          ウォッチポイントを削除する
 w r   watch recursive       再帰ウォッチポイントを作成する
 n     next                  次の行にステップオーバー
 E     eol                   EOLを設定する
 h     help                  ヘルプメニューを表示

 h a   help aliases          エイリアスリストを表示する

コマンドやサブコマンドのキーワード、あるいはその両方にエイリアスを使うことができます。つまり、info bは
info breakの同義語であり、l funcならlist func、といった調子です。

helpもまたパラメータとしてエイリアスを受け入れ、そのコマンドのヘルプを提供します。たとえば、h pは
printコマンドのヘルプを提供します。
```

# help syntax

```
prompt> help syntax

コマンドはキーワードで始まり、一部のコマンド（break、info、set、print、list）にはサブコマンドキーワードが含まれています。
すべてのキーワードは小文字ですが、キーワード全部を入力する代わりに1文字のエイリアスを使用することもできます。
いくつかのエイリアスは大文字であり、そのエイリアスでしかキーワードを省略することはできないことに注意してください。
（訳注：set paginationを省略したかったらS Pとしか書けないという意味だと思いますが、実際にはse paとも書けます。）

いくつかのコマンドは引数をとります。 引数はそのフォーマットごとに分類されます：
     *  omitted
     *  address      0xに続く16進文字列
     *  number       符号付き数値
     *  method       有効な [クラス]::[メソッド名] の表現
     *  func#op      有効な [関数名]＃整数（オペコード番号）
     *  method#op    有効な [クラス]::[メソッド名]#整数（オペコード番号）
     *  string       一般的な文字列
     *  function     有効な関数名
     *  file:line    有効なファイル名:整数（行番号）

引数の型によっては、2番目のキーワードを省略することができます。

すべてのコマンドの概要を表示するにはhelpと入力し、特定のコマンドの詳細なヘルプを表示するにはhelp <command>と入力します。

有効な例

     prompt>  quit
     prompt>  q
     デバッガを終了する

     prompt>  ev $total[2]
     現在のスタックフレーム内の変数$total[2]を評価して出力する

     prompt>  break 200
     prompt>  b my_source.php:200
     現在のソースの200行目とファイルmy_source.phpの200行目でブレークする

     prompt>  b @ ClassX::get_args if $arg[0] == "fred"
     prompt>  b ~ 3
     $arg[0] == "fred"ならばClassX::get_args（）でブレークし、ブレークポイント3を削除する

無効なコマンドの例
     prompt>  #This is a comment
     ＃からはじまるコメントは、phpdbginitスクリプトファイルでのみ許可されます。
```

# help options

```
prompt> help options

以下は、phpdbgでサポートされているコマンドラインオプションです。

コマンドラインオプションとフラグ
  オプション 実行例　　　　　　　　　　　　　　　　　　　　　　    説明
  -c      -c/my/php.ini       ロードするphp.iniファイルを設定する
  -d      -dmemory_limit=4G   php.iniディレクティブを設定する
  -n                          デフォルトのphp.iniを無効にする
  -q                          ウェルカムバナーを抑制する
  -v                          oplog出力を有効にする
  -b                          色を無効にする
  -i      -imy.init           .phpdbginitファイルを設定する
  -I                          デフォルトの.phpdbginitを無視する
  -O      -Omy.oplog          oplog出力ファイルを設定する
  -r                          実行コンテキストを実行する
  -rr                         実行コンテキストを実行し、実行後に終了する（ブレークポイントには依存しない）
  -e                          デバッガ/プロファイラ向けの拡張情報を生成する
  -E                          ステップスルーevalを有効にする（慎重に使ってね！）
  -s      -s=, -s=foo         標準入力から実行するコードを読み込む
  -S      -Scli               SAPI名を上書きする（慎重に使ってね！）
  -l      -l4000              リモートコンソールポートの設定
  -a      -a192.168.0.3       リモートコンソールのバインドアドレスの設定
  -x                          xml出力を有効にする（通常のテキスト出力ではなく）
  -p      -p, -p=func, -p*    オペコードを出力して終了する
  -h                          ヘルプの概要を表示する
  -V                          バージョン番号を表示する
  --      -- arg1 arg2        後ろにPHPの引数$argvを追加する（phpdbg引数とPHPの$argvを区切るために使用します）

標準入力からの読み込み

-sオプションを使用すると、標準入力からスクリプトを直接実行することができます。 与えられた区切り文字（上の例では "foo"）は、
入力の終わりを指定する独立した行で、区切り文字の後に改行をつける必要があります。-rrが指定されている場合は、
デリミタ（-s=）を省略することができ、EOFまで読み込みます。 stdinコマンドのヘルプ項目も参照してください。

リモートコンソールモード

このモードは、-aオプションを指定すると有効になります。phpdbgは、デフォルトでループバックインターフェイスにのみバインドします。
これは、-aオプションを使用してリモートコンソールのバインドアドレスを明示的に設定することによってのみ上書きできます。
引数なしで-aを指定すると、phpdbgは利用可能なすべてのインタフェースにバインドされます。
これを行うことによるセキュリティへの影響に注意してください。
つまり、公開されているインターフェイス/ポートにバインドされる場合は、このサービスを保護するための対策を講じる必要があります。

オペコード出力

オペコードを出力するには、最後の引数としてファイルパスを渡す必要があります。
実行モード:
-p メイン実行コンテキストを出力します。
-p* ファイル全体（クラスおよび関数を含む）のすべてのオペコードを出力します。
-p=function_name 指定された関数のオペコードを出力する
-p=class_name:: 指定されたクラスのすべてのメソッドのオペコードを出力する
-p=class_name::method 指定されたメソッドのオペコードを出力する
```

# help phpdbginit

```
prompt> help phpdbginit

phpdgbは、デバッガスクリプトファイルを使用してデバッガコンテキストを初期化します。
デフォルトでは、phpdbgは現在の作業ディレクトリで.phpdbginitという名前のファイルを探します。
デバッガスクリプトファイルの位置は、コマンドラインから-iスイッチを使って上書きすることができます（詳細はヘルプオプションを参照してください）。

デバッガスクリプトファイルは、sourceコマンドを使用して実行することもできます。

デバッガスクリプトファイルには、有効なデバッガコマンド、コメント、埋め込みPHPコードを組み合わせて含めることができます。

コメント行の先頭には＃文字が付きます。 コメントは、デバッガスクリプトファイルでのみ許可され、
インタラクティブセッションでは許可されないことに注意してください。

PHPコードは、開始エスケープタグと終了エスケープタグ<：と：>によって区切られます。 PHPコードを使用してデバッグセッションの
アプリケーションコンテキストを定義したり、PHP関数を新しいコマンドとして定義して登録したりすることによってデバッガを拡張することができます。

clearコマンドを実行すると、現在のphpdbginitが再解析/再ロードされます。
```

# help break

```
prompt> help break
Command: break  Alias: b  set breakpoint

ブレークポイントは、実行環境内のターゲットの範囲で設定できます。プログラムフローがブレークポイントに達すると、実行が一時停止されます。

ブレークターゲットには、次のタイプのいずれかを指定できます。

  ターゲット  エイリアス  目的
  at       A        場所と条件でブレークポイントを指定する
  del      d        ブレークポイント識別子番号でブレークポイントを削除する

break atには2つの引数があります。最初は有効なターゲットです。2番目の引数は有効なPHP式で、指定されたターゲットにおいて
真偽値としてtrueと評価された場合にブレークします。

ブレークポイントは、set breakコマンドで無効にしたり、再度有効にすることもできます。

例

    prompt>  break test.php:100
    prompt>  b test.php:100
    test.phpの100行目でブレークする

    prompt>  break 200
    prompt>  b 200
    現在のPHPスクリプトファイルの200行目でブレークする

    prompt>  break \mynamespace\my_function
    prompt>  b \mynamespace\my_function
    \mynamespace\my_functionの先頭でブレークする

    prompt>  break classX::method
    prompt>  b classX::method
    classX::methodの先頭でブレークする

    prompt>  break 0x7ff68f570e08
    prompt>  b 0x7ff68f570e08
    アドレス0x7ff68f570e08のoplineで中断する

    prompt>  break my_function#14
    prompt>  b my_function#14
    関数のmy_functionのopline＃14でブレークする

    prompt>  break \my\class::method#2
    prompt>  b \my\class::method#2
    メソッド\my\class::methodのopline＃2でブレークする

    prompt>  break test.php:#3
    prompt>  b test.php:#3
    test.phpのopline＃3でブレークする

    prompt>  break if $cnt > 10
    prompt>  b if $cnt > 10
    条件（$cnt>10）がtrueと評価されたときに中断する

    prompt>  break at phpdbg::isGreat if $opt == 'S'
    prompt>  break @ phpdbg::isGreat if $opt == 'S'
    条件（$opt == 'S'）が真の場合、phpdbg::isGreatの任意のオペコードでブレークします

    prompt>  break at test.php:20 if !isset($x)
    条件がtrueと評価されたとき、test.phpの20行目のすべてのオペコードでブレークします。

    prompt>  break ZEND_ADD
    prompt>  b ZEND_ADD
    オペコードZEND_ADDが出現したらブレークする

    prompt>  break del 2
    prompt>  b ~ 2
    ブレークポイント2を削除

注: 条件付きブレークは実行時オーバーヘッドの観点でコストがかかります。実行が著しく遅くなるので、必要なときにのみ使用してください。

注：アドレスの指定は現在のコンパイル結果でのみ有効です。
```

# help generator

```
prompt> help generator
Command: generator  Alias: g  inspect or switch to a generator

generatorコマンドは、オプションの整数引数をとります。省略すると、現在アクティブなジェネレータの一覧が表示されます。
指定されている場合、現在のスコープは、対応するオブジェクトハンドルを持つジェネレータのフレームに設定されます。
これは、現在のバックトレースにないジェネレータを検査するために使用できます。

例

    prompt>  generator
    ジェネレータの一覧を表示する#idがオブジェクトハンドル。例：
    #3: my_generator(argument="value") at test.php:5
    prompt>  g 3
    prompt>  ev $i
    オブジェクトハンドル3のジェネレータのフレームに移動し、そのフレームの変数$iを出力します。

このフレームスコープは、実行を再開すると破棄され、実行フレームは実行中の最下層のフレームにリセットされます。
```

# help set

```
prompt> help set
Command: set  Alias: S  set phpdbg configuration

setコマンドは、phpdbgの見た目と動作を設定するために使用します。具体的なsetコマンドは次のとおりです。

   タイプ   エイリアス  目的
   prompt     p     set the prompt
   color      c     set color  <element> <color>
   colors     C     set colors [<on|off>]
   oplog      O     set oplog [output]
   break      b     set break id <on|off>
   breaks     B     set breaks [<on|off>]
   quiet      q     set quiet [<on|off>]
   stepping   s     set stepping [<opcode|line>]
   refcount   r     set refcount [<on|off>]

有効な色は none, white, red, green, yellow, blue, purple, cyan, black です。
none以外のすべての色の後に、オプションの-boldまたは-underline修飾子を付けることができます。

Color elements can be one of prompt, notice, or error.

例

     prompt>  S C on
     カラー表示を有効にする

     prompt>  set p >
     prompt>  set color prompt white-bold
     プロンプトをボールドの>にする

     prompt>  S c error red-bold
     エラー表示を赤・太字にする

     prompt>  S refcount on
     ウォッチポイントにヒットしたときに参照カウント表示を有効にする

     prompt>  S b 4 off
     一時的にブレークポイント4を無効にします。これは、後でS b 4 onによって再び有効にすることができます。
```

# help watch

```
prompt> help watch
Command: watch  Alias: w  set watchpoint


変数が定義されていれば、ウォッチポイントを変数に設定します。
watchにパラメータを渡さなければ、アクティブなウォッチポイントを一覧表示します。

$variableの書式

   $var      変数$var
   $var[]    $varのすべての配列要素
   $var->    $varのすべてのプロパティ
   $var->a   プロパティ$var->a
   $var[b]   配列$varのキーbを持つ配列要素

watchのサブコマンド:

   タイプ 　   エイリアス    目的
   array       a       配列/オブジェクトのウォッチポイントを設定する（エントリが追加または削除されたかどうかを監視する）
   recursive   r       変数を再帰的に監視し、配列/オブジェクトに何らかのエントリが追加された場合にウォッチポイントを自動的に追加する
   delete      d       ウォッチポイントを削除する

再帰ウォッチポイントが削除されると、すべての子ウォッチポイントも削除されます。

例

     prompt>  watch
     現在アクティブなウォッチポイントを一覧表示する

     prompt>  watch $array
     prompt>  w $array
     $arrayにウォッチポイントを設定する

     prompt>  watch recursive $obj->
     prompt>  w r $obj->
     $obj->に再​​帰ウォッチポイントを設定する

     prompt>  watch delete $obj->a
     prompt>  w d $obj->a
     ウォッチポイント$obj->aを削除する

テクニカルノート: デバッガ上でこの機能を使用すると、ウォッチされたアドレスを含むメモリページにヒットするたびに、
             多くのセグメンテーションフォールトが発生します。そこで実行を続けると、phpdbgが書き込み保護を解除し、
             プログラムを続行できます。phpdbgがそのセグメンテーションフォールトを処理できなかった場合、
             同じセグメンテーションフォールトが再びトリガされ、今度はphpdbgが異常終了します。
```

# Google翻訳についての所感

Google翻訳の翻訳結果を見て、違和感が大きいものだけ自力で真面目に翻訳する、ということをしてみました。真面目に測定したわけではありませんが、感覚的には6割くらいをそのまま採用、もう1割くらいは簡単な微調整のみで取り込めたように思います。

旧Google翻訳をそれほど使っていたわけではないので新しくなってどれほど訳文の品質が向上したかはわかりません。とはいえ、技術文章でもかなり良い和訳を提示するという印象を持ちました（ジャンルによるのかもしれませんが）。特に短い文章では修正が不要なことが多く、今回のように「コマンド名と1行説明」の羅列が多いような場合はかなり有効だと感じました。

## 訳語の統一について

Google翻訳の利用で注意しないといけないと感じた点は訳語の統一についてです。新Google翻訳の魅力は文脈に適した訳語選択をしてくれるところだと感じましたが、逆にどの単語を選択しても大差ない状況で訳語がぶれやすいように感じました（簡単な例ではデバッガとデバッガーなど）。

しかし、この性質は長い文章の翻訳においては好ましくありません。原文で同じ単語だったものが訳文でブレてしまうと読者が混乱してしまうので、翻訳において訳語の統一は重要なテーマです。現状のGoogle翻訳にはこれをサポートする機能は無さそうですので、現状では翻訳者が逐一訳語の修正・統一をしていくしかなさそうです。