Sharp Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require code16/sharp
   php artisan vendor:publish --tag=sharp-assets --force
   php artisan migrate
   

2. Configure via Service Provider: Create a custom provider extending SharpAppServiceProvider and implement configureSharp():

   use Code16\Sharp\SharpAppServiceProvider;
   
   class SharpServiceProvider extends SharpAppServiceProvider
   {
       protected function configureSharp(SharpConfigBuilder $config): void
       {
           $config
               ->setName('My CMS')
               ->declareEntity(\App\Sharp\Entities\PostEntity::class);
       }
   }
   

3. First Use Case: Define a simple entity (e.g., PostEntity) and access it via /sharp/posts (or your custom URL segment).

Implementation Patterns

Core Workflows

1. Entity Management:

   • Define entities with declareEntity() in the config builder.
   • Use Sharp\Entities\Entity traits for CRUD operations (e.g., SingleInstanceTrait, ListTrait).

   class PostEntity extends Entity
   {
       use SingleInstanceTrait, ListTrait;
       // ...
   }
   

2. Forms and Validation:

   • Leverage Sharp\Form\Fields for form fields (e.g., TextField, RichTextField).
   • Validate data via Sharp\Validation\Rules or Laravel’s built-in rules.

   protected function buildForm(): array
   {
       return [
           TextField::make('title')->required(),
           RichTextField::make('content'),
       ];
   }
   

3. Search and Filtering:

   • Implement Sharp\Search\SearchEngine for custom search logic.
   • Use GlobalFilter to apply filters across entities.

   class PostSearchEngine implements SearchEngine
   {
       public function search(string $query): Collection
       {
           return Post::where('title', 'like', "%{$query}%")->get();
       }
   }
   

4. Authorization:

   • Extend Sharp\Authorization\Authorizer for custom rules.
   • Use can() in entities to enforce permissions.

   class PostEntity extends Entity
   {
       public function canCreate(): bool
       {
           return auth()->user()->isAdmin();
       }
   }
   

5. Commands and Actions:

   • Create custom commands for bulk operations (e.g., SingleInstanceCommand, EntityCommand).

   class PublishPostCommand extends SingleInstanceCommand
   {
       public function handle(): void
       {
           $this->instance->update(['status' => 'published']);
       }
   }
   

Integration Tips

• Laravel Ecosystem: Use Laravel’s Eloquent models as the data layer; Sharp handles the UI/UX.
• Inertia.js: Sharp uses Inertia for frontend rendering. Customize views in resources/js/Pages/Sharp.
• APIs: Expose Sharp entities via Laravel APIs by extending Sharp\Http\Controllers\ApiController.

Gotchas and Tips

Pitfalls

1. Middleware Conflicts:

   • Ensure HandleGlobalFilters and SubstituteBindings are in the correct order (Sharp docs specify SubstituteBindings must come after HandleGlobalFilters).
   • Remove SetSharpLocale from the api middleware group if using the new config builder.

2. Icon Migration:

   • Sharp 9.x requires blade-icons. Update icon names from FontAwesome (e.g., fas fa-user → fas-user).
   • For backward compatibility, install owenvoke/blade-fontawesome and configure default attributes.

3. Deprecated Methods:

   • buildListFields() and buildListLayout() were replaced with buildList().
   • The delete() method in forms was moved to Show or EntityList.

4. 2FA Setup:

   • For TOTP, ensure the users table has two_factor_secret, two_factor_recovery_codes, and two_factor_confirmed_at columns.
   • Use pragmarx/google2fa-laravel and bacon/bacon-qr-code for TOTP support.

5. Global Filters:

   • Auth context is unavailable in addGlobalFilter(). Use the authorize() method of the filter instead.

Debugging Tips

• Clear Caches:

  php artisan view:clear
  php artisan cache:clear
  

• Log Sharp Events: Enable Sharp’s debug mode in the config builder:

  $config->enableDebug();
  

• Check Inertia Props: Use dd($this->props) in Inertia pages to inspect passed data.

Extension Points

1. Custom Handlers:

   • Extend Sharp2faNotificationHandler or Sharp2faTotpHandler for 2FA customization.
   • Override isEnabledFor() to restrict 2FA to specific users.

2. Search Engines:

   • Implement Sharp\Search\SearchEngine for full-text search or external APIs (e.g., Algolia).

3. Menu Customization:

   • Extend Sharp\Menu\SharpMenu to dynamically build menus.
   • Use addEntityLink() with logo for icons (e.g., logo: 'fas-user').

4. Form Fields:

   • Create custom fields by extending Sharp\Form\Field.
   • Example: Add a ColorPickerField for hex color inputs.

5. Commands:

   • Extend SingleInstanceWizardCommand for multi-step workflows (e.g., 2FA setup).
   • Use EntityCommand for bulk actions (e.g., export/import).