Arkhe Main Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation

   composer require adhocrat-io/arkhe-main
   php artisan arkhe:install
   

   • Follow prompts to configure admin panel routes (/admin), user model, and Flux UI integration.

2. Publish Assets

   php artisan arkhe:assets
   

   • Publishes Flux UI CSS/JS and Arkhe-specific views.

3. Run Migrations

   php artisan migrate
   

   • Creates users, roles, and permissions tables (via Spatie Laravel-Permission).

4. Seed Default Admin

   php artisan arkhe:seed
   

   • Creates a super-admin user (credentials output in CLI).

5. First Use Case

   • Visit /admin to access the Flux UI-powered admin panel.
   • Use the Users and Roles sections to manage permissions via Livewire 4 components.

Where to Look First

• Admin Panel: /resources/views/vendor/arkhe/ – Customize Flux UI templates here.
• Livewire Components: /vendor/adhocrat-io/arkhe-main/src/Livewire/ – Extend or override default components.
• Configuration: /config/arkhe.php – Adjust routes, user model, and Flux UI settings.
• SEO/Sitemap: /routes/arkhe.php – Modify SEO rules or sitemap generation.

Implementation Patterns

Core Workflows

1. User & Role Management

   • Use the arkhe:users and arkhe:roles Livewire components for CRUD operations.
   • Example: Assign a role to a user via the UI or programmatically:

     use Adhocrat\Arkhe\Models\User;
     $user = User::find(1);
     $user->assignRole('editor');
     

2. Permission-Based Access Control

   • Gate routes or controllers using Spatie’s can() helper:

     if (auth()->user()->can('manage-users')) {
         return view('admin.users');
     }
     

   • Define custom permissions in migrations or via the Permissions section in the admin panel.

3. Flux UI Integration

   • Extend the sidebar by publishing and modifying:

     php artisan vendor:publish --tag=arkhe-sidebar
     

   • Override the default layout (if not using the Livewire/Volt starter):

     ARKHE_ADMIN_LAYOUT=arkhe::layouts.app
     

4. SEO & Sitemap

   • Generate dynamic sitemaps for admin routes:

     use Adhocrat\Arkhe\Facades\ArkheSitemap;
     ArkheSitemap::add('/admin/users');
     

   • Customize SEO metadata via the arkhe:seo facade or Flux UI’s built-in SEO tools.

5. Cookie Consent

   • Configure consent banners via /config/arkhe.php:

     'cookie_consent' => [
         'enabled' => true,
         'cookie_name' => 'arkhe_consent',
     ],
     

Integration Tips

• Custom User Model Extend the default Adhocrat\Arkhe\Models\User or bind your model in config/arkhe.php:

  'user_model' => App\Models\CustomUser::class,
  

• Livewire Component Overrides Publish and modify components:

  php artisan vendor:publish --tag=arkhe-livewire
  

  Example: Override the UsersTable component in /resources/livewire/arkhe/users-table.blade.php.

• Middleware for Admin Routes Use the provided middleware:

  Route::middleware(['auth', 'arkhe.admin'])->group(function () {
      // Admin routes
  });
  

• API Endpoints Leverage Spatie’s permission checks in API controllers:

  public function destroy(User $user)
  {
      $this->authorize('delete', $user);
      $user->delete();
  }
  

Gotchas and Tips

Pitfalls

1. Flux UI Starter Dependency

   • Without the Livewire/Volt starter, the package skips sidebar/CSS integration. Manually set ARKHE_ADMIN_LAYOUT to avoid missing assets.
   • Fix: Use the Flux UI starter or publish Arkhe’s default layout.

2. Permission Caching

   • Spatie’s permission cache may cause delays after bulk updates. Clear it manually:

     php artisan cache:clear
     php artisan arkhe:permissions:cache
     

3. Route Conflicts

   • Arkhe registers /admin routes by default. Customize in config/arkhe.php:

     'routes' => [
         'prefix' => 'backend',
     ],
     

4. Livewire Component Naming

   • Avoid naming custom Livewire components similarly to Arkhe’s (e.g., UsersTable). Use unique namespaces:

     namespace App\Livewire\Admin\Users;
     

5. SEO/Sitemap Duplicates

   • Ensure admin routes are excluded from public sitemaps. Use Spatie’s shouldBeIndexed() method:

     public function shouldBeIndexed(): bool
     {
         return false; // Exclude admin routes
     }
     

Debugging Tips

1. Livewire Errors

   • Check the livewire.log in /storage/logs/ for component-specific issues.
   • Use php artisan livewire:discover to refresh component autoloading.

2. Permission Denied

   • Verify roles/permissions in the database (roles, permissions, model_has_roles tables).
   • Test with php artisan arkhe:permissions:list to debug assignments.

3. Asset Loading Issues

   • Ensure ARKHE_ASSETS_PUBLISHED is true in .env after running arkhe:assets.
   • Clear views/cache:

     php artisan view:clear
     php artisan cache:clear
     

4. Flux UI Tailwind Conflicts

   • If Tailwind builds fail, check @source directives in /resources/css/app.css. Arkhe patches Tailwind v4 by default.

Extension Points

1. Custom Livewire Components

   • Extend Arkhe’s components by publishing them and adding logic:

     // app/Livewire/Arkhe/ExtendedUsersTable.php
     namespace App\Livewire\Arkhe;
     use Adhocrat\Arkhe\Livewire\UsersTable;
     class ExtendedUsersTable extends UsersTable
     {
         public function render()
         {
             return view('livewire.arkhe.extended-users-table')->layout('arkhe::layouts.app');
         }
     }
     

2. Event Listeners

   • Listen to Arkhe’s events (e.g., UserCreated, RoleDeleted) in EventServiceProvider:

     protected $listen = [
         \Adhocrat\Arkhe\Events\UserCreated::class => [
             \App\Listeners\LogUserCreation::class,
         ],
     ];
     

3. API Resource Extensions

   • Override Arkhe’s API resources (e.g., UserResource) by publishing and modifying:

     php artisan vendor:publish --tag=arkhe-api
     

4. Custom Views

   • Override any Arkhe view by publishing it first:

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

   • Example: Modify /resources/views/vendor/arkhe/users/create.blade.php.

5. Database Schema

   • Extend the users table by creating a migration and updating the model:

     // app/Models/User.php
     use Adhocrat\Arkhe\Models\User as ArkheUser;
     class User extends ArkheUser
     {
         protected $table = 'users';
         // Add custom fields
     }