Laravel Saved Filter Laravel Package

Technical Evaluation

Architecture fit. Unchanged: the package still follows the hasMigrations() publishable-stub pattern, and 1.10.0 is the first release to actually exercise the consequence of that choice — a third migration stub arriving out of band. That validates the design intent (schema under application review) and confirms the cost (a manual re-publish per schema-bearing release). The new timezone column is ordinary application-level configuration data sitting on the package's table; nothing about it strains the architecture. The builder-context change is a runtime contract change, not a structural one.

Integration feasibility. The upgrade is still two idempotent-bound commands. Critically, the 1.10.0 notes answer the largest open question from the 1.2.0 review: re-running vendor:publish --tag="saved-filter-migrations" delivers only the missing stub and skips the ones already present, so --force is not required for the upgrade path. That should still be verified on staging rather than taken on trust, but it converts the primary rollout risk from "unknown semantics" to "documented, testable behaviour."

Technical risk.

• Schema change. The timezone column is nullable and additive, and null is defined as "use the app timezone," so existing rows are correct without a backfill. This is the safest possible shape for a schema addition and is a materially lower risk than the 1.2.0 column additions.
• Stub drift — now realised. The predicted failure has occurred: a new stub exists that a 1.2.0 install will not have run. Teams that deferred the 1.2.0 publish (legitimate, since 1.0/1.1 → 1.2 was a no-op) will receive all three stubs on the next publish; the guards make that safe, but only if the guards are per-column and per-table as claimed.
• Deploy ordering is now hard. Before 1.10, a skipped migrate produced missing read paths. If application code begins writing timezone while the column is absent, it is an unknown-column SQL error at runtime — a louder but more disruptive failure. migrate must land in the same release, ahead of exercising the code path.
• Fail-open timezone validation. An unknown IANA name silently falls back to the app timezone. This trades an outage for a silent mis-send: a typo'd zone produces a report that fires at a plausible but wrong hour, with no error surfaced. This is the most consequential new risk in the release and the one most likely to generate hard-to-diagnose support tickets.
• Silent behaviour change on DST day. The double-send fix changes send counts on transition days. Teams that built dedupe or "already sent today" workarounds around the bug should audit and retire them; a leftover workaround keyed to the old duplicate pattern can suppress a legitimate send.
• Builder-context contract. Scheduled sends now always include saved_filter_id and report_id alongside tenant_id. Adding keys is normally backward compatible for consumers, but any strict deserialiser, exact-shape assertion, or templating that iterates context will see the change. report_id inside a signed unsubscribe route also warrants a scoping check — the signature must bind it to the recipient or tenant, not merely to the report.
• Unenumerated releases. This assessment is being made against 1.2.0; 1.3.0 through 1.9.x are not described in the data provided. There are eight minor versions of unaccounted-for changes between the reviewed baseline and 1.10.0.
• Timezone data dependency. Correct DST behaviour now depends on the tzdata in the runtime image being current. Container base images pinned months ago can carry stale rules for regions that have changed their transitions.

Key questions.

1. Confirm on staging that re-publishing adds only the new timezone stub, leaves the two published stubs byte-identical, and needs no --force.
2. What filename does the new stub publish under, and does it sort after the two migrations already applied in the host app?
3. Are the guards in the new stub hasColumn-scoped, and does the second stub's pagination/grouping guard remain per-column rather than per-table?
4. Is timezone validated at write time, or only at schedule execution? If only at execution, can an invalid value raise a warning, log event, or validation error rather than falling back silently?
5. Do existing reports need any backfill or UI/API surface to set a timezone, and is there a documented default for reports that should never have differed from the app timezone?
6. Does describeSchedule() render correctly for null and for an invalid zone, and is the "(America/Sao_Paulo)" suffix stable enough for anything downstream to parse?
7. What changed in 1.3.0–1.9.x? Provide the changelog before this upgrade is scheduled.
8. Are saved_filter_id and report_id additive-only in the context payload, and is the contract documented? Is saved_filter_id guaranteed tenant-scoped at the point it enters the builder?
9. Is the report_id in the signed unsubscribe route bound to the recipient as well as the report, and does it expire?
10. Does the new occurrence computation change send times for reports with null timezone, i.e. is there any missed or shifted send on the upgrade day itself?
11. Does down() on the new stub drop the column, and is that acceptable given older application code ignores it?
12. Are the supported Laravel and PHP ranges unchanged from 1.2.0?

Integration Approach

Stack fit. Standard artisan workflow, no new services, no configuration coupling beyond the existing publish tag. The one genuinely new infrastructure assumption is accurate timezone data in the runtime image; treat tzdata currency as a deployment prerequisite alongside the PHP version, and make the container timezone explicit now that it is the documented fallback.

Migration path.

• New installs (1.10.0+): publish the saved-filter-migrations tag and run migrate during first deploy — now three stubs, applied in declared order.
• 1.2.0 installs with stubs already published and run: re-publish the tag, review the single new stub, and migrate. The two existing stubs are skipped; one nullable column is added.
• 1.0/1.1 installs that never published: publishing now delivers all three stubs in one pass; guards skip the existing table and columns and add timezone. This is the cleanest way to finally bring the schema under application ownership.
• Data: no backfill required, but a one-off pass to set timezone on reports where the app timezone was only accidentally correct is worth considering, and is an application task, not a migration.
• Downgrades: rolling back to a pre-1.10 package is comparatively safe — older code does not read timezone, so a nullable, unread column is inert. The unresolved downgrade caveat remains 1.2 → 1.1, where package-loaded migrations re-enable against a published schema.

Compatibility. The schema change is backward compatible. The behaviour changes — DST occurrence computation and the expanded builder context — are the parts to test, not the DDL. Run the upgrade against a staging copy of a real 1.2-era schema rather than only against a fresh install.

Sequencing.

1. Obtain and read the 1.3.0–1.9.x changelog; the notes for 1.10.0 alone are insufficient to clear this upgrade.
2. Verify current tzdata in the base image and pin the app timezone deliberately.
3. Publish the stubs in a dedicated commit, review the new stub's DDL, and merge — not during a production deploy.
4. Run php artisan migrate --pretend in staging and diff the output against the applied 1.2-era schema.
5. Deploy migrate in the same release as the package bump, ahead of any code that writes timezone.
6. Audit consumers of the scheduled-send context — mail templates, queued job payloads, webhook handlers — for the two new keys, and confirm the unsubscribe route signature scope.
7. Search the codebase for DST or duplicate-send workarounds and retire them in the same release.
8. Post-deploy: exercise one report with a non-app timezone and one with null, and confirm the rendered schedule description.
9. Retain the standing "check for new migration stubs" item in the package-upgrade checklist — this release is the proof it is needed, not a reason to drop it.
10. In multi-tenant or database-per-tenant setups, confirm the new stub ships in the artefact and the migrate step fans out per tenant before any tenant writes timezone.

Operational Impact

Maintenance. Schema ownership stays with the application team, and the per-release stub check is now a demonstrated obligation rather than a theoretical one — budget it explicitly for every future release that touches migrations. Two new maintenance lines enter the runbook: timezone data currency in base images, and support for per-report timezone configuration now that the feature is user-facing.

Support. The DST fix removes a class of duplicate-send complaints, which is a net reduction in ticket volume. Against that, per-report timezones introduce a new question shape — "the report sent at the wrong hour" — whose most likely cause is a typo'd zone falling back silently. Without write-time validation or a surfaced warning, that ticket is expensive to diagnose. Onboarding documentation grows by one paragraph on timezone semantics plus the unchanged publish-then-migrate step.

Scaling. No impact at request time. Timezone resolution and occurrence computation happen once per schedule evaluation, which is negligible. The tzdata dependency scales with the fleet: every environment and every tenant's runtime image needs current rules, so it belongs in the base image build, not in per-application configuration.

Failure modes.

• Forgot to re-publish before upgrading: application code writes to a non-existent timezone column — a hard SQL failure at deploy or first use. This is the highest-probability failure of the release.
• Invalid IANA string: silent fallback to app timezone, wrong send hour, no error. Highest-difficulty failure to detect.
• Stale tzdata: DST transitions computed against outdated rules, producing offset-by-one-hour sends around transition dates.
• Leftover duplicate-send workaround: a legitimate send suppressed on a DST day, now that the underlying bug is fixed.
• Context-shape assumptions: a consumer asserting an exact payload, or templating that enumerates keys, breaks on the two added fields.
• Unscoped report_id: a signed unsubscribe link that binds only to the report could be replayed across recipients or tenants if the signature scope is too broad.
• Partial migration across tenants: some tenants without the timezone column, producing inconsistent behaviour that is hard to reproduce.
• Rollback with destructive down(): dropping a column that a partially deployed 1.10 application still writes.

Each is mitigated by a pre-deploy migrate --pretend diff, a post-deploy schema assertion, and a timezone round-trip check on one non-default report.

Ramp-up. Low. Teams already on the publishable-migration pattern need only re-run a command they have run before; the concept is familiar. New material is limited to timezone semantics and the tzdata prerequisite. Recommend adopting 1.10.0 rather than deferring: staying on 1.2.0 leaves the DST double-send defect in production, and the gap to 1.10.0 widens the unreviewed changelog with every further release.