php documentation updates (#2654)

content/en/docs/instrumentation/php/automatic.md

@@ -9,7 +9,7 @@ spelling:
 Automatic instrumentation with PHP requires at least PHP 8.0, and
 [the OpenTelemetry PHP extension](https://github.com/open-telemetry/opentelemetry-php-instrumentation).
 The extension allows developers code to hook into classes and methods, and
-execute userland code before and after.
+execute userland code before and after the hooked method runs.
 
 ## Example
 
@@ -21,9 +21,8 @@ OpenTelemetry\Instrumentation\hook(
     'pre': static function (DemoClass $demo, array $params, string $class, string $function, ?string $filename, ?int $lineno) use ($tracer) {
         static $instrumentation;
         $instrumentation ??= new CachedInstrumentation('example');
-        $instrumentation->tracer()->spanBuilder($class)
-            ->startSpan()
-            ->activate();
+        $span = $instrumentation->tracer()->spanBuilder($class)->startSpan();
+        Context::storage()->attach($span->storeInContext(Context::getCurrent()));
     },
     'post': static function (DemoClass $demo, array $params, $returnValue, ?Throwable $exception) use ($tracer) {
         $scope = Context::storage()->scope();
@@ -43,57 +42,60 @@ $demo->run();
 
 Here, we provide `pre` and `post` functions, which are executed before and after
 `DemoClass::run`. The `pre` function starts and activates a span, and the `post`
-function ends it.
+function ends it. If an exception was thrown by `DemoClass::run()`, the `post`
+function will record it, without affecting exception propagation.
 
-## Setup
+## Installation
 
-1. Install the extension via [pickle](https://github.com/FriendsOfPHP/pickle) or
-   [php-extension-installer](https://github.com/mlocati/docker-php-extension-installer)
-   (docker specific):
+The extension can be installed via pecl,
+[pickle](https://github.com/FriendsOfPHP/pickle) or
+[php-extension-installer](https://github.com/mlocati/docker-php-extension-installer)
+(docker specific).
 
-   - **pickle** can be used to install extensions that are available via
-     <http://pecl.php.net>, however that's not the case for
-     opentelemetry-php-instrumentation yet, so the only way for it is to install
-     directly from source code. The following command line shows you how to do
-     that using a specific version of the extension (1.0.0beta2 in this case):
-
-     Installing from source requires proper development environment and few
-     dependencies:
+1. Setup development environment Installing from source requires proper
+   development environment and some dependencies:
 
      <!-- prettier-ignore-start -->
 
-     {{< tabpane lang=shell persistLang=false >}}
+   {{< tabpane lang=shell persistLang=false >}}
 
-     {{< tab "Linux (apt)" >}}sudo apt-get install gcc make autoconf{{< /tab >}}
+   {{< tab "Linux (apt)" >}}sudo apt-get install gcc make autoconf{{< /tab >}}
 
-     {{< tab "MacOS (homebrew)" >}}brew install gcc make autoconf{{< /tab >}}
+   {{< tab "MacOS (homebrew)" >}}brew install gcc make autoconf{{< /tab >}}
 
-     {{< /tabpane >}}
+   {{< /tabpane >}}
      <!-- prettier-ignore-end -->
 
-     With your environment setup you can install the extension:
+2. Build/install the extension With your environment set up you can install the
+   extension:
 
-     ```sh
-     php pickle.phar install --source https://github.com/open-telemetry/opentelemetry-php-instrumentation.git#1.0.0beta2
-     ```
+     <!-- prettier-ignore-start -->
 
-     Add the extension to your `php.ini` file:
+   {{< tabpane lang=shell persistLang=false >}}
 
-     ```ini
-     [Otel instrumentation]
-     extension=otel_instrumentation.so
-     ```
+   {{< tab "pecl" >}}pecl install opentelemetry-beta{{< /tab >}}
 
-   - **php-extension-installer**
+   {{< tab "pickle" >}}php pickle.phar install --source
+   https://github.com/open-telemetry/opentelemetry-php-instrumentation.git#1.0.0beta2{{<
+   /tab >}}
 
-     ```sh
-     install-php-extensions open-telemetry/opentelemetry-php-instrumentation@main
-     ```
+   {{< tab "php-extension-installer (docker)" >}}install-php-extensions
+   opentelemetry{{< /tab >}}
 
-2. Verify that the extension is installed and enabled:
+   {{< /tabpane >}}
+     <!-- prettier-ignore-end -->
+
+3. Add the extension to your `php.ini` file:
+
+   ```ini
+   [opentelemetry]
+   extension=opentelemetry.so
+   ```
+
+4. Verify that the extension is installed and enabled:
 
    ```sh
-   php -m | grep  otel_instrumentation
+   php -m | grep opentelemetry
    ```
 
 ## Zero-code configuration for automatic instrumentation

content/en/docs/instrumentation/php/logging.md

@@ -24,7 +24,7 @@ $loggerProvider = new LoggerProvider(
         new ConsoleExporter()
     )
 );
-$logger = $loggerProvider->getLogger('demo', '1.0', 'http://schema.url', true, [/*attributes*/]);
+$logger = $loggerProvider->getLogger('demo', '1.0', 'http://schema.url', [/*attributes*/]);
 $eventLogger = new EventLogger($logger, 'my-domain');
 ```
 
@@ -39,9 +39,32 @@ $record = (new LogRecord('hello world'))
 $eventLogger->logEvent('foo', $record);
 ```
 
-## Examples
+## Integrations for 3rd-party logging libraries
 
-The
-[monolog-otel-integration example](https://github.com/open-telemetry/opentelemetry-php/blob/main/examples/logs/features/monolog-otel-integration.php)
-demonstrates using the popular Monolog logger to send some logs to a stream (in
-their usual format), as well as sending some logs to an OpenTelemetry collector.
+### Monolog
+
+You can use the
+[monolog handler](https://packagist.org/packages/open-telemetry/opentelemetry-logger-monolog)
+to send monolog logs to an OpenTelemetry-capable receiver:
+
+```shell
+composer require open-telemetry/opentelemetry-logger-monolog
+```
+
+```php
+$loggerProvider = new LoggerProvider(/*params*/);
+
+$handler = new \OpenTelemetry\Contrib\Logs\Monolog\Handler(
+    $loggerProvider,
+    \Psr\Log\LogLevel::ERROR,
+);
+$logger = new \Monolog\Logger('example', [$handler]);
+
+$logger->info('hello, world');
+$logger->error('oh no', [
+    'foo' => 'bar',
+    'exception' => new \Exception('something went wrong'),
+]);
+
+$loggerProvider->shutdown();
+```

content/en/docs/instrumentation/php/sdk.md

@@ -81,6 +81,11 @@ $meter = OpenTelemetry\API\Common\Instrumentation\Globals::meterProvider()->getT
 
 SDK autoloading happens as part of the composer autoloader.
 
+{{% alert title="Important" color="warning" %}}The batch span and log processors
+emit metrics about their internal state, so ensure that you have a correctly
+configured metrics exporter. Alternatively, you can disable metrics by setting
+`OTEL_METRICS_EXPORTER=none`{{% /alert %}}
+
 ## Configuration
 
 The PHP SDK supports most of the

static/refcache.json

@@ -3371,6 +3371,10 @@
     "StatusCode": 200,
     "LastSeen": "2023-03-14T18:07:43.947011+01:00"
   },
+  "https://packagist.org/packages/open-telemetry/opentelemetry-logger-monolog": {
+    "StatusCode": 200,
+    "LastSeen": "2023-05-03T13:01:43.900239313Z"
+  },
   "https://packagist.org/providers/php-http/async-client-implementation": {
     "StatusCode": 200,
     "LastSeen": "2023-03-29T03:57:47.546094076Z"