Add PHP Cron Monitor upserts (#7133)

Co-authored-by: Shana Matthews <[email protected]>

src/platform-includes/crons/setup/php.mdx

@@ -17,9 +17,9 @@ SentrySdk::getCurrentHub()->captureEvent($event);
 // 🟢 Notify Sentry your job has completed successfully:
 $event = Event::createCheckIn();
 $event->setCheckIn(new CheckIn(
-    id: $checkIn->getId(),
     monitorSlug: '<monitor-slug>',
     status: CheckInStatus::ok(),
+    id: $checkIn->getId(),
 ));
 SentrySdk::getCurrentHub()->captureEvent($event);
 ```
@@ -30,9 +30,9 @@ If your job execution fails, you can notify Sentry about the failure:
 // 🔴 Notify Sentry your job has failed:
 $event = Event::createCheckIn();
 $event->setCheckIn(new CheckIn(
-    id: $checkIn->getId(),
     monitorSlug: '<monitor-slug>',
     status: CheckInStatus::error(),
+    id: $checkIn->getId(),
 ));
 SentrySdk::getCurrentHub()->captureEvent($event);
 ```
@@ -49,6 +49,9 @@ $event = Event::createCheckIn();
 $checkIn = new CheckIn(
     monitorSlug: '<monitor-slug>',
     status: CheckInStatus::ok(),
+    release: '1.0.0', // Optional release of your application
+    environment: 'production', // Optional environment your cron is running on
+    duration: 10, // Optional duration in seconds
 );
 $event->setCheckIn($checkIn);
 SentrySdk::getCurrentHub()->captureEvent($event);
@@ -60,9 +63,70 @@ If your job execution fails, you can:
 // 🔴 Notify Sentry your job has failed:
 $event = Event::createCheckIn();
 $event->setCheckIn(new CheckIn(
-    id: $checkIn->getId(),
     monitorSlug: '<monitor-slug>',
     status: CheckInStatus::error(),
+    id: $checkIn->getId(),
+    release: '1.0.0', // Optional release of your application
+    environment: 'production', // Optional environment your cron is running on
+    duration: 10, // Optional duration in seconds
+));
+SentrySdk::getCurrentHub()->captureEvent($event);
+```
+
+## Upserting Cron Monitors
+
+You can create and update your Monitors programmatically with code
+rather than [creating and configuring them in Sentry.io](https://sentry.io/crons/create/).
+
+```php
+// Create a crontab schedule object (every 10 minutes)
+$monitorSchedule = MonitorSchedule::crontab('*/10 * * * *');
+
+// Or create an interval schedule object (every 10 minutes)
+$monitorSchedule = MonitorSchedule::interval(10, MonitorScheduleUnit::minute());
+```
+
+Supported units are:
+
+- `MonitorScheduleUnit::minute()`
+- `MonitorScheduleUnit::hour()`
+- `MonitorScheduleUnit::day()`
+- `MonitorScheduleUnit::week()`
+- `MonitorScheduleUnit::month()`
+- `MonitorScheduleUnit::year()`
+
+```php
+// Create a config object
+$monitorConfig = new MonitorConfig(
+    $monitorSchedule,
+    checkinMargin: 5, // Optional check-in margin in minutes
+    maxRuntime: 15, // Optional max runtime in minutes
+    timezone: 'Europe/Vienna', // Optional timezone
+);
+
+// 🟡 Notify Sentry your job is running:
+$event = Event::createCheckIn();
+$checkIn = new CheckIn(
+    monitorSlug: '<monitor-slug>',
+    status: CheckInStatus::inProgress(),
+    release: '1.0.0', // Optional release of your application
+    environment: 'production', // Optional environment your cron is running on
+    monitorConfig: $monitorConfig,
+);
+$event->setCheckIn($checkIn);
+SentrySdk::getCurrentHub()->captureEvent($event);
+
+// Execute your scheduled task here...
+
+// 🟢 Notify Sentry your job has completed successfully:
+$event = Event::createCheckIn();
+$event->setCheckIn(new CheckIn(
+    monitorSlug: '<monitor-slug>',
+    status: CheckInStatus::ok(),
+    id: $checkIn->getId(),
+    release: '1.0.0', // Optional release of your application
+    environment: 'production', // Optional environment your cron is running on
+    monitorConfig: $monitorConfig,
 ));
 SentrySdk::getCurrentHub()->captureEvent($event);
 ```