Getting Started

Minimal Setup

Installation

composer require kamoji/cms

Publish the package assets and configuration:

php artisan vendor:publish --provider="Kamoji\CMS\CMSServiceProvider" --tag="config"
php artisan vendor:publish --provider="Kamoji\CMS\CMSServiceProvider" --tag="migrations"
php artisan migrate

Service Provider & Routes Ensure the package is registered in config/app.php under providers:

Kamoji\CMS\CMSServiceProvider::class,

Add CMS routes in routes/web.php:

Route::middleware(['web', 'auth'])->group(function () {
    Route::prefix('admin')->group(function () {
        Route::resource('pages', 'Kamoji\CMS\Http\Controllers\PageController');
    });
});

First Use Case: Creating a Page
- Navigate to /admin/pages/create in your browser.
- Fill in the form fields (title, slug, content, etc.) and save.
- The page will be stored in the database and can be accessed via the frontend using the slug.

Implementation Patterns

Core Workflows

1. Page Management

CRUD Operations Use the Page model (Kamoji\CMS\Models\Page) to interact with pages programmatically:

use Kamoji\CMS\Models\Page;

// Create a page
$page = Page::create([
    'title' => 'About Us',
    'slug' => 'about',
    'content' => '<h1>Welcome to our page</h1>',
    'status' => 'published',
]);

// Retrieve a page by slug
$page = Page::where('slug', 'about')->first();

// Update a page
$page->update(['content' => '<h1>Updated content</h1>']);

// Delete a page
$page->delete();

Frontend Display Retrieve and display pages in your views:

// In a controller
public function showPage($slug) {
    $page = Page::where('slug', $slug)->firstOrFail();
    return view('pages.show', compact('page'));
}

// In a blade view
<div class="page-content">
    {!! $page->content !!}
</div>

2. Custom Fields & Extensions

Adding Custom Fields Extend the Page model to include custom fields. For example, add a meta_description field:

// In a migration
Schema::table('pages', function (Blueprint $table) {
    $table->text('meta_description')->nullable();
});

// Update the model
public function fillable() {
    return array_merge(parent::fillable(), ['meta_description']);
}

Event Listeners Listen to page events (e.g., page.created) to trigger custom logic:

// In EventServiceProvider
protected $listen = [
    'Kamoji\CMS\Events\PageCreated' => [
        'App\Listeners\LogPageCreation',
    ],
];

3. Middleware & Authorization

Restrict Access Use Laravel’s middleware to protect CMS routes:

Route::middleware(['web', 'auth', 'admin'])->group(function () {
    Route::resource('pages', 'Kamoji\CMS\Http\Controllers\PageController');
});

Create a custom middleware (app/Http/Middleware/AdminMiddleware.php):

public function handle($request, Closure $next) {
    if (!auth()->user()->isAdmin()) {
        abort(403);
    }
    return $next($request);
}

4. Theming & Templates

Override Default Views Publish and override the package’s views:
```
php artisan vendor:publish --provider="Kamoji\CMS\CMSServiceProvider" --tag="views"
```
Customize the views in resources/views/vendor/cms/.

Dynamic Templates Use blade templates to create reusable layouts for pages:

// In a controller
public function show($slug) {
    $page = Page::where('slug', $slug)->firstOrFail();
    return view('cms.templates.' . $page->template, compact('page'));
}

Gotchas and Tips

Pitfalls and Debugging

1. Route Conflicts

Issue: CMS routes may conflict with existing routes.
- Fix: Use route namespaces or prefixes to avoid conflicts. For example:
```
Route::prefix('admin')->namespace('Admin')->group(function () {
    Route::resource('pages', 'PageController');
});
```

2. Migration Issues

Issue: Running migrations after installation may fail if the database schema is already set up.
- Fix: Check the pages table structure before running migrations. If needed, rollback and re-run:
```
php artisan migrate:rollback
php artisan migrate
```

3. Content Security

Issue: Directly outputting page content ({!! $page->content !!}) can expose XSS vulnerabilities.
- Fix: Sanitize content before rendering:
```
use Purifier;

$cleanContent = Purifier::clean($page->content);
```
  Or use Laravel’s built-in e() helper for escaping:
```
{!! e($page->content) !!}
```

4. Performance with Large Content

Issue: Storing large HTML content in the database can bloat the database and slow queries.
- Fix: Use a dedicated storage system (e.g., AWS S3) for large assets and store only metadata in the database. Alternatively, compress content before storing.

5. Caching Strategies

Issue: Frequent page updates may lead to stale cached content.

Fix: Implement cache tags or versioning:

// Cache the page with a tag
Cache::tags(['page-' . $page->slug])->put('page-' . $page->slug, $page, now()->addHours(1));

// Clear cache on update
Cache::tags(['page-' . $page->slug])->flush();

Tips and Tricks

1. Useful Artisan Commands

Clear CMS Cache
```
php artisan cms:clear-cache
```
Generate a Sitemap If the package supports it, generate a sitemap for SEO:
```
php artisan cms:sitemap
```

2. Extending the Package

Custom Controllers Override the default controllers by binding them in the service provider:

public function boot() {
    $this->app->bind(
        'Kamoji\CMS\Http\Controllers\PageController',
        'App\Http\Controllers\Admin\PageController'
    );
}

Custom Models Extend the Page model to add custom logic:

class CustomPage extends \Kamoji\CMS\Models\Page {
    public function getFormattedContent() {
        return str_replace(['<p>', '</p>'], ['<div class="content-paragraph">', '</div>'], $this->content);
    }
}

Bind the custom model in the service provider:

$this->app->bind('Kamoji\CMS\Models\Page', 'App\Models\CustomPage');

3. Localization Support

Multilingual Pages Extend the Page model to support localization:
```
public function translations() {
    return $this->hasMany(\App\Models\PageTranslation::class);
}
```
Create a pivot table for translations and update the CMS to handle them.

4. Media Management

Integrate with Spatie Media Library Attach media to pages for richer content:

use Spatie\MediaLibrary\HasMedia;
use Spatie\MediaLibrary\InteractsWithMedia;

class Page extends \Kamoji\CMS\Models\Page implements HasMedia {
    use InteractsWithMedia;

    public function registerMediaCollections(): void {
        $this->addMediaCollection('images');
    }
}

5. Logging and Monitoring

Track Page Changes Use Laravel’s logging to monitor page updates:
```
// In a listener
Log::info('Page updated', ['page_id' => $page->id, 'changes' => $changes]);
```
Or use a package like spatie/laravel-logging for structured logging.

6. Testing

Unit Tests for Page Model Test the Page model and its interactions:

public function test_page_creation() {
    $page = Page::create(['title' => 'Test', 'slug' => 'test', 'content' => '<p>Test</p>']);
    $this->

Cms Laravel Package