From ca6e75ba9df0c05081853de014cacbe0b1dc3919 Mon Sep 17 00:00:00 2001 From: Younes ENNAJI Date: Wed, 26 Mar 2025 04:06:45 +0000 Subject: [PATCH 1/2] update laravel documentation page --- docs/_layouts/home.html | 4 +- docs/_layouts/inertia.html | 16 +- docs/_layouts/livewire.html | 20 +- docs/{_layouts => pages}/laravel.html | 311 +++++++++++++++++++------- docs/pages/laravel.md | 8 - docs/pages/symfony.html | 21 +- 6 files changed, 270 insertions(+), 110 deletions(-) rename docs/{_layouts => pages}/laravel.html (85%) delete mode 100644 docs/pages/laravel.md diff --git a/docs/_layouts/home.html b/docs/_layouts/home.html index 8b365f72..c661201a 100644 --- a/docs/_layouts/home.html +++ b/docs/_layouts/home.html @@ -482,7 +482,9 @@
Controller.php
- 
namespace App\Http\Controllers;
+                            
<?php
+
+namespace App\Http\Controllers;
 
 class ProfileController
 {
diff --git a/docs/_layouts/inertia.html b/docs/_layouts/inertia.html
index 712ecf64..bb36ca6b 100644
--- a/docs/_layouts/inertia.html
+++ b/docs/_layouts/inertia.html
@@ -253,7 +253,7 @@ layout: default
                         
app/Http/Middleware/HandleInertiaRequests.php
-
<?php
 
 namespace App\Http\Middleware;
 
@@ -402,7 +402,7 @@ export default {
                         
app/Http/Controllers/UsersController.php
-
<?php
 
 namespace App\Http\Controllers;
 
@@ -604,7 +604,7 @@ class UsersController extends Controller
                         
app/Http/Controllers/ProductController.php
-
<?php
 
 namespace App\Http\Controllers;
 
@@ -739,7 +739,7 @@ class ProductController extends Controller
                         
app/Http/Controllers/Auth/AuthController.php
-
<?php
 
 namespace App\Http\Controllers\Auth;
 
@@ -848,7 +848,7 @@ class AuthController extends Controller
                         
app/Http/Controllers/FormController.php
-
<?php
 
 namespace App\Http\Controllers;
 
@@ -1503,7 +1503,7 @@ export default function Dashboard() {
                         
CustomOptions.php
-
<?php
 
 namespace App\Http\Controllers;
 
@@ -1578,7 +1578,7 @@ class NotificationController extends Controller
                         
app/Http/Controllers/PostController.php
-
<?php
 
 namespace App\Http\Controllers;
 
@@ -1691,7 +1691,7 @@ onMounted(() => {
                         
config/flasher.php
-
<?php
 
 return [
     // Default notification handler (theme)
diff --git a/docs/_layouts/livewire.html b/docs/_layouts/livewire.html
index b2970e08..b0ebf3b9 100644
--- a/docs/_layouts/livewire.html
+++ b/docs/_layouts/livewire.html
@@ -220,7 +220,9 @@ layout: default
                         
UserComponent.php
-
namespace App\Livewire;
+
<?php
+
+namespace App\Livewire;
 
 use Livewire\Component;
 
@@ -272,7 +274,9 @@ class UserComponent extends Component
                         
ContactForm.php
-
namespace App\Livewire;
+
<?php
+
+namespace App\Livewire;
 
 use Livewire\Component;
 use App\Models\Contact;
@@ -455,7 +459,9 @@ class ContactForm extends Component
                         
UserDeleteComponent.php
-
namespace App\Livewire;
+
<?php
+
+namespace App\Livewire;
 
 use Livewire\Attributes\On;
 use Livewire\Component;
@@ -553,7 +559,9 @@ class UserComponent extends Component
                         
TasksComponent.php
-
namespace App\Livewire;
+
<?php
+
+namespace App\Livewire;
 
 use App\Models\Task;
 use Livewire\Attributes\On;
@@ -713,7 +721,9 @@ Livewire.hook('commit', ({ component }) => {
                         
PublishArticle.php
-
namespace App\Livewire;
+
<?php
+
+namespace App\Livewire;
 
 use Livewire\Attributes\On;
 use Livewire\Component;
diff --git a/docs/_layouts/laravel.html b/docs/pages/laravel.html
similarity index 85%
rename from docs/_layouts/laravel.html
rename to docs/pages/laravel.html
index 0f74bba4..50709a3f 100644
--- a/docs/_layouts/laravel.html
+++ b/docs/pages/laravel.html
@@ -1,5 +1,9 @@
 ---
-layout: default
+permalink: /laravel/
+title: Laravel
+handler: flasher
+description: Add flash notifications to your Laravel application with PHPFlasher. Follow our step-by-step guide to install and use the library, and start informing your users with powerful flash messages.
+framework: laravel
 ---
 
 

@@ -210,7 +214,7 @@ layout: default
                         

                             
Best Practice

                             

-                                PHPFlasher works seamlessly with Laravel's service container and will be automatically discovered. No additional configuration is needed.
+                                Commit the installed assets to your version control system to ensure everyone on your team has the same notification experience.
                             

                         

                     

@@ -243,7 +247,9 @@ layout: default
                         
ProductController.php
-
namespace App\Http\Controllers;
+
<?php
+
+namespace App\Http\Controllers;
 
 use App\Models\Product;
 use Illuminate\Http\Request;
@@ -277,10 +283,10 @@ class ProductController extends Controller
-

Pro Tip: Two Ways to Use PHPFlasher

+

Pro Tip: Three Ways to Use PHPFlasher

PHPFlasher - provides two ways to create notifications: + provides three ways to create notifications:

  • @@ -291,6 +297,10 @@ class ProductController extends Controller Facade: use Flasher\Laravel\Facade\Flasher; Flasher::success('Message');
    • +
  • + + Dependency injection: public function __construct(private FlasherInterface $flasher) {} +
@@ -488,7 +498,9 @@ flash()->info('The system will be down for maintenance tonight.');
PostController.php
-
namespace App\Http\Controllers;
+
<?php
+
+namespace App\Http\Controllers;
 
 use App\Models\Post;
 use Illuminate\Http\Request;
@@ -564,7 +576,9 @@ class PostController extends Controller
                         
RegisterController.php
-
namespace App\Http\Controllers\Auth;
+
<?php
+
+namespace App\Http\Controllers\Auth;
 
 use App\Http\Controllers\Controller;
 use App\Models\User;
@@ -604,21 +618,22 @@ class RegisterController extends Controller
 
                 
                 
AJAX Support

-                
PHPFlasher works seamlessly with AJAX requests. It automatically displays notifications from JSON responses:

+                
PHPFlasher can be used with AJAX requests, but requires explicit handling in your JavaScript code:

 
-                

-                    
-                    

-                        

-                            

-                                

-                                

-                                

-                            

-                            
ApiController.php

+                
+                

+                    

+                        

+                            

+                            

+                            

                         

-                        

-
namespace App\Http\Controllers\Api;
+                        
ApiController.php

+                    

+                    

+                
<?php
+
+namespace App\Http\Controllers\Api;
 
 use App\Http\Controllers\Controller;
 use Illuminate\Http\Request;
@@ -632,45 +647,42 @@ class ApiController extends Controller
             $success = true; // Assuming operation succeeded
 
             if ($success) {
-                flash()->success('Data saved successfully!');
-
                 return response()->json([
                     'status' => 'success',
                     'message' => 'Data saved successfully!'
                 ]);
             } else {
-                flash()->error('Failed to save data');
-
                 return response()->json([
                     'status' => 'error',
                     'message' => 'Failed to save data'
                 ], 400);
             }
         } catch (\Exception $e) {
-            flash()->error('An error occurred: ' . $e->getMessage());
-
             return response()->json([
                 'status' => 'error',
-                'message' => 'An error occurred'
+                'message' => 'An error occurred: ' . $e->getMessage()
             ], 500);
         }
     }
 }

-                        

                     

+                

 
-                    
-                    

-                        

-                            

-                                

-                                

-                                

-                            

-                            
script.js

+                
+                

+                    

+                        

+                            

+                            

+                            

                         

-                        

-
document.getElementById('saveForm').addEventListener('submit', function(e) {
+                        
script.js

+                    

+                    

+                
// Import flasher in your JS file
+import flasher from '@flasher/flasher';
+
+document.getElementById('saveForm').addEventListener('submit', function(e) {
     e.preventDefault();
 
     const formData = new FormData(this);
@@ -685,28 +697,119 @@ class ApiController extends Controller
     .then(response => response.json())
     .then(data => {
         console.log('Success:', data);
-        // PHPFlasher will automatically display the notification
-        // No additional JS code needed!
+        // Explicitly call flasher methods based on the response
+        if (data.status === 'success') {
+            flasher.success(data.message);
+        } else {
+            flasher.error(data.message);
+        }
     })
     .catch(error => {
         console.error('Error:', error);
+        flasher.error('An unexpected error occurred');
     });
 });

+                    

+                

+
+                
+                
Alternative: Dedicated Flash Message API

+                
You can also create a dedicated endpoint that returns flash messages as part of your API response:

+
+                
+                

+                    

+                        

+                            

+                            

+                            

                         

+                        
FlashController.php

+                    

+                    

+                
<?php
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+
+class FlashController extends Controller
+{
+    public function getFlashMessages()
+    {
+        // Get all flash messages as an array
+        $messages = flash()->render([], 'array');
+
+        return response()->json($messages);
+    }
+}

+                    

+                

+
+                
+                

+                    

+                        

+                            

+                            

+                            

+                        

+                        
fetch-flash.js

+                    

+                    

+                
import flasher from '@flasher/flasher';
+
+// Function to fetch and display flash messages
+function fetchFlashMessages() {
+    fetch('/api/flash', {
+        headers: {
+            'X-Requested-With': 'XMLHttpRequest'
+        }
+    })
+    .then(response => response.json())
+    .then(messages => {
+        // Render the flash messages using PHPFlasher
+        flasher.render(messages);
+    })
+    .catch(error => {
+        console.error('Error fetching flash messages:', error);
+    });
+}
+
+// Call this after operations that might set flash messages on the server
+// or periodically if needed
+fetchFlashMessages();

                     

                 

 
                 
-                

-                    

-                        

-                            
+                

+                    

+                        

+                            
+                                
+                            
                         

-                        

-                            
Expert Tip: AJAX Integration

-                            

-                                PHPFlasher automatically handles AJAX responses — notifications from the server appear without any additional code. This works with fetch, axios, jQuery, and other AJAX methods.
+                        

+                            
Expert Tip: AJAX Integration

+                            

+                                PHPFlasher requires explicit JavaScript calls to display notifications in AJAX scenarios. You have several options:
                             

+                            
    
+                                
  • 
+                                    1
+                                    Call flasher methods directly in your JavaScript after receiving a response
+                                
    • 
+                                
  • 
+                                    2
+                                    Use the render() method with a dedicated endpoint that returns flash messages
+                                
    • 
+                                
  • 
+                                    3
+                                    Integrate with frameworks like InertiaJS to automatically include flash messages in each response
+                                
    • 
+                            

                         

                     

                 

@@ -725,7 +828,9 @@ class ApiController extends Controller
                         
AdminAccessMiddleware.php

                     

                     

-
namespace App\Http\Middleware;
+
<?php
+
+namespace App\Http\Middleware;
 
 use Closure;
 use Illuminate\Http\Request;
@@ -736,6 +841,7 @@ class AdminAccessMiddleware
     {
         if (!$request->user() || !$request->user()->isAdmin()) {
             flash()->error('You do not have access to this area.', 'Access Denied');
+
             return redirect()->route('home');
         }
 
@@ -791,9 +897,22 @@ class AdminAccessMiddleware
                         
config/flasher.php

                     

                     

-
<?php
 
-return [
+declare(strict_types=1);
+
+use Flasher\Prime\Configuration;
+
+/*
+ * Default PHPFlasher configuration for Laravel.
+ *
+ * This configuration file defines the default settings for PHPFlasher when
+ * used within a Laravel application. It uses the Configuration class from
+ * the core PHPFlasher library to establish type-safe configuration.
+ *
+ * @return array PHPFlasher configuration
+ */
+return Configuration::from([
     // Default notification library (e.g., 'flasher', 'toastr', 'noty', 'notyf', 'sweetalert')
     'default' => 'flasher',
 
@@ -817,6 +936,9 @@ return [
     // Enable message translation using Laravel's translation service
     'translate' => true,
 
+    // URL patterns to exclude from asset injection and flash_bag conversion
+    'excluded_paths' => [],
+
     // Map Laravel flash message keys to notification types
     'flash_bag' => [
         'success' => ['success'],
@@ -838,18 +960,18 @@ return [
     //         'message' => 'Entity saved successfully',
     //     ],
     // ],
-];

+]);

Common Configuration Examples

-
+
-
+

Change Default Position

-
<?php // config/flasher.php
 
 return [
     'options' => [
@@ -861,7 +983,7 @@ return [
                     
                     

                         
Change Default Timeout

-
<?php // config/flasher.php
 
 return [
     'options' => [
@@ -970,7 +1092,7 @@ $request->session()->flash('error', 'Something went wrong!');
                         
config/flasher.php

                     

                     

-
<?php // config/flasher.php
 
 return [
     'presets' => [
@@ -1020,7 +1142,9 @@ return [
                         
BookController.php

                     

                     

-
namespace App\Http\Controllers;
+
<?php
+
+namespace App\Http\Controllers;
 
 use App\Models\Book;
 use Illuminate\Http\Request;
@@ -1067,7 +1191,9 @@ class PaymentController extends Controller
                         
EquivalentCode.php

                     

                     

-
namespace App\Http\Controllers;
+
<?php
+
+namespace App\Http\Controllers;
 
 class BookController extends Controller
 {
@@ -1083,33 +1209,52 @@ class BookController extends Controller
                 

 
                 
-                

-                    
Common Preset Use Cases

-                    
    
+                
    
+                    
    
+                        Common Preset Use Cases
+                    
    
+
+                    
      
                         
    • 
-                            
      
-                                
+                            
      
+                                
+                                    
+                                
+                            
      
+                            
      
+                                
      CRUD Operations
      
+                                
      
+                                    Create consistent notifications for create, update, and delete operations
+                                
      
                             
      
-                            
      
-                                CRUD Operations:
-                                Create consistent notifications for create, update, delete operations
-                            
      
                         
      • 
+
                         
    • 
-                            
      
-                                
+                            
      
+                                
+                                    
+                                
+                            
      
+                            
      
+                                
      User Feedback
      
+                                
      
+                                    Standardize welcome messages, payment confirmations, and other user communications
+                                
      
                             
      
-                            
      
-                                User Feedback: Standardize welcome messages, payment confirmations, etc.
-                            
      
                         
      • 
+
                         
    • 
-                            
      
-                                
+                            
      
+                                
+                                    
+                                
+                            
      
+                            
      
+                                
      Error Handling
      
+                                
      
+                                    Create consistent error notifications with custom styling and actionable messages
+                                
      
                             
      
-                            
      
-                                Error Handling: Create consistent error notifications with custom styling
-                                                        
      
                         
      • 
                     
    
                 
    
@@ -1143,7 +1288,7 @@ class BookController extends Controller
                         
    config/flasher.php
    
                     

                     

-
<?php // config/flasher.php
 
 return [
     'presets' => [
@@ -1240,7 +1385,7 @@ flash()->translate('ar')->success('The resource was created');