Pageman Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation Run composer require tsrgtm/pageman in your Laravel project. Publish the config with php artisan vendor:publish --provider="Tsrgtm\Pageman\PagemanServiceProvider". Execute php artisan pageman:install and follow the CLI prompts (e.g., admin user credentials, database setup).

2. First Access Visit /pageman/admin in your browser. Log in with the credentials set during installation.

3. First Use Case: Create a Page

   • Navigate to Pages > Add New.
   • Define a slug (e.g., about-us), title (e.g., "About Us"), and content (HTML or markdown).
   • Assign a template (if provided) or use the default.
   • Publish the page. Access it via /[slug] (e.g., /about-us).

4. Where to Look First

   • Admin Panel: /pageman/admin for UI-based management.
   • Config File: config/pageman.php for customizing routes, middleware, or roles.
   • Migrations: database/migrations/ for schema changes (e.g., pageman_pages_table).
   • Service Provider: app/Providers/PagemanServiceProvider.php (if extending).

Implementation Patterns

Core Workflows

1. Page Management

• CRUD via Admin Panel: Use the built-in UI to create, edit, and delete pages. Pages are stored in the pageman_pages table. Example: Create a dynamic "Contact" page with a form.
• Programmatic Access: Retrieve pages in your controllers/views using:

  use Tsrgtm\Pageman\Facades\Pageman;
  $page = Pageman::getPage('about-us'); // Returns Page model or null
  

  Fetch all published pages:

  $pages = Pageman::getPublishedPages();
  

2. Role-Based Access Control (RBAC)

• Assign Roles: Use the Users > Roles section in the admin panel to create roles (e.g., editor, admin). Assign roles to users via the Users > Edit interface.
• Gate Checks: Protect routes or logic with Laravel’s gates:

  if (Gate::allows('edit-pageman-pages')) {
      // Allow page editing
  }
  

  Or use middleware:

  Route::middleware(['auth', 'can:edit-pageman-pages'])->group(function () {
      // Protected routes
  });
  

3. Templates and Layouts

• Default Templates: Pageman includes a Tailwind CSS-based admin panel. Override templates by publishing views:

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

  Customize files in resources/views/vendor/pageman/.
• Frontend Templates: Extend the page.blade.php template (located in resources/views/vendor/pageman/page.blade.php) to wrap page content:

  <div class="container">
      @yield('content')
      {{ $page->content }}
  </div>
  

4. Integration with Laravel Ecosystem

• Events: Listen to page events (e.g., PageCreated, PageUpdated) in EventServiceProvider:

  protected $listen = [
      'Tsrgtm\Pageman\Events\PageCreated' => [
          'App\Listeners\LogPageCreation',
      ],
  ];
  

• Service Container: Bind custom repositories or services:

  $this->app->bind('Tsrgtm\Pageman\Repositories\PageRepository', function () {
      return new App\Repositories\CustomPageRepository();
  });
  

5. API Endpoints

• Expose Pages via API: Use Laravel’s API resources to return pages as JSON:

  Route::get('/api/pages/{slug}', function ($slug) {
      return new PageResource(Pageman::getPage($slug));
  });
  

  Register the PageResource in app/Http/Resources.

Gotchas and Tips

Pitfalls

1. Database Conflicts:

   • Issue: Running pageman:install after migrations exist may cause errors.
   • Fix: Drop the pageman_* tables or manually merge schema changes.

2. Route Collisions:

   • Issue: Pageman’s default routes (e.g., /pageman/admin) may conflict with existing routes.
   • Fix: Customize routes in config/pageman.php:

     'admin' => [
         'prefix' => 'cms',
         'middleware' => ['web', 'auth'],
     ],
     

3. Tailwind CSS Dependencies:

   • Issue: The admin panel relies on Tailwind. Missing styles may break the UI.
   • Fix: Ensure Tailwind is installed (npm install tailwindcss) and configured in resources/css/app.css.

4. Permission Denied:

   • Issue: Users without roles may be locked out of the admin panel.
   • Fix: Assign the default admin role to at least one user during installation.

5. Caching Quirks:

   • Issue: Page content may not update immediately due to caching.
   • Fix: Clear the cache after publishing changes:

     php artisan cache:clear
     php artisan view:clear
     

Debugging Tips

1. Log Page Queries: Enable query logging in .env:

   DB_LOG_QUERIES=true
   

   Check storage/logs/laravel.log for SQL errors.

2. Admin Panel Debugging:

   • Use Laravel’s debugbar (barryvdh/laravel-debugbar) to inspect:
     • Authenticated user roles.
     • Middleware execution.
   • Temporarily disable middleware in config/pageman.php for testing:

     'middleware' => ['web'], // Remove 'auth' or 'can:...'
     

3. Template Overrides:

   • Debug: Add @debug directives in custom templates to inspect variables:

     @debug($page)
     

Extension Points

1. Custom Fields:

   • Extend the Page model to add fields (e.g., meta_title, featured_image):

     php artisan make:migration add_custom_fields_to_pageman_pages_table --table=pageman_pages
     

     Update the model:

     namespace App\Models;
     use Tsrgtm\Pageman\Models\Page as BasePage;
     
     class Page extends BasePage {
         protected $casts = [
             'featured_image' => 'string',
         ];
     }
     

2. Custom Templates:

   • Override the default page.blade.php to add dynamic layouts:

     <!-- resources/views/vendor/pageman/page.blade.php -->
     <article class="prose">
         <h1>{{ $page->title }}</h1>
         {!! $page->content !!}
         @if($page->featured_image)
             <img src="{{ asset('storage/' . $page->featured_image) }}" alt="{{ $page->title }}">
         @endif
     </article>
     

3. Custom Roles/Permissions:

   • Extend the Role model or use Laravel’s policy system:

     php artisan make:policy PagePolicy --model=Tsrgtm\Pageman\Models\Page
     

     Define permissions in app/Policies/PagePolicy.php:

     public function edit(User $user) {
         return $user->hasRole('editor');
     }
     

4. API Extensions:

   • Add custom API endpoints for pages:

     Route::prefix('api')->group(function () {
         Route::get('/pages/search', [PageController::class, 'search']);
     });
     

     Implement search logic in app/Http/Controllers/PageController.

5. Event Listeners:

   • React to page changes (e.g., send notifications):

     // app/Listeners/SendPageUpdateNotification.php
     public function handle(PageUpdated $event) {
         Notification::route('mail', $event->page->user->email)
                     ->notify(new PageUpdatedNotification($event->page));
     }