Rjcms Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require rjcodes/rjcms
   php artisan rjcms:install --admin-email="admin@example.com" --admin-password="password"
   

   • The installer handles migrations, config publishing, and initial admin setup.

2. First Use Case:

   • Access /admin and log in with the credentials you set.
   • Navigate to Content Types to define your first custom content type (e.g., "Blog Post").
   • Add fields (title, body, featured image) using the BREAD builder (no manual migrations needed).
   • Create and manage content via the intuitive UI.

Where to Look First

• Admin Dashboard: /admin – Familiar WordPress-style layout.
• BREAD Builder: Under Content Types – Define schemas visually.
• Media Library: Under Media – Upload and manage assets.
• Documentation: Check the GitHub README for advanced features (e.g., permissions, menus).

Implementation Patterns

Core Workflows

1. Content Type Management:

   • Define a content type (e.g., Product) with fields like name, description, and price.
   • Use the BREAD builder to configure relationships (e.g., linking Product to a Category).
   • Example:

     // Access content via Eloquent (auto-generated models)
     $products = \App\Models\Product::with('category')->get();
     

   • Display content in your frontend using Laravel Blade:

     @foreach($products as $product)
         <h2>{{ $product->name }}</h2>
         <p>{{ $product->description }}</p>
     @endforeach
     

2. Media Handling:

   • Upload files via the Media Library (accessible in the admin panel).
   • Attach media to content types (e.g., featured_image field).
   • Retrieve media URLs in your frontend:

     $imageUrl = $product->featured_image->url; // Assuming `featured_image` is a media field
     

3. Menus and Navigation:

   • Build menus via the Menus section in the admin panel (drag-and-drop).
   • Render menus in your frontend:

     {!! menu('main') !!}
     

   • Customize menu rendering by extending the MenuRenderer service.

4. Permissions and Roles:

   • Assign roles (e.g., admin, editor) and permissions to users via the Users section.
   • Gate access programmatically:

     @can('update-posts')
         <button>Edit Post</button>
     @endcan
     

5. Site Settings:

   • Configure global settings (e.g., site name, logo) via Settings.
   • Access settings in your code:

     $siteName = \RJCMS\Settings::get('site_name');
     

Integration Tips

• Frontend Integration:

  • Use the rjcms::content directive to fetch content types:

    @php
        $posts = \RJCMS\Facades\Content::type('post')->get();
    @endphp
    

  • Extend the package’s views by publishing assets:

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

• Custom Fields:

  • Extend the field types by publishing the config and adding your own field classes in app/Providers/RJCMSServiceProvider.php:

    public function boot()
    {
        RJCMS::extend('custom_field', \App\Fields\CustomField::class);
    }
    

• API Endpoints:

  • Use Laravel’s built-in API resources to expose content types:

    Route::apiResource('posts', \App\Http\Controllers\PostController::class);
    

  • Authenticate API requests with Laravel Sanctum or Passport.

• Livewire Components:

  • Leverage Livewire for dynamic admin panels. The package uses Livewire under the hood, so you can create custom Livewire components for extended functionality.

Gotchas and Tips

Pitfalls

1. Field Type Limitations:

   • The BREAD builder supports common field types (text, image, relationship, repeater), but custom field types require manual extension. Ensure you publish the config and register your field classes properly.
   • Example error: If a custom field isn’t registered, you’ll see a ClassNotFoundException when trying to use it in the builder.

2. Media Storage:

   • By default, media is stored in storage/app/public. Ensure your filesystems.php config is set up correctly:

     'public' => [
         'driver' => 'local',
         'root' => storage_path('app/public'),
         'url' => env('APP_URL').'/storage',
         'visibility' => 'public',
     ],
     

   • Run php artisan storage:link to create the symlink for public access.

3. Permission Conflicts:

   • If you manually create users or roles outside the package, ensure their permissions align with the package’s default roles (e.g., admin, editor). Mismatched permissions may cause access issues.

4. Idempotent Installer:

   • While the installer is idempotent, re-running it may overwrite your customizations (e.g., config, migrations). Backup your config/rjcms.php before re-installing.

5. Livewire Dependencies:

   • The package requires Livewire 4. Ensure your composer.json includes:

     "livewire/livewire": "^4.0"
     

   • Conflicts may arise if you’re using an older version of Livewire.

Debugging

• Log Viewer:

  • Use Laravel’s log viewer (php artisan log:view) to debug issues with content types, media uploads, or permissions.

• Database Inspection:

  • Check the rjcms_content_types, rjcms_fields, and rjcms_media tables for misconfigurations. Example:

    SELECT * FROM rjcms_content_types WHERE slug = 'post';
    

• Common Errors:

  • 404 on /admin: Ensure the admin middleware group is properly configured in app/Http/Kernel.php.
  • Field Validation Errors: Validate field configurations in the BREAD builder UI. Use the "Test" button to preview.

Tips

1. Demo Content:

   • Use the --demo flag during installation to explore pre-built content types and fields:

     php artisan rjcms:install --demo
     

2. Custom Admin Routes:

   • Extend the admin panel by adding custom routes in routes/admin.php (published by the installer). Example:

     Route::get('/reports', [ReportController::class, 'index'])->middleware('can:view-reports');
     

3. Performance:

   • For large media libraries, optimize storage by using cloud services (e.g., S3) and configure caching for frequently accessed content types.

4. Localization:

   • The package supports localization. Extend the language files in resources/lang/vendor/rjcms to add translations.

5. Backup Strategy:

   • Regularly back up the rjcms_content_types, rjcms_fields, and rjcms_media tables, as these store your schema and assets.

6. Extending the Builder:

   • To add a custom field type (e.g., color_picker), create a class in app/Fields and register it in the service provider:

     RJCMS::extend('color_picker', \App\Fields\ColorPickerField::class);
     

   • Ensure your field class implements RJCMS\Contracts\Field.

7. Testing:

   • Use Laravel’s testing helpers to interact with the admin panel:

     $response = $this->actingAs($adminUser)->get('/admin');
     $response->assertStatus(200);