Graper Laravel Package

Technical Evaluation

Architecture Fit

• Filament-Centric Design: Perfectly aligns with Laravel/Filament stacks where admin panels are built using Filament. The package extends Filament’s plugin system, requiring minimal architectural changes to the existing Laravel app.
• Database-First Storage: Uses Eloquent models (GraperPage) to store page content (HTML, CSS, project data), enabling versioning, API access, and programmatic manipulation. This fits well with Laravel’s ORM-centric architecture.
• Component-Based Extensibility: Custom blocks are registered via PHP classes, leveraging Laravel’s service container and dependency injection. This approach is familiar to Laravel developers and avoids JavaScript-based extensions.
• Separation of Concerns: Frontend (GrapeJS editor) and backend (Filament admin + Laravel routes) are decoupled, allowing for future frontend framework upgrades (e.g., Livewire, Inertia) without breaking the package.

Integration Feasibility

• Laravel Compatibility: Supports Laravel 11/12/13 and Filament 3.2+/5.0+, which are widely adopted in modern Laravel projects. The package’s dependency on Spatie’s Laravel Package Tools ensures smooth integration with Laravel’s service provider and package management systems.
• Filament Plugin System: Follows Filament’s plugin architecture, requiring only registration in AdminPanelProvider. This is a low-risk integration point with minimal boilerplate.
• Route Conflicts: Default routes (/pages/{slug}, /graper/api/*) are configurable via graper.php config, reducing the risk of conflicts with existing routes. Custom route prefixes can be set to avoid overlaps.
• Asset Management: Relies on GrapeJS’s bundled assets, which are loaded via Filament’s asset pipeline. No custom webpack/vite configuration is required, simplifying integration.

Technical Risk

• GrapeJS Version Lock: The package uses GrapeJS v3, which may introduce compatibility risks if GrapeJS undergoes breaking changes. However, the MIT license allows for forks or patches if needed.
• Custom Block Complexity: While the package provides a straightforward API for custom blocks, complex blocks (e.g., those requiring dynamic data or interactivity) may require additional JavaScript or PHP logic, increasing development effort.
• Performance Overhead: GrapeJS is a feature-rich editor, which may add noticeable load times to the Filament admin panel. Testing under production-like conditions is recommended to assess impact.
• Limited Documentation: The package has basic documentation (README, changelog) but lacks detailed guides for advanced use cases (e.g., custom block interactivity, API extensions). This may require additional internal documentation or trial-and-error during integration.
• No Headless CMS Features: The package does not support features like multi-language content, media libraries, or user roles beyond Filament’s built-in capabilities. Projects requiring these may need additional layers.

Key Questions

1. Customization Depth:

   • How many custom blocks will be required, and what level of interactivity (e.g., dynamic data, API calls) will they need?
   • Will custom blocks require additional JavaScript (e.g., Alpine.js, Tailwind CSS) beyond the provided templates?

2. Performance Impact:

   • What is the expected load on the Filament admin panel with GrapeJS enabled? Will lazy-loading or asset optimization be needed?
   • How will published pages perform under traffic? Are there caching strategies (e.g., Laravel’s cache middleware) to mitigate load?

3. Content Management Workflow:

   • Will non-technical users (e.g., marketing teams) need training to use the drag-and-drop editor? What support will be required?
   • How will content approval workflows (e.g., staging/production environments) be handled? Will additional Filament policies or Laravel middleware be needed?

4. Extensibility:

   • Are there plans to extend the package’s API (e.g., adding endpoints for content versioning, bulk exports)? Could this be done via middleware or custom controllers?
   • How will the package handle future Filament or GrapeJS updates? Will automated testing (e.g., PHPUnit) be implemented to catch integration issues early?

5. Security:

   • How will CSRF protection be handled for the API endpoints (/graper/api/*)? Are there risks of XSS or CSS injection in user-generated HTML/CSS?
   • Will published pages be sanitized or escaped when rendered on the frontend? Are there risks of HTML/CSS-based attacks?

6. Scaling:

   • How will the database handle a large number of pages or blocks? Are there indexing or query optimization opportunities for the graper_pages table?
   • Will the package support multi-tenancy (e.g., SaaS environments with client-specific pages)? If so, how will data isolation be managed?

Integration Approach

Stack Fit

• Laravel/Filament Stack: The package is a first-class citizen in Laravel/Filament projects, requiring no additional frameworks or tools. It leverages:
  • Filament Plugins: Integrates via Filament’s plugin system, with zero impact on existing Filament resources or widgets.
  • Eloquent ORM: Stores page content in the database, enabling Laravel’s query builder, relationships, and migrations.
  • Laravel Routing: Uses Laravel’s routing system for both admin (edit) and frontend (publish) routes, with configurable prefixes.
  • Blade Templates: Renders published pages via Blade, allowing for seamless integration with existing frontend templates.
• Frontend Dependencies: Relies on GrapeJS (included via CDN or Filament’s asset pipeline) and Tailwind CSS for styling. No custom frontend build tools (e.g., webpack, Vite) are required.
• API-First Design: Provides RESTful endpoints for loading/saving page content, enabling programmatic access to page data.

Migration Path

1. Preparation:

   • Audit existing Filament admin panel and Laravel routes for conflicts with Graper’s default routes (/pages/*, /graper/api/*).
   • Backup the database and test environment.
   • Ensure Laravel 11/12/13 and Filament 3.2+/5.0+ are installed.

2. Installation:

   • Install the package via Composer:

     composer require cybertroniankelvin/graper
     

   • Run the one-step installer (recommended):

     php artisan graper:install
     

     This publishes the config, runs migrations, and sets up the graper_pages table.
   • Register the plugin in app/Providers/Filament/AdminPanelProvider.php:

     public function panel(Panel $panel): Panel {
         return $panel->plugins([
             GraperPlugin::make(),
         ]);
     }
     

3. Configuration:

   • Publish and customize the config (optional):

     php artisan vendor:publish --tag=graper-config
     

   • Update config/graper.php to set route prefixes, block defaults, or other settings.
   • Configure Filament’s asset pipeline to load GrapeJS and Tailwind CSS (if not already included).

4. Customization:

   • Blocks: Develop custom blocks by extending the Block class and registering them in a service provider:

     BlockRegistry::make()->register(CustomBlock::class);
     

   • Routes: Extend or override Graper’s routes in routes/web.php or routes/api.php as needed.
   • Frontend Integration: Add Blade directives or controllers to render pages in custom templates:

     @php
         $page = \Cybertroniankelvin\Graper\Models\GraperPage::where('slug', 'about')->first();
     @endphp
     {!! $page->html !!}
     <style>{!! $page->css !!}</style>
     

5. Testing:

   • Test the Filament admin panel to ensure the Graper plugin is accessible and functional.
   • Create and publish a test page to verify frontend rendering.
   • Test custom blocks for rendering and interactivity.
   • Load-test the admin panel and published pages to assess performance.

6. Deployment:

   • Deploy the package to staging for user acceptance testing (UAT).
   • Train non-technical users on the drag-and-drop editor and Filament workflows.
   • Monitor for issues in production and iterate based on feedback.

Compatibility

• Laravel Versions: Officially supports Laravel 11/12/13. Laravel 10 may work but is unsupported.
• Filament Versions: Requires Filament 3.2+ or 5.0+. Older versions may not support the plugin system.
• PHP Requirements: PHP 8.2+ is required, which aligns with modern Laravel projects.
• Database: Uses standard Laravel migrations for the graper_pages table. Compatible with MySQL, PostgreSQL, SQLite, and SQL Server.
• Frontend Frameworks: No strict requirements, but Tailwind CSS is used for styling blocks. Existing Tailwind setups will integrate smoothly.
• Third-Party Packages: No hard dependencies beyond Filament and GrapeJS. Soft dependencies (e.g., Spatie’s Laravel Package Tools) are optional.

Sequencing

1. Phase 1: Core Integration (2–3 weeks):
   • Install and configure the package.