Flysystem Onedrive Laravel Package

Technical Evaluation

Architecture fit

• The package is a Flysystem v3 adapter that speaks to OneDrive/SharePoint document libraries through Microsoft Graph. Because Laravel's Storage facade is a thin wrapper over Flysystem, the adapter plugs in without touching application code: register a custom driver with Storage::extend('onedrive', ...) and the disk becomes usable via Storage::disk('onedrive'), exactly like local or s3.
• This makes it an integration-shaped dependency, not a framework-shaped one. No Laravel service provider is shipped (0 dependents, no Laravel-specific glue), so the TPM must budget for a thin internal package: one service provider, one config block in config/filesystems.php, and secret management.
• Fit is strongest where data already lives in Microsoft 365: contract/HR document vaults, tenant-scoped user uploads, exports that business users expect to see in OneDrive/SharePoint, or environments where a separate S3 bucket is blocked by procurement or data-residency policy.
• Fit is weak as a general-purpose primary storage disk. OneDrive is a sync-and-collaboration product, not an object store; latency, throttling, and path semantics differ materially from S3.
• v2.0.8 does not change this picture. It is a patch release with no architectural movement: one adapter file change, CI housekeeping, and a framework-compatibility bump.

Integration feasibility

• Technically feasible in days, not weeks, for a read/write/list/delete use case. Prerequisites are mostly Azure AD administration, not code: app registration, client secret or certificate, API permissions (Files.ReadWrite.All application-level or Files.ReadWrite delegated), and tenant admin consent.
• Real constraints surface quickly: files above the Graph simple-upload ceiling (~250 MB) require chunked upload sessions; copies are asynchronous (202 + monitor URL); directory listings are paginated via @odata.nextLink; paths are case-insensitive, length-capped, and reject reserved characters (* : < > ? / \ | # %).
• Verification burden is on us: still ~50 stars and zero Packagist dependents, so no meaningful production corpus to lean on. Expect to write our own integration tests against a real tenant — Graph has no faithful local emulator.
• The v2.0.8 adapter edit (PR #24, new contributor) is shipped with no description — the changelog entry is a raw file name, not a behavioural statement. Treat it as an unverified behaviour change in the adapter's core file and diff it before pinning.

Technical risk

• Maintainer/bus factor (high, marginally improved): still effectively a single-maintainer project with low adoption, but v2.0.8 shows two new external contributors and an automated Laravel Shift compat PR — the first evidence of pull-request throughput beyond the maintainer. That is a positive signal, not a structural fix; we still assume fork ownership on a known timeline.
• API drift (medium, slightly reduced): Microsoft evolves Graph continuously; throttling behaviour, permission models, and upload session semantics change. v2.0.8 demonstrates the project is still responsive to ecosystem drift (CI PHP matrix + Laravel 13), which shortens the expected lag — but a framework-compat bump is not the same as a Graph-compat bump.
• Correctness gaps (medium): Flysystem contract surface — visibility, MIME detection, checksums, copy/move atomicity, exception mapping — is unlikely to be fully honoured. Silent partial successes (an upload that 90% completes) are the dangerous class of bug. The undocumented adapter change in this release means our existing behavioural test suite must be re-run, not assumed.
• Auth/token lifecycle (medium): token caching and refresh must be correct or we generate auth storms and 429s under load.
• Vendor coupling (low-medium): deep M365 dependency for what may be a peripheral feature; acceptable if M365 is already the system of record.
• Upgrade opacity (low-medium, new): the release is a patch version but touches the adapter's main file with a non-descriptive commit message. Semver here is a weak contract; we should read diffs, not changelogs.

Key questions

1. Application-level or delegated permissions — and can we obtain tenant-wide admin consent, or is per-user consent in scope?
2. Is the target a personal OneDrive, a SharePoint document library, or a shared drive, and is the drive ID stable across environments?
3. Does the adapter support upload sessions for large files, and does it stream downloads or buffer them in memory?
4. How are Graph errors (401/403/423/429/507) translated into Flysystem exceptions, and are 429 Retry-After values honoured?
5. Does it implement url(), temporaryUrl(), visibility, and mimeType — or throw NotSupportedException? Which of these does our feature actually need?
6. What exactly changed in OneDriveAdapter.php in v2.0.8 (PR #24)? Is it a bug fix, a Graph payload change, or a behaviour change we depend on — and is it covered by any test?
7. Is there a supported Flysystem major/Laravel version matrix? v2.0.8 advertises Laravel 13.x compatibility; confirm it holds for our pinned Laravel/Flysystem/PHP combination rather than assuming a patch bump is inert.
8. What is the fork-and-own cost if upstream goes quiet for two quarters?

Integration Approach

Stack fit

• Laravel 9–13 on Flysystem 3 / PHP 8.1+ is now the realistic target range, per v2.0.8's Laravel 13 compat PR and the widened CI PHP matrix. Flysystem 1/2 remain unsupported by the v3 adapter line; any legacy disk on the older contract needs its own path.
• Widening the supported range is helpful for teams mid-upgrade (Laravel 12 → 13), but it does not mean we should adopt Laravel 13 early on the strength of a single Laravel Shift PR. Confirm our own framework version is exercised in our integration tests, not just claimed in constraints.
• Config-driven disk definition keeps blast radius small: tenant ID, client ID, client secret (from a secrets manager, never .env in production), drive ID, and a root prefix for environment/tenant isolation.

Migration path

• Do not swap an existing disk. Add onedrive as an additional disk and route one narrowly scoped feature to it first.
• For existing objects, write a one-off artisan command that streams from the source disk to OneDrive, honouring chunked uploads and recording per-object failures. Expect the backfill to be throttled — plan it as a slow background job, not a single run.
• Keep the storage root configurable per environment so staging and production never share a drive.

Compatibility

• Azure AD conditional access, MFA policies, and IP restrictions apply to app registrations; validate against the actual tenant before committing.
• Watch for the app-secret expiry cliff — calendar it and rotate via certificate if possible.
• Filesystem feature parity with S3 (temporaryUrl, object versioning, lifecycle rules, checksums) is partial at best. Document unsupported operations in the internal adapter wrapper and fail loudly rather than silently.
• Treat v2.0.8 as a re-baseline point: capture the diff, run the full wrapper test suite against it, and only then move the pinned version. Do not float onto it because it is a patch.

Sequencing

1. Spike (1 week): register an Azure app, stand up a proof disk, exercise write/read/list/delete/large-file/429 behaviour. Output: a written risk note, not a demo.
2. Wrapper (1 week): internal package that composes the driver, centralizes config and secret retrieval, maps exceptions to our error taxonomy, and pins the upstream version (or a fork). Include the v2.0.8 diff review in this step if it is the version we pin.
3. Observability: instrument Graph call latency, 429 rates, upload failures, and token refresh failures before feature work.
4. Single feature in production behind a config flag, with an S3/local fallback path.
5. Expand only after a full quarter of clean error budgets.

Operational Impact

Maintenance

• Budget for fork ownership. Realistic steady-state is a few hours per quarter monitoring Graph API deprecations and upstream commits, plus a hard-coded contingency to take the fork if upstream ships nothing. Pin to an exact version; never float.
• v2.0.8 modestly improves the maintenance outlook: activity from two first-time contributors plus an automated Laravel 13 compat PR means the project is not dormant. It does not change the conclusion — a compatibility PR from Laravel Shift is a low-effort signal, and there is still no stated support policy.
• The MIT license makes this a governance decision, not a legal one. Record it as an accepted single-vendor dependency in the risk register.
• Add a standing procedure: every upstream tag, including patches, requires a diff review and wrapper regression run before adoption. This release is the justification for that rule.

Support

• No vendor SLA, no commercial support, no security response process. Internal on-call owns every OneDrive-related incident, and the team must be able to debug at the Graph HTTP layer.
• Microsoft support covers the platform, not the adapter — expect finger-pointing during incidents where auth or throttling is implicated.
• The adapter change in v2.0.8 has no changelog narrative, so there is no upstream artefact explaining intent or risk. Our own diff review is the only record.

Scaling

• Graph enforces per-app and per-tenant throttling. Throughput is a policy variable, not a provisioning lever; the design must assume 429s are normal traffic and implement backoff with jitter.
• Large-directory listings are paginated and slow. Avoid designs that enumerate folders at request time; cache directory metadata.
• Not a CDN origin. Serving user-facing assets directly from OneDrive will produce latency and throttling complaints — front it with a cache or restrict to low-volume document access.
• Per-tenant storage quotas (OneDrive/SharePoint) become an application failure mode; monitor quota headroom proactively.
• No scaling-relevant change in v2.0.8.

Failure modes

• 401 from an expired/rotated secret → total disk outage; mitigated by rotation runbook and secret-expiry alerting.
• 429/503 throttling → cascading job failures if retries are naive; require exponential backoff and dead-letter queues.
• 507/quota exhaustion → writes fail silently in some code paths if exceptions are swallowed; enforce fail-fast.
• 423 file-locked (user has the document open in Office) → transient write failures unique to this backend; needs retry-with-jitter and user-facing messaging.
• Async copy returning 202 → code that assumes synchronous completion will read a missing file; must poll the monitor URL.
• Path collisions from case-insensitivity and reserved characters → objects overwritten or rejected; sanitize keys at the wrapper boundary.
• Partial chunked uploads leaving zero-byte or truncated files → verify size/hash after upload for anything business-critical.
• Patch-release regression (new): an unqualified change in OneDriveAdapter.php can silently alter request payloads or error handling. Detect via version pinning plus a regression suite that exercises Graph error codes and large-file paths against a real tenant.

Ramp-up

• Engineering: ~2–3 days for a mid-level PHP developer familiar with Flysystem; the learning curve is Graph auth and throttling, not the adapter.
• Platform/IT: Azure AD app registration and admin consent are on the critical path and typically take longer than the code. Start the access request first.
• Documentation deliverable: a runbook covering secret rotation, quota monitoring, 429 triage, the patch-release diff-review procedure, and the fork procedure — this is what makes the dependency survivable at ~50 stars.