Laravel Todo Laravel Package

Technical Evaluation

Architecture fit

• Small, single-purpose package that slots into the standard Laravel service-provider / facade / trait / migration idiom. Low architectural surface area: one polymorphic table, one trait, one facade, one config file.
• Polymorphic todos table (todos + creator morphs) is a good fit for a platform where "work items" attach to heterogeneous domain entities (User, Project, Team). Avoids N per-model join tables.
• Trait + facade duality is pragmatic: $model->todos() for relationship-oriented code, Todo::for($model) for query-oriented code. Both are conventional Laravel ergonomics and reduce onboarding cost.
• Primary structural gap: no domain events in v1.0.0 (TodoCreated, TodoCompleted, TodoCancelled are explicitly "coming soon"). Without them, any decoupled integration (notifications, webhooks, analytics, search indexing, audit log) must poll or be hard-wired into application code — which inverts the dependency direction and is the single biggest architectural constraint on this release.
• creator tracking is present but there is no assignee/owner relation. Todos belong to the model they're attached to and record who created them; there is no first-class "assigned to a different user" concept. Confirm whether that gap is acceptable or whether creator will be overloaded.

Integration feasibility

• Installation is a standard three-step Composer + publish + migrate flow, with config and migrations published separately. Straightforward for any team already on Laravel.
• Migration publication (rather than loading migrations from the package) means the host application owns the schema. That's good for customization, but it also means upstream schema changes in future versions will not auto-apply and will need manual diffing on upgrade.
• The Todo facade alias is a collision risk in a codebase that already has a Todo model, facade, or service — very likely in a task-adjacent domain. Verify alias registration and plan to alias/rename on import.
• Facade usage in controllers/spread across the codebase creates tight coupling to the package. Feasible, but wrap it.

Technical risk

• Medium-low overall. The package is narrow, and "Pest + Real Laravel Application" testing is a credible quality signal for a v1.0.0.
• Bus factor 1. Single named maintainer, no evidence of a governance model, no stated support commitment, no LTS/backport policy. This is the dominant risk, not the code.
• Version compatibility not stated in the release notes — no Laravel or PHP version matrix. Must be verified before adoption.
• No todos:prune yet and no stated retention policy: the table grows unbounded, and deleted parent models may leave orphaned polymorphic rows unless foreign-key/morph cleanup exists. Confirm whether nullableMorphs + cascadeOnDelete is actually enforceable for polymorphic columns (it generally isn't).
• Enum-as-string status/priority with no documented enum class or validation layer means invalid states are prevented only by convention; scopes will silently return nothing for typos.
• No documented authorization story. Row-level access control (who can complete whose todo?) is entirely the host app's responsibility and must be built.

Key questions

1. What is the supported Laravel/PHP version matrix, and is semver guaranteed post-1.0?
2. Is there a due-date/reminder column backing overdue() and dueToday(), and what is the timezone behaviour?
3. What is the committed timeline for events and the prune command? Are they v1.1 or v2.0?
4. Is there any assignee concept on the roadmap, or is creator intended to serve both roles?
5. What happens to todos when the parent model is deleted — cascade, orphan, or soft delete?
6. Is morphMap respected for creator and todos relations (string vs. class storage)?
7. Is there guidance for multi-tenant scoping, or is that fully delegated to the host app?
8. Any policy/authorization hooks, or is everything expected to live in app-level Policies?
9. Is there a changelog, security policy, or issue-response commitment?

Integration Approach

Stack fit

• Native fit for a conventional Laravel app (Eloquent, service providers, facades, traits, migrations, config publishing). No new runtime, no queue worker, no external service, no schema beyond one table.
• Fits monoliths and modular monoliths well. In a multi-tenant SaaS, tenancy scoping is not provided and must be layered on via a global scope keyed to the tenant — plan for it explicitly rather than retrofitting.
• Poor fit only where a richer work-management model already exists (assignments, comments, attachments, subtasks, ordering). This package is deliberately minimal; treat it as a primitive, not a task-management system.

Migration path

• Greenfield: publish migrations, run, add HasTodos to the first model, ship.
• Brownfield (existing tasks/todos table): treat as a data migration project.
  • Map existing status values onto pending | in_progress | completed | cancelled and priority onto low | medium | high; document lossy mappings (e.g. blocked → ?).
  • Backfill polymorphic todos rows from the legacy table, resolving todos_type/todos_id and creator_type/creator_id.
  • Dual-write or shadow-read for one release cycle, then cut over, then drop the legacy table. Do not attempt a hard cutover on a table with active read paths.
• If a legacy table exists with assignee_id, decide now whether to persist that in a side table or drop the concept — the package will not store it.

Compatibility

• Pin the Composer constraint to ^1.0 and commit the lockfile; do not float.
• Verify Laravel/PHP support against the host app's matrix before any spike.
• Audit for existing Todo symbols (class, facade, alias, Livewire component, JS namespace) and resolve collisions up front.
• Confirm morphMap behaviour if the app uses morph maps — mismatched storage between class names and aliases is a common and painful source of silent empty results.
• Check whether published migrations are timestamp-safe relative to existing migrations and whether the users/models table assumptions hold.

Sequencing

1. Spike (days): install in a throwaway branch, add HasTodos to one low-risk model, exercise every scope, verify config publishing and facade alias behaviour.
2. Abstraction layer: wrap facade calls behind an app-owned service/repository (e.g. TodoService) so the package is swappable and events can be synthesized manually until upstream events land.
3. Authorization: build Policies/Gates for create/complete/cancel before any UI exposure.
4. Pilot: one domain (e.g. internal Project todos), one team, one release cycle.
5. Backfill + cutover for any legacy data, with dual-write.
6. Broaden trait adoption model by model; each addition is an independent, reversible change.
7. Re-evaluate on v1.1 — if events and prune ship, remove the manual event-synthesis shims and add the scheduled prune.

Operational Impact

Maintenance

• Low ongoing effort for the host team: one migration, one config file, one trait per model. Upgrades are Composer bumps plus manual migration diffing on minor releases.
• The real maintenance exposure is upstream: single maintainer, no stated release cadence, no LTS. Mitigations: pin versions, keep the abstraction layer thin enough that forking or vendoring is a day's work, monitor the repo for responsiveness.
• Published (not package-loaded) migrations mean the host team is permanently responsible for reconciling schema drift. Assign that to a named owner.

Support

• Community-only: README, GitHub issues. No commercial support, no SLA. Acceptable for internal tooling; a consideration if todos become user-facing in a revenue path.
• Documentation depth is unknown beyond the README; assume scopes, status transitions, and edge cases will require reading source.
• The "coming soon" list is a de facto roadmap with no dates — do not plan dependent work against it.

Scaling

• Query patterns are simple but the polymorphic index is the pressure point: ensure a composite index on (todos_type, todos_id, status) and (todos_type, todos_id, due_at) to keep pending()/overdue() selective as the table grows.
• overdue() and dueToday() are date-range scans — fine with an index, but dueToday() is timezone-sensitive and should be evaluated per-request in the user's timezone, not the app default.
• Eager-load creator (with('creator')) in list views; the polymorphic creator relation is an easy N+1.
• No prune command in v1.0.0 means completed/cancelled rows accumulate indefinitely. Until it ships, add an application-level scheduled job that hard-deletes or archives terminal-state rows older than a defined retention window.
• Horizontal scaling is trivially fine — no caches, no locks, no queues introduced by the package.

Failure modes

• Silent scope no-ops from status/priority typos or morph-map mismatch — returns empty sets rather than errors. Add validation/enum casting at the boundary and cover with tests.
• Orphaned todos when a parent model is deleted (polymorphic FKs generally don't cascade). Mitigate with model deleting observers or a periodic reconciliation job.
• No events → missed side effects. Without TodoCompleted, notifications, webhooks, and analytics silently don't fire. Until events ship, dispatch application-level events from the service wrapper for every state transition.
• Facade alias collision breaking an unrelated Todo symbol at autoload/boot time — caught in the spike, not in production.
• Config drift between environments if the config file is published and then edited; treat it as code and review changes.
• Unbounded table growth degrading list queries over 12–18 months; mitigated by the retention job above.
• Upstream abandonment — mitigated by pinning and the abstraction layer.

Ramp-up

• Very low for any Laravel developer: the API is four verbs (create, completeTodo, scopes, for()), and the mental model is one polymorphic table. Estimate under half a day to first productive use.
• The ramp-up cost is not the package — it's the undocumented host-side work: authorization policies, tenancy scoping, event synthesis, retention job, and creator eager-loading conventions. Budget that as a small, explicit workstream in the first sprint rather than discovering it in review.
• Recommend a short internal README addendum documenting the wrapper service, the retention job, and the "always go through the service, never the facade directly" rule — that single convention preserves the option to swap or fork the package later.