Eloquent Criteria Laravel Package

Getting Started

This is the first assessment for this package; v2.0.0 is the baseline to evaluate against.

1. Confirm framework compatibility before upgrading. v2.0.0 removes Laravel 9 support, so the package now targets Laravel 10+ (verify the exact upper bound in its composer.json). On a Laravel 9 application, composer require/composer update will fail or resolve to the older 1.x line.
2. Check the package constraints first. Run:

   composer show <vendor>/<package> --all
   composer why-not <vendor>/<package> "^2.0"
   

   Look at the package’s composer.json for illuminate/*, PHP, and extension requirements.
3. Upgrade in a branch. Update the constraint to ^2.0, run composer update <vendor>/<package> -W, then execute the application test suite before touching production configuration.
4. First use case. Install the package, publish any config/migrations if the package provides them, set the required environment variables, and resolve the package’s main service through constructor injection or its documented facade in a controller, job, or service class.
5. Where to look first: the package README, UPGRADE.md/CHANGELOG.md, the service provider, published config file, and any Laravel-specific integration tests shipped by the package.

Implementation Patterns

• Pin the major version in applications. Use ^2.0 in composer.json and commit composer.lock. Because v2.0.0 also updates composer dependencies, avoid broad * constraints that could silently pull incompatible transitive packages.
• Resolve through the container. Prefer constructor injection of the package’s service/interface over facades or app() calls in domain code. This keeps tests fast and makes package replacement or decoration easier.
• Keep configuration in config files. Publish the package config and reference it with config('package.key'). Do not call env() directly outside config files, especially if you use php artisan config:cache.
• Use the package at the boundaries. Typical integration points are controllers, form requests, jobs, console commands, and event listeners. Keep package-specific calls out of models and pure domain services where possible.
• Wrap side effects in transactions or jobs. If the package writes to the database, dispatches events, or calls external services, invoke it inside a transaction or queued job and make the operation idempotent.
• Test against supported Laravel versions. Add a CI matrix for the Laravel versions the package supports in v2. Run the application’s feature tests plus a small integration test that resolves the package service and exercises one real workflow.
• Upgrade workflow:
  1. Branch from the current release.
  2. Bump the package constraint to ^2.0.
  3. Run composer update <vendor>/<package> -W.
  4. Run php artisan config:clear, php artisan cache:clear, and the test suite.
  5. Deploy to staging and restart queue workers.
• Use package extension points rather than vendor edits. Publish config, bind interfaces in a service provider, or use documented macros/hooks. Never modify files under vendor/.

Gotchas and Tips

• Laravel 9 is a hard break. Do not work around the constraint with --ignore-platform-reqs or by editing composer.json to allow Laravel 9. Either stay on the package’s 1.x line or upgrade the application to Laravel 10+ first.
• “Updated composer packages” can raise the effective PHP or extension requirement. Run composer diagnose and check composer why-not if resolution fails. Update transitive dependencies with -W rather than forcing individual packages.
• Clear caches after upgrading. Run:

  php artisan config:clear
  php artisan cache:clear
  php artisan route:clear
  php artisan view:clear
  

  Then rebuild production caches with config:cache and route:cache.
• Restart queue workers. Long-running workers can hold old package code or stale config in memory. Use php artisan queue:restart after deployment.
• Config caching hides env() calls. If behaviour changes only in production, check whether the package reads environment variables outside a config file. Publish and edit the config instead.
• Watch transitive dependency conflicts. v2.0.0’s dependency updates may conflict with older packages in the application. Use composer why-not <vendor>/<package> "^2.0" to identify the blocker before changing unrelated dependencies.
• Test the lowest and highest supported Laravel versions. A passing suite on the newest Laravel does not guarantee compatibility with the oldest version allowed by the package’s constraints.
• Read the changelog for upcoming deprecations. Since v2.0.0 is a major release, expect future 2.x minors to deprecate APIs before a 3.0 removal. Avoid relying on undocumented internals.
• Debugging checklist: composer show <vendor>/<package>, composer why-not, composer diagnose, application logs, and the package’s own test suite. If the package provides a facade, confirm it is registered in config/app.php only for legacy Laravel setups; modern Laravel uses package discovery.
• Extension point to prefer: publish the config and bind the package’s contracts/interfaces in your own service provider. This keeps upgrades to 2.x minor releases low-risk.