Laravel Twig Laravel Package

Getting Started

• Check compatibility first. Version 3.0.0 targets Laravel 10.x and drops Laravel 6.x, 7.x, and 8.x. Confirm your app’s Laravel and PHP versions before requiring it; Laravel 10 requires PHP 8.1+.
• Where to look first:
  • composer.json for exact Laravel/PHP constraints and autoloaded service providers.
  • The package README/quickstart for install and publish commands.
  • The service provider and config file to understand what gets registered, merged, or published.
  • The changelog for any undocumented breaking changes beyond the headline notes.
• First use case: Install into a fresh Laravel 10 app, publish any config/migrations/assets if the package provides them, and run the README’s simplest example end-to-end. Then add one focused feature test around the package’s primary integration point before wiring it into existing code.

Implementation Patterns

• Use Laravel 10 conventions. Prefer constructor injection and typed properties over facades where practical; this makes package services easier to fake and test.
• Upgrade path from 2.x:
  • Bump the package constraint only after the app is on Laravel 9/10 and PHP 8.1+.
  • Run the full test suite and static analysis after upgrading.
  • Search for subclasses, overridden methods, and direct calls to package internals; these are the most likely upgrade breakpoints.
• Day-to-day integration:
  • Resolve package services from the container rather than instantiating them manually.
  • Keep package configuration in config/ and use environment variables for credentials or environment-specific values.
  • If the package dispatches events, exposes jobs, or supports middleware, wrap usage in your application’s own service/job layer so upgrades stay isolated.
  • Use package-provided fakes or test doubles in feature tests; otherwise bind a mock implementation in the container.
• Configuration workflow: Publish config once, commit the app-specific config, and avoid editing vendor files. After changing config, run php artisan config:clear locally and php artisan config:cache in deployment if your app uses config caching.
• Version pinning: For production, pin to a known 3.x release and upgrade deliberately; 3.0.0 includes compatibility drops and type-hint changes that can affect downstream code.

Gotchas and Tips

• Breaking compatibility: Laravel 6–8 are no longer supported. Apps on those versions must stay on the previous major line or upgrade Laravel first.
• Type-hints can break subclasses. If you extended package classes or implemented package interfaces, method signatures may now require matching parameter and return types. Run PHPStan/Psalm and your test suite to catch fatal signature mismatches.
• Removed “unused” code may still be used by your app. Treat undocumented public methods or properties as potentially removed. Search your codebase for direct references before upgrading.
• Laravel 10 / PHP 8.1 requirement: CI images, Dockerfiles, and deployment runtimes must be updated before the package can install.
• Config caching quirks: If the package merges config, verify defaults after config:cache. Clear cached config when debugging “missing” package settings.
• Service provider and alias checks: If a facade or alias stops resolving after upgrade, confirm the provider is still auto-discovered or manually registered in config/app.php.
• Debugging approach: Start with composer why-not for dependency conflicts, then check provider registration, published config, and cached bootstrap files (bootstrap/cache).
• Extension points: Prefer binding package interfaces in your own service provider, overriding published config, and using events/hooks over modifying vendor code. This keeps future major upgrades manageable.