zarbinco/laravel-workdays
zarbinco/laravel-workdays is a Laravel package for working-day calculations. Add or subtract business days, check whether a date is a workday, and account for weekends and holidays—useful for deadlines, SLAs, and scheduling.
Architecture fit. This is a Laravel-native package that owns a bounded domain: working-time/calendar definitions, business-hours arithmetic, and SLA/reverse-scheduling calculations. v1.0.0 consolidates what was previously a multi-mode design (Chain/Hybrid storage) into a single unified definition model with exactly two exclusive sources — Config (file-based) and Database (revision-based, atomically published). That is a genuine simplification of the mental model: one schema, one arithmetic engine, one publication path. For teams that already treat business calendars as configuration rather than code, the Database source with revision-based storage and atomic publication is the important architectural addition — it turns calendar changes into a deployable, auditable, revertible artifact instead of a code change.
Integration feasibility. The package appears to be a library dependency rather than an infrastructure component: no queues, no daemons, no external services implied. Integration is therefore bounded to (a) publishing/authoring a definition, (b) calling the calculation API from application code, and (c) persisting definitions if the Database source is selected. The import/export and restore capability lowers the barrier for teams migrating from the Config source or seeding environments. Persian/Iran calendar support is first-class and now better documented, which matters if any operating region is Iran — that is usually the hardest thing to retrofit into a scheduling library later.
Technical risk. Concentrated in the breaking change, not the feature work:
Regression, database, and integration test coverage is claimed, which is the main mitigating signal. The unstated risk is behavioral equivalence for edge cases (DST transitions, month/leap boundaries in the Persian calendar, inclusive vs. exclusive end times) that the tests may or may not exercise against your historical data.
Key questions. Is there a documented migration path from the legacy config structure, or only import/export? What replaces Chain/Hybrid resolution for layered/default-plus-override use cases — application composition, or a roadmap feature? Do the standardized boundary semantics change results for existing definitions, and is there a compatibility flag? How is "atomic publication" implemented and does it require specific DB engine/transaction support? What is the support policy for 0.x, and is 1.0.0 intended as the long-term stable line? Are the Persian RTL documentation fixes cosmetic or do they signal prior doc inaccuracy on calendar semantics?
Stack fit. Standard Laravel package shape: Composer dependency, publishable config, optional migrations for the Database source, service-provider registration. Fits monoliths and API services alike. The Database source makes it a natural fit for multi-tenant applications if definitions can be scoped per tenant — worth confirming, since exclusivity between Config and Database is a global setting in the described model, not per-tenant.
Migration path. Sequence conservatively:
Compatibility. Assume no backward compatibility at the API/config level. Two independent axes need verification: PHP/Laravel version support (unstated) and database engine support for the revision/atomic-publication feature — transactional DDL and locking behavior differ meaningfully between MySQL, PostgreSQL, and SQLite. If the test matrix runs only on one engine, treat others as unvalidated.
Sequencing. Land the upgrade as an isolated change with no other dependency work in the same window. If the application depends on Chain/Hybrid resolution, build and test the replacement composition layer before upgrading, so the upgrade does not become the moment that behavior disappears. Defer the Database source adoption to a second phase — first establish parity on Config, then introduce revisions and atomic publication as a deliberate operational capability with its own runbook.
Maintenance. A 1.0.0 with a documented breaking change, rewritten bilingual docs, and a claimed regression/DB/integration test suite is a healthier maintenance posture than a 0.x line, but it is also a hard reset: expect a period where the ecosystem (forks, blog answers, community snippets) describes the old structure. Budget for the team to be the source of truth internally rather than relying on search results.
Support. Key-man risk if the package has a small maintainer base and the breaking change reduces the pool of people who have run it in production. Ask about release cadence, security-response expectations, and whether 1.0.0 starts a semver commitment. Persian-language documentation as a first-class artifact is a positive signal of an engaged user base, but also suggests the primary maintainer/user community may be regionally concentrated — relevant for timezone-of-support, not capability.
Scaling. Calculation-heavy usage (per-request SLA evaluation, reverse scheduling over long horizons) should be profiled; microsecond-precision arithmetic is not free, and reverse scheduling can be algorithmically expensive. The Database source shifts load onto your database: revision reads should be cached, and atomic publication implies write locking that must be kept off the hot path. Cache definitions and invalidate on publish.
Failure modes. (1) Silent arithmetic drift — stored SLA deadlines computed pre-upgrade no longer match recomputation, causing spurious breach/at-breach states. (2) Partial publication — a revision published mid-transaction leaves readers on a mixed definition; verify atomicity actually holds under concurrent reads. (3) Timezone/DST edge cases where a boundary falls inside a transition, especially combined with Persian calendar month boundaries. (4) Config/Database exclusivity misconfiguration causing the wrong source to win silently. (5) Import/restore overwriting live revisions without a dry-run.
Ramp-up. Low-to-moderate for developers using the calculation API; moderate for whoever owns definitions, because the unified schema and revision/publication model are new concepts requiring an operational runbook (who publishes, how to roll back, how to dry-run an import). Rewritten English docs shorten the curve; run one engineer through an end-to-end publish-and-restore exercise before the team depends on it, and treat the output of that exercise as the internal onboarding doc.
How can I help you explore Laravel packages today?