Nova Contracts Laravel Package

Getting Started

This package assumes Laravel Nova is already installed. The last release is from 2022-03-26, so it likely targets Nova 3.x/4.x and Laravel 8/9 — confirm before installing into a newer stack.

1. Install:

   composer require zareismail/nova-contracts
   

2. Verify package discovery registered the provider. If not, add it to config/app.php.
3. Publish assets. The docs do not name the provider, so list publish tags rather than guessing:

   php artisan vendor:publish
   

   Then publish the nova-contracts config/migrations by tag or provider.
4. Review the migrations before running them. Check the contracts table columns (status, expiration, customer FK, contractable morph columns) and indexes, then php artisan migrate.
5. Register the package's Nova resource in app/Nova/NovaServiceProvider.php (or via Nova::resources([...])).
6. Configure the customer model and any contractable models in the published config. Read the config file — do not assume key names.
7. First use case: create a contract in Nova against a customer, set status and expiration, confirm the index filters/search work, and confirm the contract appears on the customer detail page if a relation is defined.

Where to look first: the service provider (register/boot), the published config, the migration, and the Nova resource class. Those four files tell you the entire integration surface.

Implementation Patterns

• Standard Nova CRUD. Keep contract management inside Nova. Use a Select/Badge for status, a date field for expiration, BelongsTo for customer, and a morph field for contractables. Add a HasMany/MorphMany on the customer resource so contracts show on the customer detail page.
• Enforce a morph map. If contracts attach to multiple models, call Relation::enforceMorphMap([...]) before production data exists. This stops the package from storing full class names in contractable_type and makes refactors safe.
• Wrap it behind your own interface. Create App\Contracts\ContractManager (or repository) with createFor(Model $owner, array $data), expireDue(), renew(Contract $c). Bind the package model behind it so Nova resources, jobs, and controllers never reference the vendor class directly. This is your exit path.
• Status/expiration workflow. Implement expiry as a scheduled command (Schedule::command('contracts:expire')->daily()), not just a Nova filter. Flip statuses and fire notifications from the wrapper. Add scopeActive and scopeExpiringSoon there too.
• Nova actions for lifecycle. Add RenewContract and TerminateContract actions to the resource (subclass it, don't edit vendor code). Keep the business logic in the wrapper; the action is just the UI trigger.
• Extend by subclassing. Subclass the package's Nova resource and override fields(), filters(), actions(). Register your subclass instead of the vendor resource in NovaServiceProvider.
• Permissions. Register a ContractPolicy. Nova uses policies for authorization, and without one non-super-admins will see nothing.
• Metrics. Add a value metric for "contracts expiring in 30 days" against the contract model — it is the highest-signal dashboard card for this domain.
• Seed statuses/types so Nova select fields are not empty in local and testing environments.

Gotchas and Tips

• Thin documentation, older release. Single tag from 2022, 2 stars. Pin ^1.0, compare the package's composer.json constraints against your Laravel/Nova versions, and run its tests plus your own before adopting. A stable tag is not a support commitment.
• Provider and publish tag names are undocumented. Use php artisan vendor:publish with no arguments to list tags, or read the provider's publishes() array. Do not guess the provider FQCN.
• Migration coupling. Review migrations before running, especially morph indexes and the customer FK. On large tables, split index creation or run in a maintenance window.
• Config caching. After publishing, run php artisan config:clear. If the config reads env at boot, test config:cache in staging — a failure there is a deployment blocker.
• Morph-map regressions. Changing morph aliases after data exists requires a data migration. Lock aliases down before production data.
• Expiration semantics. Decide date vs. datetime and timezone up front. Nova Date fields store dates; DateTime fields have timezone behavior. Store UTC, display in app timezone. Off-by-one expiry is the most common contract bug.
• Authorization invisibility. A Nova resource without a matching policy is invisible to non-super-admins. Check whether the package hard-codes canSee/canRun closures that override your policy.
• Customization surface. Prefer subclassing the Nova resource plus container binding over editing vendor files. If you fork, you own the maintenance burden forever.
• Octane and queues. Do not resolve the contract model as a long-lived singleton and hold it across requests; re-query in jobs to avoid stale status.
• No evident security disclosure process. Assign an internal owner, run composer audit on a schedule, and track advisories as a health signal.
• Rollback. Keep a feature flag around Nova resource registration. Verify the package's down() migrations before relying on them — they may drop tables.