Laravel Sphinxsearch Laravel Package

Getting Started

Install via Composer:

composer require vendor/package-name

Publish the package's configuration (if applicable) with:

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

For Laravel 11/12, ensure your config/app.php includes the service provider in the providers array under the correct framework version section. The package now officially supports both Laravel 11.x and 12.x, so no additional setup is required beyond standard Laravel initialization.

First use case: Use the package's facade or helper directly in a controller or command:

use Vendor\PackageName\Facades\PackageFacade;

Route::get('/example', function () {
    return PackageFacade::doSomething();
});

Implementation Patterns

Core Workflows

1. Service Integration:

   • Register the package's service in AppServiceProvider (if not auto-discovered):

     public function register()
     {
         $this->app->singleton('package.service', function ($app) {
             return new \Vendor\PackageName\Services\PackageService();
         });
     }
     

   • For Laravel 12, leverage the new bind() method in AppServiceProvider if using dependency injection:

     public function register()
     {
         $this->app->bind(\Vendor\PackageName\Contracts\PackageContract::class, function () {
             return new \Vendor\PackageName\Services\PackageService();
         });
     }
     

2. Configuration:

   • Access config values via config('package.key'). Example:

     $timeout = config('package.timeout', 30); // Fallback to 30 if undefined
     

   • Override defaults in config/package.php (published via vendor:publish).

3. Event Listeners:

   • Attach listeners in EventServiceProvider (Laravel 11/12 compatible):

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

4. Middleware:

   • Register middleware in app/Http/Kernel.php under $middleware or $routeMiddleware:

     protected $routeMiddleware = [
         'package.middleware' => \Vendor\PackageName\Http\Middleware\PackageMiddleware::class,
     ];
     

Laravel 11/12-Specific Patterns

• Model Casting (Laravel 11+): If the package includes model traits or casts, use them in your Eloquent models:

  use Vendor\PackageName\Casts\PackageCast;
  
  class MyModel extends Model
  {
      protected $casts = [
          'attribute' => PackageCast::class,
      ];
  }
  

• Route Model Binding (Laravel 12): For custom route binding logic, extend the package's resolver:

  Route::bind('package', function ($value, $route) {
      return \Vendor\PackageName\Services\PackageService::resolve($value);
  });
  

Gotchas and Tips

Laravel 11/12 Compatibility Notes

1. Service Provider Auto-Discovery:

   • Laravel 11+ auto-discovers providers in config/app.php under providers. Ensure the package's provider is listed:

     'providers' => [
         // Laravel Framework Service Providers...
         Vendor\PackageName\PackageServiceProvider::class,
     ],
     

   • If using Laravel 12's new PackageManifest, verify the package is listed in bootstrap/app.php:

     return Application::configure(basePath: dirname(__DIR__))
         ->withRouting(
             web: __DIR__.'/routes/web.php',
             commands: __DIR__.'/routes/console.php',
             api: __DIR__.'/routes/api.php',
             channels: __DIR__.'/routes/channels.php',
         )
         ->withMiddleware(function ($middleware) {
             $middleware->alias('package.middleware', \Vendor\PackageName\Http\Middleware\PackageMiddleware::class);
         })
         ->create();
     

2. Facades and Aliases:

   • Laravel 11/12 facades are resolved via the Illuminate\Support\Facades\Facade class. If the package uses a facade, ensure its alias is defined in config/app.php:

     'aliases' => [
         'Package' => Vendor\PackageName\Facades\PackageFacade::class,
     ],
     

3. Blade Directives:

   • If the package includes Blade directives, register them in AppServiceProvider:

     public function boot()
     {
         \Vendor\PackageName\Blade::register();
     }
     

Common Pitfalls

1. Configuration Caching:

   • After publishing the config, clear the configuration cache:

     php artisan config:clear
     

   • In Laravel 12, use:

     php artisan optimize:clear
     

2. Dependency Injection:

   • If the package uses interfaces, ensure your bindings are correct. For Laravel 12, prefer constructor injection:

     public function __construct(private PackageContract $package) {}
     

3. Queue Workers:

   • If the package dispatches jobs, ensure your queue worker is running:

     php artisan queue:work
     

   • For Laravel 12, use the new queue connection syntax in .env:

     QUEUE_CONNECTION=database
     

4. Testing:

   • Mock the package's services in tests using Laravel's testing helpers:

     $this->mock(Vendor\PackageName\Contracts\PackageContract::class, function ($mock) {
         $mock->shouldReceive('doSomething')->andReturn('mocked');
     });
     

Extension Points

1. Customizing Behavior:

   • Override package logic by binding interfaces to your implementations in AppServiceProvider:

     $this->app->bind(
         Vendor\PackageName\Contracts\PackageContract::class,
         App\Services\CustomPackageService::class
     );
     

2. Adding Commands:

   • Extend the package's commands by creating a new command and registering it in AppServiceProvider:

     $this->commands([
         \App\Console\Commands\CustomPackageCommand::class,
     ]);
     

3. Event Customization:

   • Listen to the package's events and modify behavior:

     Event::listen(\Vendor\PackageName\Events\PackageEvent::class, function ($event) {
         // Custom logic
     });
     

4. Views and Assets:

   • Publish the package's views and assets:

     php artisan vendor:publish --tag=package-views
     php artisan vendor:publish --tag=package-assets
     

   • Override them in resources/views/vendor/package/ or public/vendor/package/.