Cms Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require tallcms/cms
   php artisan tallcms:install

• Runs migrations, publishes config, and sets up default permissions.

2. Register Plugin: Add to your Filament panel provider (e.g., app/Providers/Filament/AdminPanelProvider.php):

   ->plugin(TallCmsPlugin::make())
   

3. User Model: Add HasRoles trait to your User model:

   use Spatie\Permission\Traits\HasRoles;
   class User extends Authenticatable { use HasRoles; }
   

4. First Use Case:

   • Create a Page (/admin/pages) or Post (/admin/posts) via Filament UI.
   • Use the block editor (WYSIWYG) to add content (e.g., Hero, Text, Media blocks).
   • Publish and preview via the "Preview" button.

Key Entry Points

• Admin Panel: Accessible at /admin (default Filament route).
• Frontend: Content renders via Blade components (e.g., @tallcms('page', 'home')).
• Documentation: Start with Installation Guide and Blocks.

Implementation Patterns

Core Workflows

1. Content Management

• Pages/Posts:

  • Create via Filament resources (/admin/pages, /admin/posts).
  • Use slugs for URL routing (e.g., /about).
  • Translations: Enable via config/tallcms.php (locales array) and use the "Copy from default" button for multilingual content.
  • Status Workflow: Draft → Pending Review → Scheduled → Published.

• Blocks:

  • Built-in Blocks: Hero, Text, Media, Grid, etc. (see Blocks Docs).
  • Custom Blocks: Extend TallCms\Cms\Blocks\Block and register via:

    TallCmsPlugin::make()->withBlocks([
        new \App\Blocks\CustomBlock(),
    ]);
    

  • Dynamic Data: Use {{ $block->field }} in Blade templates or access via $block->getContent().

• Media Library:

  • Upload assets via /admin/media.
  • Organize into collections (e.g., "Hero Images").
  • Reference in blocks using the media picker.

2. Theming

• Frontend Templates:

  • Override default themes by publishing assets:

    php artisan vendor:publish --tag=tallcms-themes
    

  • Customize via Blade components (e.g., @tallcms('theme', 'header')).
  • Dynamic Themes: Switch themes per-site (multisite) or globally via config/tallcms.php.

• CSS/JS:

  • Extend via Vite (Node 20+ required). Add to resources/js/tallcms.js:

    import './blocks/custom-block.js'; // Custom block logic
    

  • Compile with npm run dev or npm run build.

3. Menus

• Menu Builder:
  • Create menus via /admin/menus.
  • Link to pages, posts, or external URLs.
  • Dynamic Menus: Render in Blade:

    @tallcms('menu', 'primary')
    

4. Forms & Comments

• Contact Forms:

  • Create forms via /admin/forms.
  • Submit data via frontend (e.g., @tallcms('form', 'contact')).
  • Configure email notifications in Filament.

• Comments:

  • Enable on posts/pages via Filament toggle.
  • Moderate via /admin/comments.

5. Multilingual Support

• Locale Setup:
  • Configure in config/tallcms.php:

    'locales' => [
        'en' => ['name' => 'English', 'rtl' => false],
        'es' => ['name' => 'Español', 'rtl' => false],
    ],
    

  • URL Routing: Use helpers:

    <a href="{{ tallcms_localized_route('page.show', ['page' => $page, 'locale' => 'es']) }}">
    

  • Blade Components:

    @tallcms('language-switcher')
    

6. API & Frontend Integration

• API Endpoints:

  • Fetch content via Laravel routes (e.g., Route::get('/api/pages/{page}', [PageController::class, 'show'])).
  • Use Page::getUrl() for dynamic links.

• Preview Tokens:

  • Generate tokens for unpublished content:

    $token = $page->createPreviewToken();
    

  • Use in frontend URLs: /preview?token=$token.

7. Multisite (Commercial Add-on)

• Site Management:
  • Create sites via /admin/sites.
  • Assign themes, settings, and content per-site.
  • Embed Code: Override global scripts/styles per-site via /admin/sites/{site}/edit → "Embed Code" tab.

Integration Tips

Filament Customization

• Disable Components:

  TallCmsPlugin::make()
      ->withoutPages()
      ->withoutPosts()
  

• Extend Resources: Override Filament resources by publishing and modifying:

  php artisan vendor:publish --tag=tallcms-filament-resources
  

Performance

• Lazy-Load Blocks: Use @once in Blade to cache block rendering:

  @once
      @tallcms('page', 'home')
  @endonce
  

• Media Optimization: Configure storage drivers (config/filesystems.php) for S3/DigitalOcean R2.

Debugging

• Log Block Content:

  \Log::debug('Block content:', ['content' => $block->getContent()]);
  

• Check Permissions: Use php artisan filament:shield:check to verify user roles.

Gotchas and Tips

Pitfalls

1. PHP Version Mismatch:

   • Issue: v4.6.2+ requires PHP 8.3+ for Laravel 13. Older versions (e.g., PHP 8.2) may fail with Symfony 8.1 compatibility errors.
   • Fix: Downgrade or update:

     composer require laravel/framework:^12.0
     

     Or upgrade PHP to 8.3+.

2. Node Version:

   • Issue: Node 20+ is required for Vite builds. Older versions (e.g., Node 18) may fail with syntax errors.
   • Fix: Use nvm to switch versions:

     nvm install 20
     nvm use 20
     

3. Multilingual Slugs:

   • Issue: Slugs are locale-specific. Changing a default locale slug may break links in other locales.
   • Fix: Use tallcms_localized_route() with explicit locales:

     {{ tallcms_localized_route('page.show', ['page' => $page, 'locale' => 'en']) }}
     

4. Revision Pruning:

   • Issue: Manual revision limits prune oldest revisions (not newest) due to a bug in v4.6.4 and earlier.
   • Fix: Update to v4.6.4+ or manually delete old revisions via:

     $page->revisions()->orderBy('revision_number', 'asc')->limit(5)->delete();
     

5. Embed Code Scope:

   • Issue: Global embed code (e.g., Google Analytics) may override per-site settings if not scoped correctly.
   • Fix: Use SiteSettingsService::setForSite() with explicit site_id:

     use TallCms\Cms\Services\SiteSettingsService;
     SiteSettingsService::setForSite($siteId, 'code_head', '<script>...</script>');
     

6. Block Editor Conflicts:

   • Issue: Custom JavaScript may break the block editor (e.g., Alpine.js conflicts).
   • Fix: Isolate scripts in the editor:

     // resources/js/tallcms.js
     if (window.location.pathname.includes('/admin')) {
         // Editor-specific logic
     }
     

7. Permission Orphans:

   • Issue: Upgrading from v4.3.2 may leave orphaned `Manage:CodeInjection