Laravel Amplitude Laravel Package

Getting Started

1. Install the package with Composer and publish its config/views if it exposes them:

   composer require <vendor>/<package>
   php artisan vendor:publish --provider="<Vendor>\<Package>\<PackageServiceProvider>"
   

2. Look first at:
   • the package service provider for Blade directives/components/helpers,
   • the published config for script placement and attributes,
   • the package views for the actual <script> rendering.
3. Confirm how your app sets Laravel’s Vite CSP nonce. In a CSP-enabled app this is typically done once per request, before views render:

   Vite::useCspNonce($nonce);
   

   As of 1.1.0, any <script> rendered by the package automatically picks up that nonce. You do not need package-specific nonce configuration if the app already sets one.
4. First use case: render the package’s script in your layout while serving a nonce-based CSP:

   {{-- layout head --}}
   <x-package-script />
   

   With script-src 'nonce-...' in place, the package output should carry the same nonce rather than requiring 'unsafe-inline'.

Implementation Patterns

• Set the nonce once, early. Put Vite::useCspNonce(...) in middleware or a service provider that runs before the response is rendered. The package reads the nonce at render time, so ordering matters.
• Use the package’s Blade surface. Prefer the package component/directive over copying its script markup into your templates; that is what receives the nonce automatically.
• Render package scripts from layouts or partials. A single inclusion in app.blade.php or a dedicated scripts partial keeps nonce behavior consistent across pages.
• Align with your CSP middleware. If you use laravel-security-headers or similar, ensure the Content-Security-Policy header contains the same nonce value used by Vite. The package only annotates its script tags; it does not create or synchronize the response header.
• Multiple package scripts share one request nonce. You can render several package scripts on a page; each should receive the same nonce. Do not generate a new nonce per script.
• Cache views, not nonces. Blade view caching is fine, but full-page response caching must not cache HTML containing a nonce unless the nonce is regenerated on each response.
• Test the contract. Add a feature test that asserts the CSP header nonce and the package’s rendered <script nonce="..."> match:

  $response->assertHeader('Content-Security-Policy');
  $response->assertSee('nonce="'.$nonce.'"', false);
  

• Local vs production. In local development, Vite’s dev client also uses the nonce. Verify that package scripts and Vite-injected scripts both receive it, especially when switching between npm run dev and built assets.
• Extension point. If the package publishes its views, customize script attributes there rather than post-processing HTML; keep the nonce attribute intact.

Gotchas and Tips

• Nonce must be set before rendering. If the package script renders before Vite::useCspNonce(...), the script may be emitted without a nonce or with an empty one. Move nonce setup into early middleware.
• Header and HTML must match exactly. A nonce in the CSP header that differs from the script tag’s nonce attribute will block the script. This is the most common CSP integration failure.
• Do not hardcode or cache the nonce in config. Nonces are per-response. Caching config:cache is fine; caching a rendered nonce is not.
• Full-page caching needs care. If you cache HTML containing a nonce, either exclude those responses from caching or rewrite the nonce and CSP header after cache retrieval.
• laravel-security-headers may have its own nonce flow. Confirm whether it reads Laravel’s Vite nonce or generates a separate one. If separate, align them explicitly; otherwise the package script and header will disagree.
• The package only covers its own scripts. Inline scripts, analytics snippets, and other manually added <script> tags still need nonce="{{ Vite::cspNonce() }}" or equivalent.
• 'strict-dynamic' changes the failure mode. With a nonce and 'strict-dynamic', scripts loaded by a nonced script are trusted, but the initial package script still needs the correct nonce.
• Debug with the browser, not just the DOM. Check the response Content-Security-Policy header for the nonce value and compare it to the script tag. Browser console CSP violations usually name the blocked script and the expected nonce.
• Use report-only first when rolling out. Deploy Content-Security-Policy-Report-Only to catch package scripts that are missing or mismatching nonces before enforcing.
• Emails, PDFs, and queued renders have no CSP context. The nonce feature is relevant to HTTP responses; don’t expect nonce behavior in non-browser rendering paths.
• Keep package views updated. If you published and customized the package views, re-check them after upgrades so you don’t accidentally drop the nonce attribute added in 1.1.0.