Markable Laravel Package

Getting Started

• Start with the package README and CHANGELOG, then inspect the scope implementation and tests. The v1.0.0 notes specifically mention a fixed “wrong scope query call,” so verify how the package exposes Eloquent scopes before relying on them.
• Install using Composer versioning now that the package is tagged:

composer require vendor/package:^1.0

• If the package was previously installed from dev-main or an untagged branch, switch the constraint to ^1.0, run composer update vendor/package --with-dependencies, and commit composer.lock.
• First day-to-day use case: apply the package’s model scope to an Eloquent query instead of hand-writing the equivalent where clauses, then inspect the generated SQL and result set.

$results = Model::query()
    ->packageScope()
    ->get();

• Where to look first:
  • Package service provider and auto-discovery.
  • Scope/query-builder classes.
  • Published config, if any.
  • Tests covering scope behavior and SQL generation.
  • Laravel version constraints in composer.json.

Implementation Patterns

• Use the package scope as the canonical query path for the behavior it encapsulates. Avoid duplicating the same filters manually in controllers or repositories.
• Compose package scopes with existing Eloquent constraints:

$query = Order::query()
    ->packageScope()
    ->where('status', 'paid')
    ->latest();

$orders = $query->paginate(25);

• Wrap package-backed queries in repository or query-object layers when the scope is used in multiple places. This keeps application code stable if the package’s API changes.
• For reusable reporting or dashboard filters, build named query methods around the package scope rather than scattering scope calls across controllers.
• Add feature/integration tests that assert both result correctness and generated SQL where practical:

$query = Order::query()->packageScope();

$this->assertStringContainsString('expected_column', $query->toSql());

• In Laravel applications using route model binding or API resources, apply the scope before pagination, counts, or aggregate queries so all downstream results share the same filtering behavior.
• If the package publishes config, publish it only when defaults need changing:

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

• After upgrading to v1.0.0, run the package’s tests plus your own scope-related tests. The scope fix may change query results, so verify any dashboards, exports, or APIs that depend on the affected scope.

Gotchas and Tips

• The v1.0.0 fix for a “wrong scope query call” is the highest-risk change. Audit every usage of the package’s scopes and compare before/after results where possible.
• Composer versioning is now available, so prefer a stable constraint such as ^1.0 rather than dev-main. If you previously required an untagged branch, update your composer.json constraint deliberately.
• Clear Laravel caches after upgrading:

php artisan config:clear
php artisan cache:clear
composer dump-autoload

• Debug scopes with toSql(), dd(), or Laravel’s query log. Scope methods can be easy to miss in long query chains.
• Watch for scope name collisions with existing local scopes or global scopes on the model. Rename application-level scopes if needed.
• Do not mix manual where clauses with the package scope unless you understand the SQL semantics; duplicate filtering can produce confusing results.
• Check Laravel and PHP version constraints in the package’s composer.json before upgrading. v1.0.0 may be the first properly versioned release, but it still needs to match your application’s runtime.
• If the package documents extension points, prefer those over subclassing internal classes. The release notes do not advertise new extension APIs, so treat internals as private unless documented.
• Commit composer.lock after upgrading and verify CI uses the same dependency resolution. This is especially important now that Composer versioning has been added.