Getting Started

Install via Composer using the package name from the updated README: composer require vendor/package. The 0.3 README is the first place to check for new install steps, config publishing, and migration notes.
Publish any config and run migrations if the package provides them. Re-publish config after upgrading to pick up new options.
First use case: exercise a method that now returns a Model instead of bool. For example, call the method, inspect the returned model, and chain Eloquent operations directly:
```
$record = $package->someMethod($data);
if ($record !== null) {
    $record->update(['processed_at' => now()]);
}
```
Validate the addOnlyExpired fix with a small test: create one expired and one active record, call addOnlyExpired, and assert only the expired record is added.

Implementation Patterns

Model return values: Methods that previously returned bool now return a Model instance or null on failure. Use explicit null checks ($model = $package->method(); if ($model === null) { ... }) and inspect $model->wasRecentlyCreated or $model->exists when you need to distinguish creation from an existing record.
Chaining: Because you receive a model, you can immediately load relationships, update attributes, or dispatch events:
```
$package->addSomething($data)->load('relation');
```
Expiration workflows: Use addOnlyExpired to avoid duplicating active entries. Pair it with scheduled commands or queued jobs that periodically refresh expired items. For example, a nightly job can call addOnlyExpired for each user or resource.
Integration: Wrap calls in database transactions if the package writes to the database. Use dependency injection or the documented facade. For testing, use the package’s fake or mock the underlying model resolution.
New methods: After upgrading, scan the updated README for newly added methods. Adopt them where they simplify existing code—especially bulk operations or scoped queries that previously required manual loops.

Breaking change—return types: The change from bool to Model is breaking. Audit every call site. Replace strict checks like if ($result === true) with if ($result !== null) or if ($result). Update return type hints and docblocks on any wrapper methods. Code that returned the old bool directly from a function will now fail type checks.
addOnlyExpired bug fix: If you had workarounds for the old bug, remove them. Test edge cases: expired vs. non-expired records, timezone handling, and concurrent calls. The fix may change which records are added, so verify existing data assumptions.
Null vs. false: A Model return can be null on failure. Avoid treating null as false in strict comparisons. Use is_null() or !== null for clarity.
README is updated: The new methods and return type changes should be documented there. Check for migration notes, changelog entries, and updated examples. If the README is sparse, inspect the package source for method signatures.
Debugging: Enable query logging or use dd($model) on the returned model to inspect attributes and existence state. If a method unexpectedly returns null, check the package’s logging or exception handling.
Extension points: Prefer the package’s events, custom model resolution, or config options over modifying vendor code. After upgrading, merge config changes carefully—don’t overwrite your customizations.