Nova Tinymce Laravel Package

Getting Started

1. Install the package and publish its assets/config:

   composer require <vendor>/<package>
   php artisan vendor:publish --tag=<package>-config
   

2. Check config/<package>.php first. Look for the upload route prefix, middleware group, disk, and validation rules.
3. Inspect the registered route before wiring up a frontend:

   php artisan route:list --path=<upload-prefix>
   

   After 1.0.3 the image upload endpoint is CSRF-protected, so confirm whether it sits behind web/VerifyCsrfToken or a package-defined middleware stack.
4. First use case: upload an image from a Blade form or a first-party SPA. For a Blade form, include @csrf and enctype="multipart/form-data". For an SPA, fetch the CSRF cookie first and send the token with the request.
5. If you are upgrading from 1.0.2, treat this as a behavior change for any non-browser client. API consumers that previously posted to the endpoint without a CSRF token will now receive 419 Page Expired unless they are updated or the route is explicitly excluded.

Implementation Patterns

• Blade forms: Use the package route as-is and include @csrf. This is the simplest path and requires no changes for 1.0.3.
• SPA with Sanctum/axios: Call /sanctum/csrf-cookie before uploading, ensure withCredentials: true, and let axios read the XSRF-TOKEN cookie. Upload via FormData; do not manually set Content-Type.
• Token-authenticated APIs: If the upload endpoint is used by mobile apps or service-to-service clients, either move it to an API middleware group, add it to VerifyCsrfToken::$except, or front it with a stateful Sanctum request. Prefer narrowing an exclusion to the exact upload route rather than excluding a wildcard.
• Customizing the endpoint: Use the package config for disk, max size, mime types, and route prefix. If the package exposes middleware config, override it in the published config rather than editing vendor files.
• Validation and storage: Keep package validation for basic image checks, but add application-level rules (dimensions, aspect ratio, virus scanning) via a wrapper controller or form request if the package supports route/controller overrides.
• Testing: In feature tests use $this->withoutMiddleware(\App\Http\Middleware\VerifyCsrfToken::class) only when testing upload logic, and add a separate test that asserts CSRF behavior for browser-facing flows. Use Storage::fake() and UploadedFile::fake()->image().
• Frontend integration: For Inertia or Livewire, the CSRF token is already handled by the framework; verify the upload component sends the token after 1.0.3 rather than assuming the endpoint is exempt.

Gotchas and Tips

• 419 after upgrading to 1.0.3: The most likely symptom. Check the request’s X-CSRF-TOKEN header, _token field, or X-XSRF-TOKEN cookie. Browser clients using axios need the CSRF cookie endpoint and withCredentials.
• Cross-origin sessions: If the SPA and Laravel app are on different subdomains, set SESSION_DOMAIN, SANCTUM_STATEFUL_DOMAINS, and CORS supports_credentials correctly. A missing cookie is often a domain/config issue, not a package bug.
• Don’t over-exclude CSRF: Adding the upload route to VerifyCsrfToken::$except fixes API clients but removes protection for browser sessions. Prefer separate API and web routes if both consumers exist.
• Route caching: After changing config or middleware, run php artisan config:clear and php artisan route:clear. Cached routes can hide middleware changes introduced by the release.
• Debugging middleware: Use php artisan route:list -v to see the full middleware stack for the upload endpoint. Confirm whether CSRF is applied by the package, the application’s web group, or both.
• Extension points: Published config, package middleware, route registration, and any custom controller binding are the safest override points. Avoid modifying vendor files so future releases remain upgradeable.
• Security note: Adding CSRF protection to an image upload endpoint is a positive change. It reduces cross-site upload abuse, but does not replace authentication, authorization, file type validation, size limits, or storage isolation. Keep those controls in place.
• Upgrade checklist: Re-test browser uploads, SPA uploads, API clients, and automated tests that post directly to the endpoint. Add a regression test for the 419 path so future middleware changes are caught.