Clean up examples (#1773)

* renamed NewExample to ExampleTemplate and added comments

* added file comments to other examples

* renamed stripe_webhook_handler to ThinEventWebhookHandler for clarity

* changed verbiage in readme

examples/ExampleTemplate.php

@@ -0,0 +1,40 @@
+<?php
+
+/**
+ * This is a template for defining new examples.  It is not intended to be used directly.
+ *
+ * <describe what this example does>
+ *
+ * In this example, we:
+ *   - <key step 1>
+ *   - <key step 2
+ *   - ...
+ *
+ * <describe assumptions about the user's stripe account, environment, or configuration;
+ * or things to watch out for when running>
+ */
+require 'vendor/autoload.php'; // Make sure to include Composer's autoload file
+// Use this require statement to import the SDK from this repo folder
+// require '../init.php';
+
+class ExampleTemplate
+{
+    private $apiKey;
+
+    public function __construct($apiKey)
+    {
+        $this->apiKey = $apiKey;
+    }
+
+    public function doSomethingGreat()
+    {
+        echo "Hello World\n";
+        // $client = new \Stripe\StripeClient($this->apiKey);
+    }
+}
+
+// Usage
+$apiKey = '{{API_KEY}}';
+
+$example = new ExampleTemplate($apiKey);
+$example->doSomethingGreat();

examples/MeterEventStream.php

@@ -1,5 +1,16 @@
 <?php
 
+/**
+ * Use the high-throughput MeterEventStream to report create billing meter events.
+ *
+ * In this example, we:
+ *   - create a meter event session and store the session's authentication token
+ *   - define an event with a payload
+ *   - use the meterEventStream service to create an event stream that reports this event
+ *
+ * This example expects a billing meter with an event_name of 'alpaca_ai_tokens'.  If you have
+ * a different meter event name, you can change it before running this example.
+ */
 require 'vendor/autoload.php'; // Make sure to include Composer's autoload file
 
 class MeterEventStream

examples/README.md

@@ -3,9 +3,14 @@
 From the examples folder, run:
 `php your_example.php`
 
+e.g.
+
+`php ThinEventWebhookHandler.php`
+
 ## Adding a new example
 
-1. Clone new_example.php
+1. Clone ExampleTemplate.php
 2. Implement your example
-3. Run it (as per above)
-4. 👍
+3. Fill out the file comment. Include a description and key steps that are being demonstrated.
+4. Run it (as per above)
+5. 👍

examples/stripe_webhook_handler.php → examples/ThinEventWebhookHandler.php

@@ -1,5 +1,14 @@
 <?php
 
+/**
+ * Receive and process thin events like the v1.billing.meter.error_report_triggered event.
+ *
+ * In this example, we:
+ *   - use parseThinEvent to parse the received thin event webhook body
+ *   - call StripeClient.v2.core.events.retrieve to retrieve the full event object
+ *   - if it is a V1BillingMeterErrorReportTriggeredEvent event type, call fetchRelatedObject
+ *     to retrieve the Billing Meter object associated with the event.
+ */
 require 'vendor/autoload.php';
 
 $api_key = getenv('STRIPE_API_KEY');