Merge pull request #25 from kirschbaum-development/feature/events

Paragon Broadcast Events

Author: brandonferens

README.md

@@ -6,20 +6,36 @@
 
 A tool for automatically generating typescript/javascript objects and utilities based on their PHP counterparts.
 
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Enums](#enums)
+  - [Custom Enum Methods](#custom-enum-methods)
+  - [Ignoring Enums or Methods](#ignoring-enums-or-public-methods)
+  - [Configuration](#configuration)
+  - [Recommendations](#recommendations)
+  - [Automatically Regenerate](#automatically-re-generating-when-modifying-php-enums)
+  - [Technical Details](#technical-details-)
+- [Events](#broadcast-events)
+  - [Usage](#usage)
+
+
 ## Requirements
 
 | Laravel Version | Paragon Version |
 |:----------------|:----------------|
-| 11.0            | 1.0.x           |
-| 10.0            | 1.0.x           |
+| 12.0            | ^1.0           |
+| 11.0            | ^1.0           |
+| 10.0            | ^1.0            |
 
 ## Installation
 
 ```bash
 composer require kirschbaum-development/paragon
 ```
 
-### Enums
+## Enums
 
 **TL;DR:** Run the following command to generate Typescript (or Javascript) enums from your PHP enums:
 
@@ -59,7 +75,7 @@ This package also supports generating Javascript enums. To do so, simply pass th
 php artisan paragon:enum:generate --javascript
 ```
 
-### Public Methods
+#### Public Methods
 
 A good majority of the time it is useful to use public methods to return a proper human-readable label or some other functionality on an enum. Paragon got this covered too. Assuming the following method exists on the above `Status` enum:
 
@@ -90,7 +106,7 @@ Status.Active.color() // 'bg-green-100'
 Status.Inactive.color() // 'bg-red-100'
 ```
 
-### Additional Enum Methods
+### Custom Enum Methods
 
 While this package ignores static methods on the PHP Enums, we allow you to create additional methods that Paragon will make available for every generated Enum.
 
@@ -127,12 +143,12 @@ use Kirschbaum\Paragon\Concerns\IgnoreParagon;
 
 enum Status
 {
-    ...
+    // ...
 
     #[IgnoreParagon]
     public method ignoreMe()
     {
-        ...
+        // ...
     }
 }
 ```
@@ -145,7 +161,7 @@ You can publish the configuration file by running `php artisan vendor:publish` a
 
 It is recommended that the generated path for the enums is added to the `.gitignore` file. Make sure to run this command during deployment if you do this.
 
-## Automatically Re-generating When Modifying PHP Enums
+### Automatically Re-generating When Modifying PHP Enums
 
 Install the [`vite-plugin-watch`](https://www.npmjs.com/package/vite-plugin-watch) plugin in your project via `npm`:
 
@@ -170,7 +186,7 @@ export default defineConfig({
 });
 ```
 
-## Technical Details 🤓
+### Technical Details 🤓
 
 Enums are a fantastic addition to the PHP-verse but are really lame in the TypeScript-verse. However, it can be annoying trying to get those enum values on the
 front-end of your project. Are you supposed to pass them as a method when returning a view or perhaps via an API? This
@@ -223,4 +239,60 @@ export default Status;
 
 At first glance it appears as though a lot more stuff is happening, but the above generated code allows us to interact
 with the enum in a nearly identical way as in PHP. And you may notice the generated TypeScript class extends the `Enum`
-class. This gives us some underlying functionality that is available to every enum.
+class. This gives us some underlying functionality that is available to every enum.
+
+## Broadcast Events
+
+**TL;DR:** Run the following command to generate a Typescript (or Javascript) broadcast event object based on your broadcastable events:
+
+```bash
+php artisan paragon:event:generate
+```
+
+Any events within the `App\Events` namespace will be automatically added to the `Events` object. Just make sure your event implements the `ShouldBroadcast` contract!
+
+If javascript is needed, just make sure to add the `--javascript` or `-j` flag.
+
+### Usage
+
+The primary usage of this tool is for Laravel Echo. Listening to for an event class based on a hard-coded string is not exactly preferable. The can easily get out of sync or just get mistyped.
+
+Here is a quick example event:
+
+```php
+namespace App\Events;
+
+class ParagonGenerated implements ShouldBroadcast
+{ 
+    // ...
+}
+```
+
+Then listen for it with Echo:
+
+```js
+import Events from '@/events/Events.ts';
+
+Echo.channel(...)
+    .listen(Events.ParagonGenerated, /* ... */);
+```
+
+If you have defined a `broadcastOn` method that returns a custom name, this will be handled correctly for you as well.
+
+One thing to note is that if an event namespace starts with `App\Events` or `App`, these will be removed from the dot path within the object. If an event is nested, the dot path will reflect this: For example:
+
+```php
+namespace App\Support;
+
+class NestedEvent implements ShouldBroadcast
+{ 
+    // ...
+}
+```
+
+```js
+import Events from '@/events/Events.ts';
+
+Echo.channel(...)
+    .listen(Events.Support.NestedEvent, /* ... */);
+```

config/paragon.php

@@ -33,10 +33,17 @@
         'abstract-class' => 'Enum',
 
         'paths' => [
-            'php' => '',
+            'php' => 'Enums',
             'ignore' => [],
             'generated' => 'js/enums',
             'methods' => 'js/vendors/paragon/enums',
         ],
     ],
+
+    'events' => [
+        'paths' => [
+            'php' => 'Events',
+            'generated' => 'js/events',
+        ],
+    ],
 ];

src/Commands/GenerateBroadcastEventsCommand.php

@@ -0,0 +1,61 @@
+<?php
+
+namespace Kirschbaum\Paragon\Commands;
+
+use Exception;
+use Illuminate\Console\Command;
+use Illuminate\Support\Arr;
+use Kirschbaum\Paragon\Concerns\DiscoverBroadcastEvents;
+use Kirschbaum\Paragon\Generators\EventGenerator;
+use Symfony\Component\Console\Attribute\AsCommand;
+use Symfony\Component\Console\Input\InputOption;
+
+#[AsCommand(name: 'paragon:event:generate', description: 'Generate Typescript/Javascript definitions for Laravel Broadcast Events')]
+class GenerateBroadcastEventsCommand extends Command
+{
+    /**
+     * Execute the console command.
+     */
+    public function handle(): int
+    {
+        try {
+            $config = Arr::wrap(config('paragon.events.paths.php'));
+
+            /**
+             * @var list<string> $paths
+             */
+            $paths = collect($config)
+                ->map(fn (string $path): string => app_path($path))
+                ->toArray();
+
+            $events = DiscoverBroadcastEvents::within($paths);
+
+            app(EventGenerator::class, ['events' => $events, 'generateJavascript' => $this->option('javascript')])();
+        } catch (Exception $e) {
+            $this->components->error($e->getMessage());
+
+            return self::FAILURE;
+        }
+
+        $this->components->info("{$events->count()} events have been (re)generated.");
+
+        return self::SUCCESS;
+    }
+
+    /**
+     * Get the console command options.
+     *
+     * @return array<int, InputOption>
+     */
+    protected function getOptions(): array
+    {
+        return [
+            new InputOption(
+                name: 'javascript',
+                shortcut: 'j',
+                mode: InputOption::VALUE_NONE,
+                description: 'Output Javascript files',
+            ),
+        ];
+    }
+}

src/Commands/GenerateEnumsCommand.php

@@ -18,7 +18,7 @@
 use Symfony\Component\Console\Attribute\AsCommand;
 use Symfony\Component\Console\Input\InputOption;
 
-#[AsCommand(name: 'paragon:enum:generate', description: 'Generate Typescript versions of existing PHP enums')]
+#[AsCommand(name: 'paragon:enum:generate', description: 'Generate TypeScript/Javascript versions of existing PHP enums')]
 class GenerateEnumsCommand extends Command
 {
     /**

src/Concerns/DiscoverBroadcastEvents.php

@@ -0,0 +1,112 @@
+<?php
+
+namespace Kirschbaum\Paragon\Concerns;
+
+use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
+use Illuminate\Support\Collection;
+use ReflectionClass;
+use Symfony\Component\Finder\Finder;
+use Symfony\Component\Finder\SplFileInfo;
+
+class DiscoverBroadcastEvents
+{
+    /**
+     * Get all the events by searching the given directory.
+     *
+     * @param  string|list<string>  $paths
+     *
+     * @return Collection<string, class-string>
+     */
+    public static function within(array|string $paths): Collection
+    {
+        return static::getBroadcastEvents(Finder::create()->files()->in($paths));
+    }
+
+    /**
+     * Filter the files down to only concrete classes that implement ShouldBroadcast.
+     *
+     * @param  Finder<string, SplFileInfo>  $files
+     *
+     * @return Collection<string, class-string>
+     */
+    protected static function getBroadcastEvents(Finder $files): Collection
+    {
+        /**
+         * @var Collection<int, SplFileInfo> $fileCollection
+         */
+        $fileCollection = collect($files);
+
+        return $fileCollection
+            ->mapWithKeys(function (SplFileInfo $file) {
+                $event = static::classFromFile($file);
+
+                if (! $event) {
+                    return [];
+                }
+
+                $reflector = new ReflectionClass($event);
+
+                if (
+                    $reflector->isInstantiable()
+                    && $reflector->implementsInterface(ShouldBroadcast::class)
+                ) {
+                    $key = (string) str($event)
+                        ->remove(['App\\Events\\', 'App\\'])
+                        ->replace('\\', '.');
+
+                    return [$key => $event];
+                }
+
+                return [];
+            })
+            ->filter()
+            ->sort();
+    }
+
+    /**
+     * Extract the class name from the given file path.
+     *
+     * @return class-string|false
+     */
+    protected static function classFromFile(SplFileInfo $file): string|false
+    {
+        $handle = fopen($file->getRealPath(), 'r');
+
+        if (! $handle) {
+            return false;
+        }
+
+        $namespace = null;
+        $class = null;
+
+        while (($line = fgets($handle)) !== false) {
+            if (preg_match('/^namespace\s+([^;]+);/', $line, $matches)) {
+                $namespace = $matches[1];
+            }
+
+            if (preg_match('/^class\s+(\w+)(?:\s*:\s*\w+)?/', $line, $matches)) {
+                $class = $matches[1];
+            }
+
+            if (
+                ($namespace && $class)
+                || preg_match('/\b(enum|trait|interface)\b/', $line)
+            ) {
+                break;
+            }
+        }
+
+        fclose($handle);
+
+        if ($namespace && $class) {
+            /**
+             * @var class-string $className
+             */
+            $className = "{$namespace}\\{$class}";
+
+            return $className;
+        }
+
+        return false;
+    }
+}

src/Generators/EnumGenerator.php

@@ -33,7 +33,7 @@ class EnumGenerator
     protected ReflectionEnum $reflector;
 
     /**
-     * Create new EnumGenerator instance.
+     * Create a new EnumGenerator instance.
      */
     public function __construct(
         protected ReflectionEnum $enum,
@@ -99,7 +99,7 @@ protected function contents(): string
     }
 
     /**
-     * Build out the actual enum case object including the name, value if needed, and any public methods.
+     * Build out the actual enum case object, including the name, value if needed, and any public methods.
      *
      * @return Collection<string, string>
      */