6.6 KiB
6.6 KiB
Multi-User Access — Implementation Phases
Plan of record for adding multi-user access (workspaces, folder sharing, invitations) to mytodos. Tech: Laravel 13 / PHP 8.4 / MySQL / Livewire 4 SFC pages / Pest / Flux UI (free).
Status: Phases 1–3 complete and green (303 tests, 714 assertions). Phase 4 pending.
Access model (settled decisions)
- Roles:
admin > editor > marker > viewer(additive). - Effective folder role = max of:
- creator → admin,
- explicit
folder_usershare, - inherited ancestor shares,
- workspace default: owner/admin → admin, member → viewer.
- Folder visibility:
private/workspace. Defaults: personal → private, family/org → workspace. - Explicit shares cascade down the subtree. A
privatefolder drops out of inherited workspace access (workspace-wide grants flow only through workspace-visibility folders). - No deny semantics.
- Todos have no ACL — they inherit their folder's access and
organization_id.todos.user_idstays "created by". - Page scope: folders in the user's active workspace (
users.current_organization_id) the user can access, plus folders explicitly shared with them from any workspace. Workspace-membership folders in non-active workspaces are NOT shown on pages. Folder::scopeVisibleTo(Builder, User|int $user, ?int $workspaceId = null)andTodo::scopeVisibleTo(...).nullworkspaceId keeps broad behavior (model tests rely on it); pages passactiveWorkspaceId(): int.organization_idis NOT NULL onfoldersandtodos.
Phase 1 — Foundations ✅
- Migrations
2026_10_10_214840–214847: workspaces (organizations),organization_userpivot (role),folder_userpivot (role, invited_by),invitations, plusorganization_idonfolders/todos,current_organization_idonusers. - Models:
Organization,Invitation; relations onUser,Folder,Todo. - Enums:
OrganizationRole,FolderRole,FolderVisibility(each withlabel()). - Policies:
FolderPolicy(manageShares),OrganizationPolicy(manageMembers),InvitationPolicy(create/delete),TodoPolicy(auto-discovered). - Model scopes/helpers:
Folder::scopeVisibleTo/treeForVisibleTo/flattenTree/ creating hook;Todo::scopeVisibleTo/nextPositionFor. - Factories:
OrganizationFactory(personal/family/withMember),FolderFactory(inOrganization/sharedWithWorkspace/private/childOf),InvitationFactory(forFolder/forOrganization/accepted/expired),UserFactory(unsubscribed). - Seeders pass
organization_idexplicitly.
Phase 2 — Access scoping in pages ✅
- All three pages (folders, todo list, dashboard) use
visibleFolder/folderForAction/activeWorkspaceId()and authorize withcan()/@can. - Folder workspace label in the UI.
- Tests:
tests/Feature/SharedAccessPagesTest.phpplus model-level coverage.
Phase 3 — Sharing & invitations ✅
Invitationmodel:EXPIRY_DAYS = 14;booted()creating hook (tokenStr::random(64),expires_at = Carbon::now()->addDays(14));scopePending;isForFolder/isForWorkspace;folderRole/organizationRole;roleLabel;inviterName/inviteableName;accept(User).Folder::invitations()MorphMany;treeForVisibleToaddswithCount('shares')(shares_count).- Mail:
InvitationMail+resources/views/mail/invitation.blade.php. Sent synchronously (Mail::to($email)->send(...)); mail default driverlog,QUEUE_CONNECTION=database. Invitations upserted on (inviteable_type,inviteable_id,email) with fresh token/expiry. - Accept page
resources/views/pages/invitations/⚡accept.blade.php, routeinvitations/{invitation:token}nameinvitations.accept(auth-only). Seat-limit check; redirects todashboard. - Folders page share modal (gated
manageShares): visibility select (hidden + server-guarded for personal workspaces), collaborator list with role select + remove, invite-by-email + role, pending invitations + revoke. - Members page
resources/views/pages/workspace/⚡members.blade.php, routemembersnamemembers(subscribed). Seat usage, role change, remove (blocks self + owner; reassigns removed user to a personal workspace), invite (seat-limit aware), revoke. - Nav: "Members" item in
resources/views/layouts/app/sidebar.blade.phpandheader.blade.php. - Tests:
InvitationTest,InvitationAcceptPageTest,FolderSharingTest,WorkspaceMembersTest(helpersfamilyWorkspaceFor,membersWorkspaceFor).
Phase 4 — Workspace creation & switching + billing polish ⏳
Planned, not started. Candidate work:
- Workspace creation flow (create personal/family/organization workspace; ownership).
- Active-workspace switching UI (updates
users.current_organization_id) in sidebar/header. - Workspace settings (rename, members already on the members page).
- Billing polish: ensure plan/seat limits and upgrade prompts align with workspace type
(
config/workspaces.phpseat limits: personal=1, family=6, organization=null;config/plans.php:subscription_type='default',trial_days=14, planpro). - Additional migrations are allowed in Phase 4; Phases 1–3 migrations are frozen.
Verification
php artisan test→ 303 passed, 714 assertions.vendor/bin/pint --dirty --format agent(Pint formats.blade.phptoo).vendor/bin/phpstan analyse --memory-limit=1G(Larastan, level 7). Note: the defaultcomposer types:checkcrashes at the 128M memory limit — pass--memory-limit=1G. 17 pre-existing errors remain in unrelated files (console seeders,Todo, legacyFolderhelpers, policies). All Phase 1–3 feature files are clean.
Conventions & gotchas
#[Fillable]/#[Hidden]attributes;scopeXxx()naming; enums withlabel().- Create files via
php artisan make:* --no-interaction. - Livewire
Componentbase has noAuthorizesRequests; pages useabort_unless(auth()->user()->can(...), 403); blade uses@can. - Blaze compiler bug: Blade directives as attributes on a Flux component tag
(
@selected()/@checked()on<flux:select.option>) are mangled into aParseError. Usewire:model(array dot paths) instead. Native<input @checked>is fine. - Livewire test harness renders
HttpException/AuthorizationExceptioninto responses (assertStatus(403));ModelNotFoundExceptionpropagates.#[Locked]props can't beset(). - Livewire
->set()firesupdated<Prop>hooks (used withmemberRoles.{id},collaboratorRoles.{id}). - Guest invites: accept page behind
auth; unsubscribed users bounce to pricing viasubscribed/EnsureSubscribed.