Laravel Indexable Laravel Package

Getting Started

Install the package via Composer:

composer require vendor/package-name

Publish the package configuration (if applicable):

php artisan vendor:publish --provider="Vendor\PackageName\PackageServiceProvider"

The core feature is now policy integration, enabling authorization checks directly in your application logic. Start by defining a policy for your model (e.g., PostPolicy for Post model):

php artisan make:policy PostPolicy --model=Post

Use the policy in your controller or service:

use Vendor\PackageName\Facades\PackageName;

public function update(Request $request, Post $post)
{
    if (PackageName::authorize($request->user(), 'update', $post)) {
        // Proceed with logic
    }
}

Check the README.md for the new authorize() method documentation.

Implementation Patterns

Policy Integration Workflow

1. Define Policies: Extend Laravel’s built-in Policy class for your models.
2. Register Policies: Bind policies in AuthServiceProvider:

   protected $policies = [
       Post::class => PostPolicy::class,
   ];
   

3. Leverage Package Facade: Use PackageName::authorize() to check permissions:

   if (PackageName::authorize($user, 'edit', $resource)) {
       // Authorized action
   }
   

4. Custom Logic: Extend the package’s policy handler (if needed) by publishing and modifying the config.

Common Use Cases

• API Gateways: Validate requests before processing:

  if (PackageName::authorize($request->user(), 'access', $resource)) {
      return $resource->load('comments');
  }
  

• Admin Panels: Restrict dashboard actions:

  if (PackageName::authorize(auth()->user(), 'manage', $module)) {
      return view('admin.module');
  }
  

• Middleware: Combine with Laravel middleware for global checks:

  public function handle($request, Closure $next)
  {
      if (!PackageName::authorize($request->user(), 'view', $request->route('resource'))) {
          abort(403);
      }
      return $next($request);
  }
  

Integration Tips

• Hybrid Authorization: Mix package policies with Laravel’s native Gate for granular control.
• Dynamic Policies: Pass dynamic resources (e.g., PackageName::authorize($user, 'delete', $postId)) if your policy supports it.
• Testing: Use PackageName::shouldAuthorize() in PHPUnit to mock policy checks:

  $this->partialMock(PackageName::class, function ($mock) {
      $mock->shouldReceive('authorize')->andReturn(true);
  });
  

Gotchas and Tips

Pitfalls

1. Policy Caching: Policies are cached by Laravel. Clear the cache after defining new policies:

   php artisan cache:clear
   

   Or use Policy::reset() in testing.
2. Resource Mismatch: Ensure the resource passed to authorize() matches the policy’s expected type (e.g., Post vs. int).
3. Facade vs. Direct Calls: Prefer the facade for consistency, but direct calls to the underlying service are possible:

   $service = app(Vendor\PackageName\Services\AuthorizationService::class);
   $service->check($user, 'action', $resource);
   

Debugging

• Policy Failures: Enable Laravel’s debug mode (APP_DEBUG=true) to log failed policy checks.
• Log Policy Checks: Extend the package’s logger by binding a custom Psr\Log\LoggerInterface in the service container:

  $this->app->bind(Vendor\PackageName\Contracts\Logger::class, function () {
      return Log::channel('policy');
  });
  

Extension Points

1. Custom Policy Handlers: Override the default handler by publishing the config and extending:

   'authorization' => [
       'handler' => Vendor\PackageName\Handlers\CustomHandler::class,
   ],
   

2. Policy Events: Listen for policy events (if the package emits them):

   Event::listen(Vendor\PackageName\Events\PolicyChecked::class, function ($event) {
       // Log or react to policy checks
   });
   

3. Dynamic Actions: Extend the package to support dynamic actions (e.g., PackageName::authorize($user, $action, $resource)) by implementing Vendor\PackageName\Contracts\DynamicPolicy.

Configuration Quirks

• Policy Namespaces: Ensure your policy classes are autoloaded. If using subdirectories, update composer.json:

  "autoload": {
      "psr-4": {
          "App\\Policies\\": "app/Policies/"
      }
  }
  

• Fallback Logic: Configure a fallback response for unauthorized actions in config/package-name.php:

  'unauthorized_response' => [
      'status' => 403,
      'message' => 'Unauthorized action.',
  ],