Laravel Export Laravel Package

Technical Evaluation

Architecture Fit

• Static Site Generation (SSG) Use Case: The package is a perfect fit for Laravel applications requiring static site exports (e.g., blogs, marketing sites, documentation). It leverages Laravel’s routing, middleware, and Blade templating while generating static HTML, CSS, and JS assets.
• Hybrid Dynamic/Static Workflows: Ideal for teams using Laravel for dynamic content (e.g., CMS via Nova/Filament) but needing static hosting (Netlify, Vercel, S3) for performance/scalability.
• Asset Inclusion: Seamlessly integrates with Laravel Mix/Vite by copying the public directory, ensuring assets (images, JS, CSS) are included in the export.

Integration Feasibility

• Laravel-Centric: Built for Laravel, with zero external dependencies beyond Laravel’s core and Spatie’s crawler. Minimal boilerplate required.
• Middleware & Routing Compatibility: Respects Laravel’s middleware stack (e.g., auth, localization) during crawling. Supports redirects and query parameters.
• Customization Hooks: Pre/post-export hooks (e.g., asset compilation, deployment) allow integration with CI/CD pipelines (GitHub Actions, Netlify CLI).

Technical Risk

• Dynamic Content Limitations:
  • Risk: Exported pages are static snapshots. Dynamic data (e.g., user-specific content, real-time APIs) won’t reflect changes post-export.
  • Mitigation: Use the package for content that changes infrequently (e.g., blogs, docs) or pair with a headless CMS (e.g., Strapi) for dynamic layers.
• Crawling Scope:
  • Risk: Uncontrolled crawling may export unintended routes (e.g., admin panels, API endpoints).
  • Mitigation: Explicitly define paths or use middleware to block sensitive routes (e.g., app/Http/Middleware/BlockExportMiddleware).
• Asset Dependencies:
  • Risk: Broken asset paths if Laravel Mix/Vite configurations change post-export.
  • Mitigation: Test exports locally with php artisan export and validate asset URLs.

Key Questions

1. Use Case Clarity:
   • Is the primary goal static hosting (e.g., Netlify) or offline backups of dynamic content?
   • Are there dynamic elements (e.g., user auth, real-time data) that must be excluded?
2. Performance:
   • What’s the expected site size? Large sites may require use_streaming: true to avoid memory issues.
3. CI/CD Integration:
   • How will exports trigger deployments? (e.g., Netlify CLI, S3 sync, or custom scripts).
4. Asset Management:
   • Are assets (images, JS) hosted externally (e.g., CDN) or locally? Local assets must be included via include_files.
5. Fallbacks:
   • How will broken links or missing pages be handled? (e.g., 404 templates, redirects).

Integration Approach

Stack Fit

• Laravel Versions: Supports Laravel 11–13 (and PHP 8.1–8.3). Verify compatibility with your Laravel version.
• Asset Build Tools:
  • Laravel Mix/Vite: Works natively; exports the compiled public directory.
  • Custom Assets: Ensure all static assets (fonts, images) are in public or explicitly included via include_files.
• Hosting Providers:
  • Static Hosts: Netlify, Vercel, Cloudflare Pages, S3.
  • Dynamic Hosts: Can export to a local directory for manual uploads (e.g., shared hosting).

Migration Path

1. Pilot Phase:
   • Install the package: composer require spatie/laravel-export.
   • Test with a subset of routes (e.g., /blog/*) using php artisan export.
   • Validate assets and links with include_files and exclude_file_patterns.
2. Configuration:
   • Publish config: php artisan vendor:publish --provider=Spatie\Export\ExportServiceProvider.
   • Customize config/export.php:

     'paths' => ['/', '/blog', '/about'], // Explicit routes
     'include_files' => ['public', 'storage/app/public'], // Additional assets
     'use_streaming' => true, // For large sites
     

3. Hooks Integration:
   • Add pre-export hooks (e.g., asset compilation):

     'before' => [
       'build' => 'npm run build',
     ],
     

   • Add post-export hooks (e.g., deployment):

     'after' => [
       'deploy' => './vendor/bin/netlify deploy --prod',
     ],
     

4. CI/CD Automation:
   • Trigger exports on git push to main:

     # .github/workflows/export.yml
     jobs:
       export:
         runs-on: ubuntu-latest
         steps:
           - uses: actions/checkout@v4
           - uses: actions/setup-node@v4
           - run: composer install
           - run: npm install
           - run: npm run build
           - run: php artisan export
           - run: ./vendor/bin/netlify deploy --prod
     

Compatibility

• Middleware: Ensure middleware (e.g., auth, locales) doesn’t break crawling. Use X-Laravel-Export header to bypass auth during export:

  // app/Http/Middleware/TrustProxies.php
  public function handle($request, Closure $next) {
      if ($request->header('X-Laravel-Export')) {
          return $next($request->withoutHeaders('X-Laravel-Export'));
      }
      return $next($request);
  }
  

• Routing: Avoid circular redirects or infinite loops in routes.
• Database: Exports are static; ensure no DB queries leak into templates (use @verbatim or static data).

Sequencing

1. Development:
   • Test locally with php artisan export.
   • Validate URLs, assets, and redirects.
2. Staging:
   • Run in a staging environment to catch issues (e.g., broken links, missing assets).
3. Production:
   • Schedule exports during low-traffic periods.
   • Monitor deployment hooks for failures.

Operational Impact

Maintenance

• Dependency Updates:
  • Monitor Spatie’s changelog for breaking changes (e.g., Laravel 13+ support).
  • Update spatie/crawler and Laravel core dependencies regularly.
• Configuration Drift:
  • Document config/export.php changes (e.g., new paths, hooks).
  • Use version control for the export directory (e.g., .gitignore exceptions for critical sites).

Support

• Debugging Exports:
  • Check logs for crawling errors (e.g., 404s, timeouts).
  • Use --skip-all to debug without hooks:

    php artisan export --skip-all
    

• Asset Issues:
  • Verify public directory contents and include_files patterns.
  • Test asset URLs post-export (e.g., curl -I https://example.com/css/app.css).
• Hook Failures:
  • Isolate hook failures (e.g., npm run build) by running them manually.

Scaling

• Large Sites:
  • Enable use_streaming: true to reduce memory usage.
  • Limit crawling depth or use paths to exclude deep routes.
• Performance:
  • Cache exported files (e.g., Netlify’s cache) to reduce rebuilds.
  • Use incremental exports (e.g., only regenerate changed routes) via custom logic in Exporter class.
• Distributed Exports:
  • For multi-server setups, coordinate exports to avoid race conditions (e.g., lock files).

Failure Modes

Ramp-Up

• Team Training:
  • Document the export workflow (e.g., "How to add a new route to the export").
  • Train devs on debugging exports (e.g., checking logs, validating assets).
• Onboarding:
  • Provide a template for config/export.php with common settings.
  • Example CI/CD pipeline snippet for new projects.
• Rollback Plan:
  • Maintain a backup of