docs: Added additional docs for executeUpdate

[danielgsims]

• Added notes that executeUpdate should be used for insert, update
  and delete statements, which should help quick searching of the
  docs.
• Added an example update using a struct
• Added links in the docs to DML guide

[danielgsims]

Hey @jsimonweb - based on your PR in #2121, we wanted to improve our docs and snippets for our Spanner classes. I've added links to the DML guide, added notes that users can perform INSERT, UPDATE and DELETE statements via our Transaction::executeUpdate method, and included a struct example. Do you feel like this sufficiently improves the docs, or do you have any other suggestions? Thanks!

[jdpedrie]

Did you verify that the struct example works against a real database schema and data?

[jdpedrie]

Move this down near line 363. URLs in the doc text should be formatted as markdown.

[jdpedrie]

remove empty line.

[jdpedrie]

you can assert on nested array data? cool! TIL.

[danielgsims]

Yeah! I found an example someone in phpspec, I'll send it to you if I can find it again.

[codecov]

Codecov Report

Merging #2269 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff            @@
##             master   #2269   +/-   ##
========================================
  Coverage      92.6%   92.6%           
  Complexity     4467    4467           
========================================
  Files           307     307           
  Lines         13323   13323           
========================================
  Hits          12338   12338           
  Misses          985     985

Impacted Files	Coverage Δ	Complexity Δ
Spanner/src/Transaction.php	100% <ø> (ø)	24 <0> (ø)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 92a5dd0...aa7f289. Read the comment docs.

[danielgsims]

Did you verify that the struct example works against a real database schema and data?

This is specifically what I ran and tested against a real dataset:

        $database->runTransaction(function (Transaction $t) use ($spanner) {
            $nameValue = (new StructValue)
                ->add('Title', 'New Title')
                ->add('Content', 'Lorem Ipsum');
            $nameType = (new StructType)
                ->add('Title', Database::TYPE_STRING)
                ->add('Content', Database::TYPE_STRING);

            $rowCount = $t->executeUpdate(
                "UPDATE Posts SET Title = 'New Title' "
                . "WHERE STRUCT<Title STRING, Content STRING>(Title, Content) "
                . "= @post",
                [
                    'parameters' => [
                        'post' => $nameValue
                    ],
                    'types' => [
                        'post' => $nameType
                    ]
                ]);
            $t->commit();
            printf('Updated %d row(s).' . PHP_EOL, $rowCount);
        });

[dwsupplee]

One small nit, otherwise looks nice.

[dwsupplee]

This seems like a pretty nice opportunity to use the fluent interface.

[danielgsims]

For sure! How does this look? Would you rather go all-the-way with (new StructValue())->add()->add()?