Story Laravel Package

Product Decisions This Supports

• Build vs. buy for the internal content surface — the core decision. Story ships the commodity 80% of an internal CMS: a Content model covering both posts and pages, admin CRUD, slug generation, publication status, Markdown authoring via SimpleMDE, and publishable migrations/config/views. Frame the comparison honestly: one sprint of engineering to ship a minimal posts/pages module we fully own vs. near-zero upfront cost plus a permanent, single-owner upgrade obligation tied to Orchestra releases. Do not evaluate Story as a standalone CMS product — it isn't one.
• A platform bet, not a feature bet. Story is a first-party extension of Orchestra Platform v3.2, not a general Laravel package. v3.2.0 hardens that coupling: StoryServiceProvider now extends Orchestra\Foundation\Support\Providers\ModuleServiceProvider, ACL moved to Orchestra\Support\Facades\ACL, and AuthServiceProvider/ContentPolicy replace the removed CanManage middleware. Adopting Story is functionally a decision to run Orchestra as our admin/foundation layer. Sequence the platform decision first; Story is a downstream consequence on the roadmap, not an independent line item.
• Roadmap sequencing and recurring dependency cost. Every Orchestra upgrade becomes a Story upgrade becomes a migration task in our plan. Model this as a non-optional recurring line item bound to platform releases — that recurring obligation, not the initial composer require, is the real price of the "buy."
• Authorization architecture for editorial roles. Moving editor-vs-admin permissions from route middleware (CanManage) to policies/gates (ContentPolicy) sets the precedent for how every other module in our admin enforces permissions. Decide this pattern once, deliberately, with a named owner — it will be copied.
• Content-type extensibility and shared authoring. Content::newPostInstance() / newPageInstance() plus url() / editUrl() / deleteUrl() make it cheap to add content types and to link content from adjacent modules (morph map via getMorphClass()). Relevant if the roadmap is blog + docs + landing pages sharing one authoring model; not relevant if we need typed/structured content.
• Scoping the explicit "no" list. Nothing here signals versioning/history, editorial workflow or approvals, localization, or structured content modeling. If any of those are on the roadmap within two quarters, that is a signal against adoption — not a gap to be patched later with custom work.
• Vendor/dependency risk register entry. v3.2.0 removes two public surfaces (CanManage, Content::$morphClass) and deprecates Acl aliases — evidence the public API is still settling. Zero dependents and a 0.3 score mean no community answers, no third-party extensions, and no one else catching the next breaking change. Budget for self-support and prohibit deep customization against model internals.

When to Consider This Package

Consider it when:

• We are already running Orchestra Platform v3.2 (or have independently committed to it for admin/module infrastructure). Story then becomes a cheap add-on rather than a platform commitment.
• The product needs plain posts and pages with Markdown authoring, drafts vs. published, slugs, and a taxonomy-lite organization model — and nothing more sophisticated than that for the next two-plus quarters.
• A small internal team owns the admin surface and we want a familiar CMS-style layer that stays inside Laravel conventions (Blade rendering, service providers, policies) rather than importing a separate CMS runtime.
• We accept a named internal maintainer and a recurring upgrade line item, and we plan to extend only through StoryPlugin.

Look elsewhere — or build the ~one-sprint minimal module — when:

• We are not on Orchestra Platform. Adapting Story to plain Laravel costs more than writing a small posts/pages module; the assessment is unambiguous on this.
• The roadmap requires versioning, approval workflows, localization, or structured/typed content. None of that is signalled in this release.
• We want a headless content service with a stable, versioned public API. Story's API is demonstrably still moving (two removals in one minor release); it is a content source we query, not a contract we build against.
• We cannot staff ongoing maintenance tied to Orchestra upgrades, or no team will accept ownership before adoption.
• We need a public-facing, high-traffic rendering path out of the box — Story owns admin CRUD; presentation, caching, and routing are ours to build.

Decision rule for the room: adopt only if (a) Orchestra is already in the stack or independently justified, (b) requirements are posts/pages/status/slugs for at least two quarters, and (c) an internal owner is named before the first install.

How to Pitch It (Stakeholders)

To executives (one paragraph): Story is a lightweight CMS layer that gives us articles and pages, drafts and publishing, slugs, and Markdown editing essentially for free — provided we are already standardizing on Orchestra Platform for our admin layer. The trade is straightforward: near-zero build cost today, in exchange for a recurring upgrade obligation tied to every Orchestra release and the need to name an internal owner. It does not give us content versioning, approval workflows, localization, or structured content — so if any of those are on the near-term roadmap, this is the wrong tool and we should say so now rather than fund custom work later. This is a platform decision with a content feature attached, not a standalone CMS purchase.

To engineering (the working contract):

• Prerequisite gate: confirm orchestra/platform (or orchestra/foundation) is installed and pinned to a 3.2-compatible line. If not, stop — do not "port" Story to plain Laravel.
• Integration boundary: Story owns admin CRUD; our app owns front-end routes and views. Query Orchestra\Story\Model\Content from our controllers and treat Story as a content source. Never build presentation routes inside Story.
• Stable surface we allow ourselves: title, body, slug, status, and the URL helpers. Keep an interface or DTO between Story and our views so migration off is not a rewrite. Avoid extending Content or overriding internals.
• Extension seam: StoryPlugin is the only sanctioned customization point for menus, assets, and admin screens. Vendor edits are merge conflicts on the next Orchestra bump.
• Upgrade risk to test explicitly: CanManage removal is the highest-risk item — a misregistered policy fails silently, either 403-ing legitimate editors or falling open. Stage the upgrade and test every content route against every role, with positive and negative cases per ability (view, create, update, delete) in ContentPolicy. Second risk: $morphClass removal — switch to getMorphClass() with an explicit Relation::morphMap() and a regression test on any relationship traversing content.
• Mechanical cleanups to do now, not later: replace Acl aliases with Orchestra\Support\Facades\ACL; re-publish SimpleMDE assets (v1.9.1) and clear caches so the editor doesn't silently run an old build; rebase any custom providers on ModuleServiceProvider to avoid double-registered routes and views.
• Known user-visible failure mode: slug collisions on edit. Pin the slug on publish and assert url() after rename in tests — a broken live URL is the most visible failure after an auth regression.
• Ownership: zero dependents means we are the maintainer. Name an internal owner and attach Story maintenance to each Orchestra upgrade in the planning cycle.

Ask: approve the Orchestra platform sequencing decision first; if approved, treat Story as a scoped add-on with a one-sprint integration, a named owner, and a documented "no list" (no versioning, workflow, localization, or structured content) signed off by product.