Components Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require sikessem/components
   

   Publish the package assets (if needed):

   php artisan vendor:publish --provider="Sikessem\Components\ComponentsServiceProvider"
   

2. First Use Case: Scaffold a Filament resource with built-in components:

   php artisan make:filament-resource Post --with-components
   

   This generates a resource with pre-configured Sikessem UI components (e.g., buttons, badges, and layouts).

3. Where to Look First:

   • Documentation: Sikessem Components Docs
   • Artisan Commands: Run php artisan list:sikessem to see available commands.
   • Example Resources: Check resources/Filament/Resources for auto-generated templates.

Implementation Patterns

Common Workflows

1. Scaffolding with Artisan: Use Sikessem’s commands to generate Filament resources, policies, or widgets with pre-configured components:

   # Generate a resource with Sikessem's UI components
   php artisan make:filament-resource User --with-components --with-policies
   
   # Create a custom widget (e.g., stats dashboard)
   php artisan make:filament-widget StatsOverview --with-sikessem-layout
   

2. Integrating UI Components: Replace default Filament components with Sikessem’s variants in your resources/forms:

   // app/Filament/Resources/UserResource/Pages/EditUser.php
   use Sikessem\Components\Filament\Widgets\ProfileCard;
   
   public function getWidgets(): array
   {
       return [
           ProfileCard::make(),
       ];
   }
   

3. Tailwind Customization: Extend Sikessem’s Tailwind presets in resources/css/filament/app.css:

   @layer components {
       @import 'vendor/sikessem/components/resources/css/filament/components.css';
       @import 'resources/css/filament/custom.css'; /* Override here */
   }
   

4. Policy/Permission Helpers: Use Sikessem’s policy macros to simplify authorization:

   // app/Policies/UserPolicy.php
   use Sikessem\Components\Support\Facades\PolicyHelper;
   
   public function viewAny(User $user)
   {
       return PolicyHelper::canViewAny($user, User::class);
   }
   

5. Reusable Form Patterns: Leverage Sikessem’s form macros in Filament forms:

   // app/Filament/Resources/UserResource/Pages/CreateUser.php
   use Sikessem\Components\Filament\Forms\Components\SikessemTextInput;
   
   public function form(Form $form): Form
   {
       return $form
           ->schema([
               SikessemTextInput::make('name')
                   ->label('Full Name')
                   ->required(),
           ]);
   }
   

Gotchas and Tips

Pitfalls

1. Component Overrides:

   • Sikessem components may override Filament’s default styles. If styles break, inspect the generated CSS and override in custom.css using !important sparingly.
   • Fix: Use Tailwind’s utility classes or extend Sikessem’s base classes:

     .filament-widgets .sikessem-card {
         @apply border-blue-500; /* Override border color */
     }
     

2. Artisan Command Conflicts:

   • Sikessem’s commands (e.g., make:filament-resource) may conflict with Filament’s built-in commands if not namespaced properly.
   • Fix: Use --with-components flag explicitly to avoid ambiguity.

3. Policy Macro Caching:

   • Sikessem’s policy helpers cache permissions. Clear the cache if changes aren’t reflected:

     php artisan cache:clear
     php artisan view:clear
     

4. Tailwind Version Mismatch:

   • Sikessem assumes a specific Tailwind version. If your project uses a different version, components may render incorrectly.
   • Fix: Pin Tailwind to v3.x in package.json or manually adjust Sikessem’s CSS imports.

Debugging Tips

1. Inspect Generated HTML: Use browser dev tools to verify components render as expected. Sikessem components often add custom classes like sikessem-*.

2. Log Artisan Output: Run commands with -v for verbose output:

   php artisan make:filament-resource Post --with-components -v
   

3. Check Published Assets: After publishing, verify resources/css/filament/app.css includes Sikessem’s imports:

   php artisan vendor:publish --tag=filament-css
   

Extension Points

1. Custom Components: Extend Sikessem’s base components by copying and modifying files from vendor/sikessem/components/src/Filament/Components. Place overrides in app/Filament/Components.

2. Theme Support: Sikessem supports Filament themes. Create a custom theme by extending Sikessem’s presets:

   // config/filament.php
   'theme' => [
       'custom' => [
           'path' => resource_path('views/vendor/filament/themes/custom'),
           'components' => [
               'widgets' => [
                   'ProfileCard' => Sikessem\Components\Filament\Widgets\ProfileCard::class,
               ],
           ],
       ],
   ],
   

3. Command Customization: Override Sikessem’s Artisan commands by publishing and modifying their templates:

   php artisan vendor:publish --tag=sikessem-commands
   

   Edit templates in resources/views/vendor/sikessem/commands.

4. Permission Logic: Extend Sikessem’s policy helpers by creating a custom macro:

   // app/Providers/AppServiceProvider.php
   use Sikessem\Components\Support\Facades\PolicyHelper;
   
   public function boot()
   {
       PolicyHelper::macro('customCanView', function ($user, $model) {
           // Custom logic
           return $user->can('custom_view', $model);
       });
   }