Cms Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require apie/cms apie/cms-layout-graphite
   

   • Requires apie/html-builders and a layout package (e.g., apie/cms-layout-graphite).

2. Publish Config

   php artisan vendor:publish --provider="Apie\Cms\CmsServiceProvider"
   

   • Configures CMS routes, middleware, and default settings.

3. First Use Case: Basic Page Controller

   use Apie\Cms\CmsController;
   
   class MyPageController extends CmsController
   {
       public function index()
       {
           return $this->render('my-page', [
               'title' => 'Welcome',
               'content' => 'Hello, CMS!',
           ]);
       }
   }
   

   • Register the route in routes/web.php:

     Route::get('/my-page', [MyPageController::class, 'index']);
     

4. View Structure

   • Create a Blade template at resources/views/my-page.blade.php.
   • Use the layout system (e.g., Graphite) for consistent styling.

Implementation Patterns

Core Workflows

1. Component-Based Rendering

   • Leverage Apie\HtmlBuilders to create reusable components:

     use Apie\HtmlBuilders\HtmlBuilder;
     
     class HeroComponent extends HtmlBuilder
     {
         public function render(): string
         {
             return $this->div(['class' => 'hero'])->h1('Welcome')->render();
         }
     }
     

   • Embed components in controllers:

     return $this->render('home', [
         'hero' => new HeroComponent(),
     ]);
     

2. Dynamic Route Handling

   • Use CMS controllers for dynamic content:

     class BlogController extends CmsController
     {
         public function show($slug)
         {
             $post = Post::where('slug', $slug)->firstOrFail();
             return $this->render('blog.post', compact('post'));
         }
     }
     

   • Register routes with parameters:

     Route::get('/blog/{slug}', [BlogController::class, 'show']);
     

3. Layout Integration

   • Extend the Graphite layout (or another) in app/Providers/AppServiceProvider:

     use Apie\CmsLayoutGraphite\GraphiteLayout;
     
     public function boot()
     {
         $this->app->singleton(GraphiteLayout::class, function () {
             return new GraphiteLayout(config('cms.layout'));
         });
     }
     

4. Middleware for CMS Logic

   • Attach middleware to CMS routes (e.g., auth, caching):

     Route::middleware(['auth', 'cms.cache'])->group(function () {
         Route::get('/admin', [AdminController::class, 'index']);
     });
     

Integration Tips

• Asset Management Use Laravel Mix/Vite to compile assets for CMS templates. Ensure the layout package supports your asset pipeline.

• Database-Driven Pages Store page configurations in a pages table and fetch dynamically:

  $page = Page::where('slug', $slug)->with('components')->first();
  return $this->render($page->template, $page->data);
  

• API-Driven Content Fetch content from an API and pass to views:

  $content = Http::get('https://api.example.com/content')->json();
  return $this->render('api-page', ['content' => $content]);
  

• Testing Use Laravel’s testing tools to mock CMS controllers:

  $response = $this->get('/my-page');
  $response->assertViewIs('my-page');
  

Gotchas and Tips

Pitfalls

1. Missing Layout Package

   • Error: Class 'Apie\CmsLayoutGraphite\GraphiteLayout' not found.
   • Fix: Install apie/cms-layout-graphite (or another layout package) and publish its config.

2. Route Caching Conflicts

   • Issue: CMS routes may not reflect changes after php artisan route:cache.
   • Fix: Clear cached routes or use php artisan route:clear during development.

3. Component Autoloading

   • Problem: Custom components not found.
   • Fix: Ensure components are in app/Components or autoloaded via composer.json:

     "autoload": {
         "psr-4": {
             "App\\Components\\": "app/Components/"
         }
     }
     

4. Blade Template Inheritance

   • Gotcha: Forgetting @extends('layouts.graphite') in child templates.
   • Tip: Use a Blade snippet or IDE template to auto-generate the extends line.

5. Middleware Priority

   • Issue: CMS middleware not applied.
   • Fix: Register middleware in app/Http/Kernel.php under the correct group (e.g., web).

Debugging Tips

1. View Debugging

   • Enable Blade debugging in .env:

     DEBUG_BLADE_COMPILED=true
     

   • Check compiled views at storage/framework/views.

2. Route Debugging

   • List all CMS routes:

     php artisan route:list | grep cms
     

3. Component Debugging

   • Dump component output:

     dd((new HeroComponent())->render());
     

4. Layout Debugging

   • Override layout partials in resources/views/layouts/partials/ to test changes without modifying the package.

Extension Points

1. Custom Layouts

   • Extend Apie\Cms\Contracts\Layout to create new layouts:

     class MyLayout implements Layout
     {
         public function render(View $view): string
         {
             return $this->wrap($view, 'my-layout-template');
         }
     }
     

2. Dynamic Component Registration

   • Register components dynamically in a service provider:

     $this->app->bind(HeroComponent::class, function () {
         return new HeroComponent(config('cms.hero_settings'));
     });
     

3. Event Listeners

   • Listen for CMS events (e.g., Cms.PageRendering):

     use Apie\Cms\Events\PageRendering;
     
     Event::listen(PageRendering::class, function (PageRendering $event) {
         $event->view->with('analytics', true);
     });
     

4. Custom Middleware

   • Create middleware to validate CMS content:

     class ValidateCmsContent
     {
         public function handle(Request $request, Closure $next)
         {
             if (!$request->user()->can('edit-cms')) {
                 abort(403);
             }
             return $next($request);
         }
     }
     

5. API Integration

   • Extend CMS controllers to fetch remote content:

     use Apie\Cms\Contracts\CmsController;
     
     class RemoteContentController extends CmsController
     {
         public function fetch()
         {
             $data = Http::get('https://api.example.com/data')->json();
             return $this->render('remote-content', ['data' => $data]);
         }
     }