From d534d8dfb1e382d9f727d611b7f9c8c47c596b34 Mon Sep 17 00:00:00 2001
From: Andrey Helldar <helldar@dragon-code.pro>
Date: Sat, 6 Sep 2025 02:29:29 +0300
Subject: [PATCH] Added `FeedStartingEvent` and `FeedFinishedEvent`

---
 docs/laravel-feeds.tree               |  3 +++
 docs/topics/events.topic              | 27 ++++++++++++++++++++++++
 src/Events/FeedFinishedEvent.php      | 22 ++++++++++++++++++++
 src/Events/FeedStartingEvent.php      | 20 ++++++++++++++++++
 src/Services/GeneratorService.php     | 21 +++++++++++++++----
 tests/Feature/Events/SuccessTest.php  | 30 +++++++++++++++++++++++++++
 tests/Unit/Architecture/EventTest.php |  7 +++++++
 7 files changed, 126 insertions(+), 4 deletions(-)
 create mode 100644 docs/topics/events.topic
 create mode 100644 src/Events/FeedFinishedEvent.php
 create mode 100644 src/Events/FeedStartingEvent.php
 create mode 100644 tests/Feature/Events/SuccessTest.php
 create mode 100644 tests/Unit/Architecture/EventTest.php

diff --git a/docs/laravel-feeds.tree b/docs/laravel-feeds.tree
index 5614054..1739284 100644
--- a/docs/laravel-feeds.tree
+++ b/docs/laravel-feeds.tree
@@ -20,6 +20,9 @@
         <toc-element topic="advanced-usage.topic" />
         <toc-element topic="supported-formats.topic" />
     </toc-element>
+    <toc-element toc-title="Digging Deeper">
+        <toc-element topic="events.topic" />
+    </toc-element>
     <toc-element toc-title="Receipts">
         <toc-element topic="receipt-sitemap.topic" />
         <toc-element topic="receipt-instagram.topic" />
diff --git a/docs/topics/events.topic b/docs/topics/events.topic
new file mode 100644
index 0000000..46411d3
--- /dev/null
+++ b/docs/topics/events.topic
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/xhtml-entities.dtd">
+<topic
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd"
+        title="Events" id="events">
+
+    <link-summary>Events dispatched during feed generation</link-summary>
+    <card-summary>Events dispatched during feed generation</card-summary>
+    <web-summary>Events dispatched during feed generation</web-summary>
+
+    <show-structure depth="3" />
+
+    <p>
+        Feeds dispatch two events when running the command:
+    </p>
+
+    <deflist>
+        <def title="DragonCode\LaravelFeed\Events\FeedStartingEvent">
+            The <code>FeedStartingEvent</code> is dispatched immediately before the draft file is created.
+        </def>
+        <def title="DragonCode\LaravelFeed\Events\FeedFinishedEvent">
+            The <code>FeedFinishedEvent</code> is dispatched right after the feed file generation has completed.
+        </def>
+    </deflist>
+</topic>
diff --git a/src/Events/FeedFinishedEvent.php b/src/Events/FeedFinishedEvent.php
new file mode 100644
index 0000000..6b81138
--- /dev/null
+++ b/src/Events/FeedFinishedEvent.php
@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DragonCode\LaravelFeed\Events;
+
+use DragonCode\LaravelFeed\Feeds\Feed;
+
+class FeedFinishedEvent
+{
+    /**
+     * Create a new event instance.
+     *
+     * @param  class-string<Feed>  $feed  Reference to the feed class
+     * @param  string  $path  Path to the generated feed file
+     * @return void
+     */
+    public function __construct(
+        public string $feed,
+        public string $path,
+    ) {}
+}
diff --git a/src/Events/FeedStartingEvent.php b/src/Events/FeedStartingEvent.php
new file mode 100644
index 0000000..ef33e02
--- /dev/null
+++ b/src/Events/FeedStartingEvent.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DragonCode\LaravelFeed\Events;
+
+use DragonCode\LaravelFeed\Feeds\Feed;
+
+class FeedStartingEvent
+{
+    /**
+     * Create a new event instance.
+     *
+     * @param  class-string<Feed>  $feed  Reference to the feed class
+     * @return void
+     */
+    public function __construct(
+        public string $feed,
+    ) {}
+}
diff --git a/src/Services/GeneratorService.php b/src/Services/GeneratorService.php
index aae996f..ea06574 100644
--- a/src/Services/GeneratorService.php
+++ b/src/Services/GeneratorService.php
@@ -5,6 +5,8 @@
 namespace DragonCode\LaravelFeed\Services;
 
 use DragonCode\LaravelFeed\Converters\Converter;
+use DragonCode\LaravelFeed\Events\FeedFinishedEvent;
+use DragonCode\LaravelFeed\Events\FeedStartingEvent;
 use DragonCode\LaravelFeed\Exceptions\FeedGenerationException;
 use DragonCode\LaravelFeed\Feeds\Feed;
 use DragonCode\LaravelFeed\Helpers\ConverterHelper;
@@ -15,6 +17,7 @@
 use Throwable;
 
 use function blank;
+use function event;
 use function get_class;
 use function implode;
 
@@ -28,10 +31,9 @@ public function __construct(
 
     public function feed(Feed $feed, ?OutputStyle $output = null): void
     {
-        $file = $this->openFile(
-            $path = $feed->path()
-        );
         try {
+            $this->started($feed);
+
             $file = $this->openFile(
                 $path = $feed->path()
             );
@@ -45,8 +47,9 @@ public function feed(Feed $feed, ?OutputStyle $output = null): void
 
             $this->release($file, $path);
 
-        $this->setLastActivity($feed);
             $this->setLastActivity($feed);
+
+            $this->finished($feed, $path);
         } catch (Throwable $e) {
             throw new FeedGenerationException(get_class($feed), $e);
         }
@@ -162,4 +165,14 @@ protected function progressBar(int $count, ?OutputStyle $output): ?ProgressBar
     {
         return $output?->createProgressBar($count);
     }
+
+    protected function started(Feed $feed): void
+    {
+        event(new FeedStartingEvent(get_class($feed)));
+    }
+
+    protected function finished(Feed $feed, string $path): void
+    {
+        event(new FeedFinishedEvent(get_class($feed), $path));
+    }
 }
diff --git a/tests/Feature/Events/SuccessTest.php b/tests/Feature/Events/SuccessTest.php
new file mode 100644
index 0000000..9abaac2
--- /dev/null
+++ b/tests/Feature/Events/SuccessTest.php
@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+use DragonCode\LaravelFeed\Commands\FeedGenerateCommand;
+use DragonCode\LaravelFeed\Events\FeedFinishedEvent;
+use DragonCode\LaravelFeed\Events\FeedStartingEvent;
+use DragonCode\LaravelFeed\Models\Feed;
+use Illuminate\Support\Facades\Event;
+
+use function Pest\Laravel\artisan;
+
+test('success', function () {
+    Event::fake();
+
+    artisan(FeedGenerateCommand::class)
+        ->assertSuccessful()
+        ->run();
+
+    getAllFeeds()->each(function (Feed $feed) {
+        Event::assertDispatched(FeedStartingEvent::class, static function (FeedStartingEvent $event) use ($feed) {
+            return $event->feed === $feed->class;
+        });
+
+        Event::assertDispatched(FeedFinishedEvent::class, static function (FeedFinishedEvent $event) use ($feed) {
+            return $event->feed === $feed->class
+                && $event->path === app($feed->class)->path();
+        });
+    });
+});
diff --git a/tests/Unit/Architecture/EventTest.php b/tests/Unit/Architecture/EventTest.php
new file mode 100644
index 0000000..69bd9a0
--- /dev/null
+++ b/tests/Unit/Architecture/EventTest.php
@@ -0,0 +1,7 @@
+<?php
+
+declare(strict_types=1);
+
+arch()
+    ->expect('DragonCode\LaravelFeed\Events')
+    ->toHaveSuffix('Event');