Client Portal Laravel Package

Getting Started

The first thing to internalise is the licensing constraint: Statamic Pro is a hard requirement, not a nice-to-have. Portals depend on multiple client accounts plus a dedicated client role, and Statamic Core ships neither. If you are on Core, the install will appear to succeed and then fail at the point where you try to create or assign a client — budget the Pro licence into the project before you start.

Minimum setup path:

1. Install the addon via Composer as normal (Statamic auto-discovers it), then run the addon's publish step so you get its config, migrations and portal views into your app.
2. Confirm your users / roles setup supports a client role. If you already run a bespoke role system, reconcile it now rather than after clients have registered.
3. Publish and read the config file first — that is where portal routing, registration toggles, storage/disk choices and role names live. Most "it doesn't work" reports resolve here.
4. Visit /portal (or whatever prefix you configure) and go through the registration + login flow yourself before inviting anyone.

The first real use case is almost always: create a project, hang a few phases and modules off it, upload a file, and invite one client. That single end-to-end pass exercises the registration, role, permission and file-download paths, which are the four places this package touches the rest of your app.

Implementation Patterns

Treat the portal as a separate front-end inside your app. The addon owns /portal routing and view rendering; your job is to override templates, not to rebuild them. Publish the views and edit copies rather than fighting the vendor files, so upgrades stay cheap.

Role-based gating. Everything in the portal is scoped to the client role. If you have staff who need to view the portal as a client would ("log in as"), use Statamic's impersonation rather than granting staff the client role — mixing the two blurs your permission model fast.

Model the project data in Statamic, render it in the portal. Projects → phases → modules → files is a hierarchy you will want to query from your own code (dashboards, emails, notifications). Hook into the addon's events/entry lifecycle rather than polling. Typical integrations:

• On client registration → notify an account manager.
• On file upload → push to your storage disk and record an audit trail.
• On project status change → email the client.

Escaping discipline in custom templates. From 1.1.1 the addon escapes portal titles, project status, phase/module titles, descriptions, button labels, file names, and the login heading/intro. If you override views, keep using {{ }} in Antlers and {{ $x }} in Blade for anything a client controls. The moment you reach for {!! !!} or {!! $x !!} to "fix" a formatting issue, you have reintroduced the exact bug this release patched.

Config over code for wording. Login heading and intro are plain-text configurable fields — use them for branding instead of forking the login view.

Gotchas and Tips

• Upgrade to 1.1.1 immediately if you are on 1.1.0 or earlier. The XSS vector was a client registering with HTML in their name, then staff viewing /portal — a stored XSS across the trust boundary between untrusted client input and privileged staff sessions. That is a serious one.
• The escaping fix covers the addon's own output, not yours. Custom views, email templates, PDF exports and API responses that echo client-supplied names are still your responsibility. Audit anything you built around the portal for unescaped user data.
• Statamic Pro is now documented as required. If you scaffolded a project on Core, or you are maintaining a site where the licence lapsed, portals will break in confusing ways. Check the edition before debugging anything else.
• Public registration is an attack surface. Clients self-register into a role. Rate-limit it, add a honeypot or CAPTCHA, and decide whether new accounts are active immediately or need approval.
• Field names in the portal are plain text by design — statuses, phase titles, descriptions, button labels. Do not assume they are sanitised HTML; they are escaped, so any formatting you want (bold, links) has to come from your template, not the field value.
• Debugging blank or "forbidden" portal pages is nearly always one of: user lacks the client role, the portal route isn't in your excluded-CSRF/route cache config, or php artisan config:clear hasn't been run after editing the addon config.
• Watch the changelog on minor bumps. This release changed both behaviour (output escaping) and requirements (Pro). Anything under the 1.x line can move the goalposts on both.