Filament Univer Sheet Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • Seamless Filament Integration: Designed as a first-class plugin for Filament 5.x, leveraging its form/infolist/table ecosystems. Aligns with Filament’s component-based architecture, reducing friction for adoption.
  • Modular Components: Offers three distinct use cases (SpreadsheetField, SpreadsheetEntry, SpreadsheetColumn) tailored to CRUD workflows, reducing over-engineering for specific needs.
  • JSON Persistence: Uses Eloquent’s json cast, eliminating custom serialization logic and integrating cleanly with Laravel’s ORM. Avoids bloated database migrations.
  • Univer Sheet Backend: Leverages a mature, actively maintained spreadsheet engine (1.5K stars) with formula support, multi-sheet tabs, and 12 locales. Reduces technical debt from building a custom solution.
  • Dark Mode & Accessibility: Inherits Univer Sheet’s theming and keyboard navigation, aligning with modern admin panel expectations.

• Gaps:

  • No Server-Side Processing: Client-side only; complex calculations (e.g., pivot tables, advanced formulas) require backend logic. May necessitate pairing with PhpSpreadsheet for heavy lifting.
  • Limited Collaboration: Lacks real-time sync (e.g., WebSockets). Not suitable for multi-user editing without additional infrastructure.
  • Performance Unknowns: Univer Sheet’s scalability with large datasets (>10K rows) is untested in the package. Risk of UI lag or memory leaks in production.
  • Excel I/O Absent: No native .xlsx import/export. Requires integration with Maatwebsite/Excel or similar for file-based workflows.

Integration Feasibility

• Stack Compatibility:

  • Laravel 11+ / Filament 5.x: Hard dependency. Non-negotiable for adoption.
  • PHP 8.3+: Modern features (e.g., enums, attributes) may require codebase updates if using older versions.
  • Frontend: Bundles Univer Sheet via esbuild IIFE. No React/Vue dependencies; works with Filament’s Alpine.js-based UI.
  • Database: Assumes longText or json columns. Compatible with PostgreSQL/MySQL but may need schema adjustments for SQLite.

• Migration Path:

  • Low Effort: Replace existing textarea/json fields with SpreadsheetField in forms. Example:

    // Before
    Textarea::make('pricing_data')->rows(10),
    
    // After
    SpreadsheetField::make('pricing_data')->height('600px'),
    

  • Backward Compatible: Existing JSON data in databases can be used as-is (no migration scripts needed).
  • Incremental Rollout: Start with SpreadsheetColumn for table previews (low risk), then expand to forms/infolists.

• Compatibility Risks:

  • Filament Customizations: May conflict with heavily modified Filament panels (e.g., custom CSS/JS). Test with your theme.
  • Third-Party Plugins: Potential overlaps with other Filament plugins using similar assets (e.g., filament-spreadsheet). Audit for namespace collisions.
  • Caching: Univer Sheet’s client-side state may interact with Filament’s cache (e.g., filament:cache). Monitor for stale data.

Technical Risk

• High:

  • Data Corruption: Double-encoding JSON if dehydrateStateUsing is misconfigured (package warns against this, but risk remains for teams unfamiliar with Eloquent casts).
  • Formula Limitations: Univer Sheet’s formula engine may not support all business logic (e.g., custom functions). Validate with your use cases.
  • Asset Bloat: Univer Sheet’s JS bundle (~500KB gzipped) may impact initial page load. Test with your CDN and asset optimization.

• Medium:

  • Localization: Only English/Japanese translations included. Additional locales require manual configuration or forks.
  • Mobile Support: Univer Sheet’s UI may not adapt well to touch devices. Test on target platforms.
  • Debugging Complexity: Client-side errors (e.g., formula syntax) may be opaque. Requires familiarity with browser dev tools.

• Low:

  • License Compliance: MIT-licensed (Univer Sheet is Apache 2.0). No legal risks for commercial use.
  • Dependency Updates: Single Composer package with no transitive risks (unlike npm-based solutions).

Key Questions

1. Data Volume:
   • What’s the maximum row/column count users will edit? (Test with 1K+ rows to validate performance.)
2. Formula Requirements:
   • Does your app rely on advanced Excel functions (e.g., INDEX-MATCH, SUMIFS)? If yes, prototype first.
3. Collaboration Needs:
   • Will multiple users edit the same spreadsheet simultaneously? If yes, plan for offline-first or WebSocket integration.
4. Excel Workflows:
   • Is .xlsx import/export a must-have? If so, budget for Maatwebsite/Excel integration.
5. Filament Customizations:
   • Does your panel override Filament’s default assets (e.g., CSS/JS)? Audit for conflicts.
6. Backup/Restore:
   • How will you handle spreadsheet data backups? JSON blobs may require custom export logic.
7. Access Control:
   • Will row/column-level permissions be needed? Univer Sheet lacks built-in RBAC; may require custom UI.

Integration Approach

Stack Fit

• Frontend:
  • Alpine.js: Univer Sheet integrates natively with Filament’s Alpine-based UI. No React/Vue required.
  • Asset Pipeline: Uses esbuild IIFE for minimal bundle impact. Leverage Filament’s filament:assets for optimization.
  • Dark Mode: Inherits Filament’s dark mode via CSS variables. Test with your theme.
• Backend:
  • Eloquent: JSON persistence aligns with Laravel’s ORM. No ORM extensions needed.
  • Validation: Use Filament’s built-in validation (e.g., required, max) on the containing model.
  • APIs: If exposing spreadsheets via API, return JSON directly (no custom serialization).
• Database:
  • Schema: Use longText for large datasets or json for structured data. Example:

    $table->json('spreadsheet_data')->nullable();
    

  • Indexing: Avoid indexing JSON columns unless querying specific paths (e.g., ->whereJsonContains('data->sheets->sheet1->A1', 'value')).

Migration Path

1. Phase 1: Table Previews (Low Risk)

   • Replace TextColumn with SpreadsheetColumn for compact data visualization.
   • Example:

     SpreadsheetColumn::make('inventory')
         ->previewRows(5)
         ->previewColumns(4),
     

   • Goal: Validate UI/UX with minimal code changes.

2. Phase 2: Form Editors (Medium Risk)

   • Replace Textarea/RichEditor for tabular data with SpreadsheetField.
   • Example:

     SpreadsheetField::make('configurations')
         ->showFormulaBar()
         ->ribbonType('simple'),
     

   • Goal: Enable in-app editing for power users.

3. Phase 3: Infolist Displays (Low Risk)

   • Add SpreadsheetEntry to read-only views for data auditability.
   • Example:

     SpreadsheetEntry::make('audit_log')
         ->height('400px')
         ->showToolbar(false),
     

   • Goal: Surface complex data in admin panels without clutter.

4. Phase 4: Advanced Features (High Risk)

   • Implement custom formula handling or Excel I/O.
   • Goal: Address edge cases post-core adoption.

Compatibility

• Filament Plugins:
  • Conflicts: Avoid plugins that modify Filament’s asset pipeline (e.g., filament-assets). Use filament:assets after all plugin installations.
  • Dependencies: Test with plugins using similar JS bundles (e.g., filament-tables). Monitor for namespace collisions.
• Laravel Packages:
  • ORM: Compatible with Eloquent, but avoid packages that override JSON casting (e.g., spatie/laravel-json).
  • Testing: Use filament:test alongside existing test suites.
• Custom Code:
  • Form Builders: If using custom form builders (e.g., Nova-like), adapt the SpreadsheetField to your component structure.
  • Middleware: Ensure no middleware strips JSON data (e.g., trim filters on longText columns).

Sequencing