feat: Add support for JavaScript callback options (didOpen, willClose, etc.) (#16)

* Initial plan

* Add support for JavaScript callback options (didOpen, willClose, etc.)

Co-authored-by: limonte <[email protected]>

* Improve callback implementation: address code duplication and add security documentation

Co-authored-by: limonte <[email protected]>

* Add JSON_THROW_ON_ERROR flag for better error handling

Co-authored-by: limonte <[email protected]>

* Fix test workflow to use local package code instead of published version

Co-authored-by: limonte <[email protected]>

* Fix JSON encoding to escape HTML characters for security

Co-authored-by: limonte <[email protected]>

* Use JSON_HEX_TAG flag to escape HTML tags for XSS protection

Co-authored-by: limonte <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: limonte <[email protected]>

Author: Copilot

.github/workflows/test.yml

@@ -19,7 +19,8 @@ jobs:
       - name: Install sweetalert2/laravel
         run: |
           cd sweetalert2-laravel-test
-          composer require sweetalert2/laravel
+          composer config repositories.local path ../
+          composer require sweetalert2/laravel:@dev
 
       - name: Copy Tests
         run: |

README.md

@@ -79,6 +79,29 @@ Swal::toastQuestion([
 ]);
 ```
 
+### Using JavaScript Callbacks
+
+You can use JavaScript callbacks (like `didOpen`, `willClose`, etc.) by passing them as strings:
+
+```php
+// Toast with pause on hover
+Swal::fire([
+    'title' => 'Auto close alert',
+    'toast' => true,
+    'position' => 'top-end',
+    'icon' => 'info',
+    'showConfirmButton' => false,
+    'timer' => 3000,
+    'timerProgressBar' => true,
+    'didOpen' => '(toast) => {
+        toast.onmouseenter = Swal.stopTimer;
+        toast.onmouseleave = Swal.resumeTimer;
+    }',
+]);
+```
+
+For more details on using callbacks, see [FAQ #4](#4-what-are-the-limitations).
+
 ![SweetAlert2 Laravel](sweetalert2-laravel.png)
 
 ## Livewire Components
@@ -162,6 +185,25 @@ $this->swalToastQuestion([
 ]);
 ```
 
+### Using JavaScript Callbacks in Livewire
+
+Just like in Laravel controllers, you can use JavaScript callbacks in Livewire components:
+
+```php
+$this->swalFire([
+    'title' => 'Processing...',
+    'toast' => true,
+    'position' => 'top-end',
+    'icon' => 'info',
+    'timer' => 3000,
+    'timerProgressBar' => true,
+    'didOpen' => '(toast) => {
+        toast.onmouseenter = Swal.stopTimer;
+        toast.onmouseleave = Swal.resumeTimer;
+    }',
+]);
+```
+
 ## Inertia.js
 
 You can use `Swal::fire()` or any of the available helper methods in your Inertia.js controllers to show popups after navigation:
@@ -330,5 +372,59 @@ This package uses a smart loading strategy for the SweetAlert2 library:
 
 ## 4. What are the limitations?
 
-SweetAlert2 is a JavaScript package and some of its options are JS callbacks. It's not possible to use them in the `Swal::fire()` or `$this->swalFire()` methods.
-If you need to use JS callbacks, you have to go to JS and use the SweetAlert2 API directly.
+SweetAlert2 is a JavaScript package and some of its options are JS callbacks. While you can pass JavaScript callback functions as strings in the `Swal::fire()` or `$this->swalFire()` methods, keep in mind:
+
+1. **Callbacks must be passed as strings**: Write your JavaScript function as a string. For example:
+
+```php
+Swal::fire([
+    'title' => 'Toast notification',
+    'toast' => true,
+    'position' => 'top-end',
+    'didOpen' => '(toast) => { toast.onmouseenter = Swal.stopTimer; toast.onmouseleave = Swal.resumeTimer; }',
+]);
+```
+
+2. **Supported callback options**: The following callback options are supported and will be rendered as JavaScript functions:
+   - `didOpen`
+   - `didClose`
+   - `didDestroy`
+   - `willOpen`
+   - `willClose`
+   - `didRender`
+   - `preDeny`
+   - `preConfirm`
+   - `inputValidator`
+   - `inputOptions`
+   - `loaderHtml`
+
+3. **Callback limitations**: 
+   - You cannot use PHP variables directly in callback strings (use JavaScript variables or values from the alert instead)
+   - Complex logic should be kept in JavaScript files and called from the callbacks
+   - For advanced use cases, consider using the SweetAlert2 API directly in JavaScript
+
+4. **Security considerations**:
+   - Callback strings are executed as JavaScript in the browser
+   - **Only pass callback strings from trusted sources (your PHP backend code)**
+   - **Never pass user input directly as callback strings** to prevent XSS vulnerabilities
+   - If you need to include dynamic data in callbacks, use regular options or HTML content instead
+
+### Example: Toast with Timer Control
+
+```php
+use SweetAlert2\Laravel\Swal;
+
+Swal::fire([
+    'title' => 'Your session will expire soon',
+    'toast' => true,
+    'position' => 'top-end',
+    'icon' => 'warning',
+    'showConfirmButton' => false,
+    'timer' => 3000,
+    'timerProgressBar' => true,
+    'didOpen' => '(toast) => {
+        toast.onmouseenter = Swal.stopTimer;
+        toast.onmouseleave = Swal.resumeTimer;
+    }',
+]);
+```

resources/views/inertia/index.blade.php

@@ -25,7 +25,24 @@
 
     if (sweetalert2Data && typeof sweetalert2Data === 'object') {
       Swal = Swal || await getSweetAlert2();
-      Swal.fire(sweetalert2Data);
+      
+      // Handle callbacks in Inertia
+      const options = {...sweetalert2Data};
+      const callbackOptions = @json(Swal::CALLBACK_OPTIONS);
+      
+      callbackOptions.forEach(callback => {
+        if (typeof options[callback] === 'string') {
+          try {
+            // Convert string to function (only for callbacks set by PHP backend, not user input)
+            options[callback] = new Function('return ' + options[callback])();
+          } catch (e) {
+            console.error(`Failed to parse ${callback} callback:`, e);
+            delete options[callback];
+          }
+        }
+      });
+      
+      Swal.fire(options);
     }
   });
 </script>

resources/views/laravel/index.blade.php

@@ -22,7 +22,7 @@
 
     (async () => {
       Swal = await getSweetAlert2();
-      Swal.fire(@json(session()->pull(Swal::SESSION_KEY)));
+      {!! Swal::renderFireCall(session()->pull(Swal::SESSION_KEY)) !!};
     })();
   </script>
 @endif

resources/views/livewire/index.blade.php

@@ -22,7 +22,7 @@
   @if(session()->has(Swal::SESSION_KEY))
     (async () => {
         Swal = await getSweetAlert2();
-        Swal.fire(@json(session()->pull(Swal::SESSION_KEY)));
+        {!! Swal::renderFireCall(session()->pull(Swal::SESSION_KEY)) !!};
     })();
   @endif
 
@@ -31,7 +31,24 @@
       return;
     }
     Swal = Swal || await getSweetAlert2();
-    Swal.fire(event.detail);
+    
+    // Handle callbacks in Livewire events
+    const options = {...event.detail};
+    const callbackOptions = @json(Swal::CALLBACK_OPTIONS);
+    
+    callbackOptions.forEach(callback => {
+      if (typeof options[callback] === 'string') {
+        try {
+          // Convert string to function (only for callbacks set by PHP backend, not user input)
+          options[callback] = new Function('return ' + options[callback])();
+        } catch (e) {
+          console.error(`Failed to parse ${callback} callback:`, e);
+          delete options[callback];
+        }
+      }
+    });
+    
+    Swal.fire(options);
   });
 </script>
 

src/Swal.php

@@ -18,6 +18,26 @@
 class Swal
 {
     public const SESSION_KEY = 'sweetalert2-message';
+    
+    /**
+     * List of SweetAlert2 options that accept callback functions.
+     * These will be rendered as JavaScript functions instead of JSON strings.
+     * 
+     * @var array
+     */
+    public const CALLBACK_OPTIONS = [
+        'didOpen',
+        'didClose',
+        'didDestroy',
+        'willOpen',
+        'willClose',
+        'didRender',
+        'preDeny',
+        'preConfirm',
+        'inputValidator',
+        'inputOptions',
+        'loaderHtml',
+    ];
     /**
      * Displays a SweetAlert2 popup.
      *
@@ -199,4 +219,67 @@ public static function toastQuestion(array $options = []): void
     {
         self::fire([...$options, 'toast' => true, 'icon' => 'question']);
     }
+
+    /**
+     * Separates callback options from regular options.
+     * Callbacks will be stored with a special marker to be rendered as JavaScript functions.
+     *
+     * @param array $options The full options array
+     * @return array Array with 'options' (regular JSON-serializable options) and 'callbacks' (JavaScript callback strings)
+     */
+    public static function separateCallbacks(array $options): array
+    {
+        $callbacks = [];
+        $regularOptions = [];
+
+        foreach ($options as $key => $value) {
+            if (in_array($key, self::CALLBACK_OPTIONS) && is_string($value)) {
+                $callbacks[$key] = $value;
+            } else {
+                $regularOptions[$key] = $value;
+            }
+        }
+
+        return [
+            'options' => $regularOptions,
+            'callbacks' => $callbacks,
+        ];
+    }
+
+    /**
+     * Renders the Swal.fire() JavaScript call with proper callback handling.
+     * 
+     * Security: Callback strings are rendered as JavaScript and executed in the browser.
+     * Only use callback strings from trusted sources (your backend code). Never pass 
+     * user input directly as callback strings to prevent XSS vulnerabilities.
+     *
+     * @param array $data The session data containing options
+     * @return string JavaScript code to call Swal.fire()
+     */
+    public static function renderFireCall(array $data): string
+    {
+        $separated = self::separateCallbacks($data);
+        $options = $separated['options'];
+        $callbacks = $separated['callbacks'];
+
+        if (empty($callbacks)) {
+            // No callbacks, just render as JSON
+            return 'Swal.fire(' . json_encode($options, JSON_HEX_TAG | JSON_THROW_ON_ERROR) . ')';
+        }
+
+        // Build JavaScript object with callbacks
+        $parts = [];
+        
+        // Add regular options
+        foreach ($options as $key => $value) {
+            $parts[] = json_encode($key, JSON_THROW_ON_ERROR) . ': ' . json_encode($value, JSON_HEX_TAG | JSON_THROW_ON_ERROR);
+        }
+
+        // Add callbacks as raw JavaScript
+        foreach ($callbacks as $key => $callback) {
+            $parts[] = json_encode($key, JSON_THROW_ON_ERROR) . ': ' . $callback;
+        }
+
+        return 'Swal.fire({' . implode(', ', $parts) . '})';
+    }
 }

tests/SwalTest.php

@@ -149,3 +149,37 @@
         ->assertStatus(200)
         ->assertSee('Swal.fire({"title":"toast question title","toast":true,"icon":"question"})', escape: false);
 });
+
+test('Swal::fire() with didOpen callback', function () {
+    Swal::fire([
+        'title' => 'Toast with callbacks',
+        'toast' => true,
+        'position' => 'top-end',
+        'didOpen' => '(toast) => { toast.onmouseenter = Swal.stopTimer; toast.onmouseleave = Swal.resumeTimer; }',
+    ]);
+
+    $response = $this->get('/');
+
+    $response
+        ->assertStatus(200)
+        ->assertSee('"title": "Toast with callbacks"', escape: false)
+        ->assertSee('"toast": true', escape: false)
+        ->assertSee('"position": "top-end"', escape: false)
+        ->assertSee('"didOpen": (toast) => { toast.onmouseenter = Swal.stopTimer; toast.onmouseleave = Swal.resumeTimer; }', escape: false);
+});
+
+test('Swal::fire() with multiple callbacks', function () {
+    Swal::fire([
+        'title' => 'Multiple callbacks',
+        'icon' => 'info',
+        'didOpen' => '() => { console.log("opened"); }',
+        'willClose' => '() => { console.log("closing"); }',
+    ]);
+
+    $response = $this->get('/');
+
+    $response
+        ->assertStatus(200)
+        ->assertSee('"didOpen": () => { console.log("opened"); }', escape: false)
+        ->assertSee('"willClose": () => { console.log("closing"); }', escape: false);
+});