Nova Pennant Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require laravel/nova-pennant
   

   Publish the configuration (if needed):

   php artisan vendor:publish --provider="Laravel\Nova\PennantTool\PennantToolServiceProvider"
   

2. Register the Tool: Add PennantTool::make() to your Nova resource's fields() method (as shown in the README). No additional configuration is required for basic usage.

3. First Use Case:

   • Log in to Nova as an admin.
   • Navigate to any resource where the tool is registered.
   • Open the Pennant tab to view and toggle feature flags for your application.

Implementation Patterns

Core Workflows

1. Feature Flag Management:

   • Use the tool to view all active/inactive Pennant features in a single interface.
   • Toggle flags directly in Nova without leaving the UI, reducing context switching.

2. Integration with Nova Resources:

   • Attach the tool to any Nova resource (e.g., User, Team, or custom resources) for centralized access.
   • Example: Add to a Settings resource for admin-only feature control:

     public function fields(NovaRequest $request) {
         return [
             // ... other fields ...
             PennantTool::make()->onlyOnDetail(),
         ];
     }
     

3. Role-Based Access:

   • Leverage Nova’s gates/policies to restrict tool visibility:

     PennantTool::make()->onlyOnForms()->canSee(fn ($request) => $request->user()->isAdmin());
     

4. Bulk Operations:

   • Use the tool’s search/filter to quickly locate and toggle specific features (e.g., disable a feature for all users except admins).

5. Environment-Specific Flags:

   • Configure Pennant to use environment-specific storage (e.g., .env overrides) and sync changes across environments via Nova.

Advanced Patterns

1. Customizing Feature Display: Override the tool’s default behavior by extending the PennantTool class:

   use Laravel\Nova\PennantTool\PennantTool as BasePennantTool;
   
   class CustomPennantTool extends BasePennantTool {
       public function fields(NovaRequest $request) {
           return [
               Text::make('Custom Field')->onlyOnForms(),
               parent::fields($request),
           ];
       }
   }
   

   Register the custom tool in your ToolServiceProvider.

2. Webhook Triggers: Use Pennant’s webhook events to notify external services (e.g., Slack, Datadog) when flags change:

   // In EventServiceProvider
   Pennant::onFeatureToggled(function ($feature, $isActive) {
       // Dispatch notification
   });
   

3. A/B Testing Integration: Combine with Nova’s metrics tools to track feature adoption:

   • Toggle a feature in Pennant.
   • Use Nova’s analytics to monitor user engagement post-toggle.

4. Multi-Tenant Isolation: Scope feature flags to tenants by extending Pennant’s Feature model:

   // app/Models/Pennant/Feature.php
   public function scopeForTenant($query, $tenantId) {
       return $query->where('tenant_id', $tenantId);
   }
   

Gotchas and Tips

Pitfalls

1. Authorization Misconfigurations:

   • Issue: Forgetting to restrict access to the tool can expose feature flags to unintended users.
   • Fix: Always use canSee() or Nova’s built-in gates:

     PennantTool::make()->canSee(fn ($request) => $request->user()->can('manage-features'));
     

2. Caching Conflicts:

   • Issue: Pennant flags may not update immediately if Laravel’s cache is enabled.
   • Fix: Clear the cache after toggling flags:

     php artisan cache:clear
     

     Or configure Pennant to bypass cache for critical flags:

     Pennant::disableCacheFor(['critical-feature']);
     

3. Performance with Large Feature Sets:

   • Issue: Loading hundreds of features can slow down Nova.
   • Fix: Use lazy loading or paginate the tool’s output:

     PennantTool::make()->perPage(20);
     

4. Environment Sync Delays:

   • Issue: Changes in staging may not reflect in production due to misconfigured storage.
   • Fix: Use a shared storage backend (e.g., Redis, database) for all environments:

     // config/pennant.php
     'storage' => 'database',
     

Debugging Tips

1. Log Feature Changes: Enable Pennant’s logging to track who toggled what:

   Pennant::enableLogging();
   

   Check logs at storage/logs/laravel.log.

2. Verify Tool Registration:

   • Ensure the tool is added to all relevant resources (e.g., User, Settings).
   • Check for typos in the PennantTool::make() class name.

3. Test Feature Visibility:

   • Use Nova’s incognito mode to test flag visibility as different users:

     php artisan nova:incognito
     

4. Database Schema Mismatches:

   • If flags disappear, run:

     php artisan pennant:install
     

     To reinstall the Pennant tables.

Extension Points

1. Custom Storage Backends: Extend Pennant’s FeatureRepository to support custom storage (e.g., S3, DynamoDB):

   Pennant::extend('s3', function () {
       return new S3FeatureRepository();
   });
   

2. Dynamic Feature Groups: Organize flags into collapsible groups in Nova:

   PennantTool::make()->groupFeaturesBy('category');
   

3. Audit Trails: Add a pennant_audit table to track changes:

   // In PennantToolServiceProvider
   Pennant::auditEnabled(true);
   

4. Dark Mode Compatibility: Override the tool’s CSS to match Nova’s dark theme:

   // resources/css/nova-pennant.css
   .nova-pennant-tool.dark-mode { /* Custom styles */ }