Ajaxis Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require amranidev/ajaxis
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Ajaxis\AjaxisServiceProvider"
   

2. Basic Configuration Edit config/ajaxis.php to define your CRUD routes and views:

   'crud' => [
       'users' => [
           'model' => 'App\Models\User',
           'view'  => 'users.index',
           'routes' => [
               'index' => 'users',
               'store' => 'users.store',
               'update' => 'users.update',
               'destroy' => 'users.destroy',
           ],
       ],
   ],
   

3. First Use Case: Quick CRUD AJAX Endpoint Define a controller method to handle AJAX requests:

   use Ajaxis\Ajaxis;
   
   public function index(Ajaxis $ajaxis)
   {
       return $ajaxis->get('users')->table();
   }
   

   Add the route in routes/web.php:

   Route::get('/users', 'UserController@index');
   

4. Frontend Integration Include the package’s JS/CSS in your blade view:

   @include('ajaxis::scripts')
   

   Use the provided table helper:

   <table class="ajaxis-table" data-url="{{ route('users.index') }}">
       <thead>
           <tr><th>ID</th><th>Name</th><th>Actions</th></tr>
       </thead>
   </table>
   

Implementation Patterns

Common Workflows

1. Dynamic Table Rendering Use Ajaxis to fetch and render data dynamically:

   public function index(Ajaxis $ajaxis)
   {
       return $ajaxis->get('users')
           ->select(['id', 'name', 'email'])
           ->table(['id', 'name', 'email'], ['edit', 'delete']);
   }
   

   • Columns: Define columns to display.
   • Actions: Pass an array of action buttons (e.g., ['edit', 'delete']).

2. Form Handling (Create/Update) For AJAX forms, use the form() method:

   public function create(Ajaxis $ajaxis)
   {
       return $ajaxis->form('users.store', [
           'name' => 'text',
           'email' => 'email',
       ]);
   }
   

   • Validation: Automatically validates using Laravel’s validation rules.
   • Redirects: Returns JSON response for AJAX success/error handling.

3. Custom Views Override default views by publishing assets:

   php artisan vendor:publish --tag=ajaxis-views
   

   Place custom views in resources/views/vendor/ajaxis/.

4. Middleware Integration Protect routes with middleware (e.g., auth):

   Route::middleware('auth')->group(function () {
       Route::get('/users', 'UserController@index');
   });
   

5. Pagination Enable pagination in the get() method:

   return $ajaxis->get('users')->paginate(10)->table();
   

Integration Tips

• Laravel Mix/Webpack: Bundle the package’s JS/CSS with your assets for optimization.
• API Routes: Use the package for API endpoints by returning JSON directly:

  return $ajaxis->get('users')->json();
  

• Event Listeners: Extend functionality by listening to ajaxis.* events (e.g., ajaxis.beforeRender).
• Localization: Override language strings in resources/lang/vendor/ajaxis.

Gotchas and Tips

Pitfalls

1. Outdated Package

   • Last release was in 2016; test thoroughly for Laravel 8/9 compatibility.
   • Potential issues with:
     • Eloquent query builder changes.
     • Blade directive syntax (e.g., @ajaxis).
     • CSRF token handling in AJAX requests.

2. CSRF Token Mismatch Ensure AJAX requests include the CSRF token:

   $.ajaxSetup({
       headers: {
           'X-CSRF-TOKEN': $('meta[name="csrf-token"]').attr('content')
       }
   });
   

3. Route Caching Conflicts Clear route cache if routes aren’t recognized:

   php artisan route:clear
   

4. View Override Pitfalls

   • Custom views must extend the base template (resources/views/vendor/ajaxis/table.blade.php).
   • Missing @include('ajaxis::scripts') breaks AJAX functionality.

5. Model Binding Issues Ensure your model uses Laravel’s standard conventions (e.g., App\Models\User). Custom primary keys may require explicit configuration:

   $ajaxis->get('users')->primaryKey('user_id');
   

Debugging Tips

1. Check Network Requests Use browser dev tools to verify AJAX payloads/responses. Common issues:

   • 419 errors (CSRF token missing).
   • 500 errors (validation failures; check Laravel logs).

2. Log Ajaxis Events Add debug logs in app/Providers/AjaxisServiceProvider.php:

   Ajaxis::macro('debug', function () {
       \Log::debug('Ajaxis request:', $this->request->all());
   });
   

3. Validate JSON Responses Ensure the package returns valid JSON for AJAX:

   return response()->json(['success' => false, 'errors' => $validator->errors()]);
   

Extension Points

1. Custom Directives Extend Blade directives (e.g., @ajaxisForm):

   Blade::directive('ajaxisForm', function ($expression) {
       return "<?php echo Ajaxis::form($expression); ?>";
   });
   

2. Hooks for Pre/Post Processing Use Laravel’s ModelObserver or Ajaxis macros:

   Ajaxis::macro('customAction', function ($action) {
       return $this->extend(function ($response) use ($action) {
           $response['custom'] = "Processed via {$action}";
           return $response;
       });
   });
   

3. Database Observers Trigger actions on model events (e.g., saved):

   class UserObserver {
       public function saved(User $user) {
           event(new UserSaved($user));
       }
   }
   

4. API Integration Combine with Laravel Sanctum/Passport for authenticated AJAX:

   $.ajax({
       headers: {
           'Authorization': 'Bearer ' + token,
           'X-CSRF-TOKEN': token
       }
   });
   

Performance Quirks

• Eager Loading: Manually eager-load relationships to avoid N+1 queries:

  $ajaxis->get('users')->with('roles')->table();
  

• Caching: Cache frequent queries (e.g., dashboard data):

  return Cache::remember('users.list', now()->addHours(1), function () {
      return $ajaxis->get('users')->table();
  });