- How does mnot/hinclude differ from Laravel’s native Blade @include directive?
- Unlike Blade’s server-side includes, mnot/hinclude uses HTTP headers (X-Include) to fetch fragments *after* the initial page render, enabling dynamic, client-side composition. This is ideal for loading non-critical sections (e.g., ads, user-specific widgets) without blocking page load, but requires JavaScript to process the includes.
- Can I use this package with Laravel’s caching middleware (e.g., Varnish) for edge-side includes (ESI)?
- Yes. mnot/hinclude’s X-Include headers work seamlessly with Varnish’s ESI tags. Configure Varnish to process the headers and cache included fragments separately, reducing backend load. Ensure your Laravel responses include the `X-Include` header with the fragment URL for Varnish to handle the inclusion logic.
- What Laravel versions does mnot/hinclude support, and are there breaking changes from older versions?
- The package is PHP 7.2+ compatible and works with Laravel 7+. Since its last update in 2018, it lacks explicit Laravel 9/10 support, but basic functionality (header injection) remains unchanged. Test thoroughly with your Laravel version, especially if using newer features like Symfony HTTP message components.
- How do I configure CORS for external includes (e.g., fetching fragments from another domain)?
- Laravel’s CORS middleware must allow requests to the fragment’s origin. Add the domain to `$allowedOrigins` in `config/cors.php` and ensure the fragment’s server includes the `Access-Control-Allow-Origin` header. For self-hosted microservices, use Laravel’s `VerifyCsrfToken` middleware to restrict access if needed.
- What’s the best way to test mnot/hinclude in a Laravel application before production?
- Start by mocking the X-Include header in tests using Laravel’s `Response::macro` to inject headers. Test edge cases like failed fetches (simulate 404s) and JavaScript-disabled scenarios. Use browser dev tools to inspect network requests and verify fragments load correctly. For integration tests, use Pest or PHPUnit with Laravel’s HTTP tests.
- Will mnot/hinclude work with static site generators (SSGs) like Laravel Vapor or Hugo?
- No, mnot/hinclude requires a dynamic Laravel backend to inject X-Include headers. For SSGs, use static inclusion methods like Hugo’s shortcodes or Laravel’s `@verbatim` for static fragments. If you need dynamic includes in a static context, consider a hybrid approach with a lightweight API endpoint that serves fragments.
- How do I handle SEO when using client-side includes (e.g., Googlebot not executing JavaScript)?
- Exclude includes during server-side rendering by checking `Request::is('*')` and falling back to static content. For critical SEO content, pre-render fragments server-side or use Laravel’s `@stack` directives. Tools like Prerender.io can also execute JavaScript for crawlers, but test thoroughly to avoid duplicate content issues.
- Can I use mnot/hinclude with modern frontend frameworks like React or Vue without a build step?
- Yes, but you’ll need to include the package’s JavaScript library via a `<script>` tag in your layout. For frameworks like React, manually call the `hinclude.process()` function after hydration. If using a bundler (e.g., Vite), import the library directly. Avoid build-step dependencies unless you need custom processing.
- What alternatives exist for Laravel if I need server-side includes instead of client-side?
- For server-side includes, use Laravel’s native Blade `@include` or `@stack` directives for traditional partials. For dynamic ESI-like behavior without JavaScript, consider Laravel’s `Response::addEsi()` (if using Varnish) or packages like `spatie/laravel-esi` for edge caching. If you need hybrid server/client includes, combine Blade for critical content and mnot/hinclude for non-critical fragments.
- How do I debug failed includes or missing fragments in production?
- Enable Laravel’s `debugbar` to inspect HTTP headers and responses. Check browser console logs for JavaScript errors (e.g., failed fetch requests). Use middleware to log include attempts and failures to a monitoring tool like Sentry. For CORS issues, verify the fragment’s server includes the correct `Access-Control-Allow-Origin` header and that your Laravel CORS config permits the request.