Period Bundle Laravel Package

Getting Started

To begin using this package in Laravel, ensure your project meets the updated minimum requirements:

• PHP 8.0+ (PHP 7.x is no longer supported)
• Symfony components 5.4+ (check via composer show symfony/*)

Install via Composer:

composer require vendor/package-name

For Laravel-specific setup, consult the package’s config/ files (if included) or run:

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

First use case: Verify compatibility by testing a basic feature (e.g., a middleware, service, or facade) in a fresh Laravel 9/10 project.

Implementation Patterns

Core Workflows

1. Dependency Injection: Bind services via the AppServiceProvider or package’s service provider:

   $this->app->bind('custom.service', function ($app) {
       return new \Vendor\PackageName\Services\CustomService();
   });
   

2. Middleware Integration: Register middleware in app/Http/Kernel.php:

   protected $middleware = [
       \Vendor\PackageName\Http\Middleware\ExampleMiddleware::class,
   ];
   

3. Configuration: Publish and merge config files:

   php artisan vendor:publish --tag="package-config"
   

   Override defaults in config/package-name.php.

4. Event Listeners: Subscribe to package events in EventServiceProvider:

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

Laravel-Specific Tips

• Use Laravel’s container to resolve package dependencies:

  $service = app(\Vendor\PackageName\Contracts\ServiceInterface::class);
  

• Leverage Laravel’s helpers (e.g., route(), view(), cache()) within package code for consistency.

Gotchas and Tips

Breaking Changes (v2.0.0)

• PHP 7.x Dropped: Upgrade to PHP 8.0+ to avoid runtime errors (e.g., TypeError for typed properties).
• Symfony 5.4+ Required: Update dependencies if using older Symfony components (e.g., symfony/http-foundation).

Debugging

1. Dependency Conflicts: Run composer why vendor/package-name to diagnose version mismatches. Resolve with composer update vendor/package-name --with-dependencies.

2. Configuration Overrides: Clear cached config after publishing:

   php artisan config:clear
   

3. Middleware/Service Issues: Check for ClassNotFoundException if autoloading fails. Run:

   composer dump-autoload
   

Extension Points

• Customize Services: Extend base classes (e.g., extends \Vendor\PackageName\BaseService).
• Hooks/Events: Listen to package events (e.g., ExampleEvent) to inject custom logic.
• Views/Blade: Override package views in resources/views/vendor/package-name/.

Performance

• Caching: Use Laravel’s cache drivers (e.g., cache()->remember()) for repeated package operations.
• Queue Jobs: Offload heavy tasks to Laravel queues if the package supports job dispatching.