Maintenance Laravel Laravel Package

Getting Started

Start by reading the package README, then inspect the published config, migrations, and src/ domain folders for Assets, Work Orders, Preventative Maintenance, Priorities, and Commercial boundaries. In a Laravel app:

1. Require the package with Composer.
2. Publish config and migrations.
3. Run migrations.
4. Seed or create maintenance priorities.
5. Create an asset, open a work order, add a comment, and attach a preventative maintenance schedule.

The first practical use case is an asset-centric maintenance workflow: register an asset, create a work order against it, assign a priority, add comments during execution, and configure a recurring preventative maintenance schedule that generates future work.

v0.15.0 is still early (0.x), so treat the README and package source as the source of truth over assumptions about stable APIs.

Implementation Patterns

Use the package’s domain actions and boundaries rather than writing directly against tables. The recent releases emphasize presentation action boundaries, mutation boundaries, and query boundaries, which suggests the package expects reads/presentation and writes/mutations to go through distinct entry points.

Common day-to-day patterns:

• Asset lifecycle: Create and update assets through package actions, then use assets as the anchor for work orders and preventative schedules.
• Work orders: Create work orders through mutation actions, use presentation/query APIs for lists and detail views, and keep status transitions inside package lifecycle methods.
• Comments: Add work order comments through the package’s comment API or relation rather than inserting directly. Authorize comment creation against the work order and current user.
• Priorities: Treat maintenance priorities as reference data. Seed them during deployment or provide an admin UI, then reference priority IDs/keys from work order creation.
• Preventative maintenance: Use the restored completion lifecycle to close preventative work correctly. When a preventative work order completes, verify whether the package advances the next due date or creates the next occurrence.
• Recurring scheduling: Run the package’s scheduler/job entry points from Laravel’s scheduler. Keep schedule generation idempotent in your integration tests.
• Operational queries: Use package query boundaries/scopes for dashboards and operational lists instead of hand-rolled Eloquent queries, especially for open, overdue, completed, and scheduled work.
• Integration: Wrap multi-step writes in database transactions, dispatch domain events or jobs after commits, and bind package contracts/interfaces if the package exposes them.

For UI integration, keep presentation concerns separate from mutation actions: load work order lists through package query/presentation APIs, and submit changes only through the documented mutation paths.

Gotchas and Tips

• 0.x instability: v0.15.0 includes multiple release and boundary changes. Pin the version in composer.json and review changelogs before upgrading.
• Do not bypass boundaries: Direct model updates can skip lifecycle rules, validation, events, and comment/priority handling. Prefer package actions even when Eloquent makes direct writes tempting.
• Lifecycle correctness: Preventative maintenance completion can affect recurring schedules. Test completion, cancellation, and reopening paths explicitly.
• Recurring duplication: Scheduler jobs and manual runs can overlap. Use locking, withoutOverlapping(), and idempotency checks around recurring work generation.
• Reference data: Priorities and similar lookup data may be required before work orders can be created. Add seeding and deployment steps.
• Migrations/config: Publish and review migrations/config before running in existing apps. Check for table name collisions and config keys that control model/table names.
• Authorization: Comments and work order mutations need policies or gates in the host app. The package may provide domain behavior but not your full authorization model.
• Query scope surprises: Operational query boundaries may intentionally exclude closed, cancelled, soft-deleted, or future-scheduled records. Verify scope behavior in tests before using them for dashboards.
• Debugging: Start with package actions, events, and query classes rather than raw SQL. Log lifecycle transitions and scheduler runs when diagnosing missing work orders or comments.
• Extension points: Prefer published config, package events, custom actions/jobs, and model substitution only where documented. Avoid subclassing internal classes unless the package explicitly supports it.