Package Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ajaykumaraipl/package
   

   Publish the package config (if available):

   php artisan vendor:publish --provider="AjayKumaraipl\Package\PackageServiceProvider"
   

2. First Use Case

   • Check the package's primary facade/class (e.g., Package:: or \AjayKumaraipl\Package\Facades\Package).
   • Example: If the package provides a helper for API responses, test:

     use AjayKumaraipl\Package\Facades\Package;
     
     $response = Package::success(['message' => 'Hello World']);
     return $response;
     

   • Verify the package’s documentation for a "Hello World" example or basic functionality.

3. Configuration

   • Review config/package.php (if published) for default settings.
   • Update values like API endpoints, logging preferences, or middleware bindings.

Implementation Patterns

Core Workflows

1. API Response Handling

   • Use the package’s response wrappers (e.g., Package::success(), Package::error()) to standardize API responses.
   • Example:

     return Package::success($data, 200, 'Resource fetched');
     return Package::error('Unauthorized', 401);
     

2. Middleware Integration

   • If the package includes middleware (e.g., for auth or logging), bind it in app/Http/Kernel.php:

     protected $middleware = [
         \AjayKumaraipl\Package\Http\Middleware\LogRequest::class,
     ];
     

3. Service Layer Abstraction

   • Use the package’s services (e.g., PackageService) to abstract logic:

     $service = app(\AjayKumaraipl\Package\Services\PackageService::class);
     $result = $service->process($request);
     

4. Event Listeners

   • Listen to package events (if provided) in EventServiceProvider:

     protected $listen = [
         \AjayKumaraipl\Package\Events\PackageEvent::class => [
             \App\Listeners\HandlePackageEvent::class,
         ],
     ];
     

5. Blade Directives

   • If the package adds Blade helpers, use them in views:

     @packageDirective('key', 'value')
     

Integration Tips

• Dependency Injection: Prefer constructor injection for package services:

  public function __construct(private PackageService $packageService) {}
  

• Testing: Mock the package’s facade/service in tests:

  $this->mock(\AjayKumaraipl\Package\Facades\Package::class);
  

• Customization: Override package behavior by extending its classes (e.g., extends PackageService).

Gotchas and Tips

Common Pitfalls

1. Facade vs. Service Confusion

   • Avoid mixing facades and direct service instantiation. Stick to one pattern per project.
   • Example: Prefer Package::method() over new PackageService() unless extending.

2. Configuration Overrides

   • Ensure config values are published and updated before use. Defaults may not match your needs.
   • Example: If the package uses a queue driver, verify config/package.php:

     'queue_driver' => env('QUEUE_CONNECTION', 'sync'),
     

3. Middleware Order

   • Package middleware may conflict with Laravel’s built-in middleware. Test order in Kernel.php:

     // Wrong: May block requests prematurely
     $middlewareGroups['web'] = [
         \AjayKumaraipl\Package\Http\Middleware\Auth::class, // Too early
     ];
     

4. Deprecated Methods

   • Check the package’s CHANGELOG.md or upgrading.md for breaking changes in newer versions.

5. Event Priorities

   • If using package events, ensure your listeners have the correct priority:

     Event::listen(
         \AjayKumaraipl\Package\Events\PackageEvent::class,
         \App\Listeners\HandlePackageEvent::class,
         -100 // High priority
     );
     

Debugging Tips

• Log Output: Enable debug mode and check Laravel logs for package-related errors:

  tail -f storage/logs/laravel.log | grep -i "ajaykumaraipl"
  

• Service Container: Dump the bound services to verify registration:

  dd(app()->has(\AjayKumaraipl\Package\PackageService::class));
  

• Configuration Dump: Verify loaded config:

  dd(config('package'));
  

Extension Points

1. Custom Responses

   • Extend the response wrapper by creating a decorator:

     use AjayKumaraipl\Package\Facades\Package as BasePackage;
     
     class Package extends BasePackage {
         public static function customResponse($data) {
             return response()->json(['custom' => $data]);
         }
     }
     

   • Alias the facade in config/app.php:

     'aliases' => [
         'Package' => \App\Facades\Package::class,
     ],
     

2. New Middleware

   • Create a custom middleware extending the package’s base:

     use AjayKumaraipl\Package\Http\Middleware\BaseMiddleware;
     
     class CustomMiddleware extends BaseMiddleware {
         public function handle($request, Closure $next) {
             // Logic
             return $next($request);
         }
     }
     

3. Event Extensions

   • Publish and extend package events:

     php artisan vendor:publish --tag=package-events
     

   • Modify app/Providers/EventServiceProvider.php to add listeners.

4. Blade Helpers

   • Register custom directives in AppServiceProvider:

     Blade::directive('packageCustom', function ($expression) {
         return "<?php echo customPackageLogic($expression); ?>";
     });