Laravel Export Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-export
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Spatie\Export\ExportServiceProvider"
   

2. First Export:

   php artisan export
   

   Outputs static HTML files to storage/app/export (default) with all routes and the public directory.

First Use Case: Static Blog

• Create a blog with Laravel (e.g., using posts routes).
• Export to a static site:

  php artisan export
  

• Deploy the export folder to Netlify/Vercel for hosting.

Implementation Patterns

1. Crawling vs. Manual Paths

• Crawling (Default): Automatically discovers all routes via php artisan export.

  // config/export.php
  'crawl' => true,
  

• Manual Paths: Explicitly define routes to export:

  'paths' => [
      '/',
      '/blog/{post}',
      '/about',
  ],
  

  Or dynamically via Exporter class:

  $exporter->paths(Post::all()->pluck('slug'));
  

2. Asset Handling

• Include Files: Copy additional assets (e.g., PDFs, images):

  'include_files' => [
      'public' => '',
      'storage/app/docs' => 'docs',
  ],
  

• Exclude Patterns: Skip PHP files or build artifacts:

  'exclude_file_patterns' => [
      '/\.php$/',
      '/mix-manifest\.json$/',
  ],
  

3. Hooks for Workflows

• Pre-Export Hooks: Build assets before export (e.g., Vite/Tailwind):

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

• Post-Export Hooks: Deploy to Netlify/S3:

  'after' => [
      'deploy' => 'netlify deploy --prod',
  ],
  

  Skip hooks with flags:

  php artisan export --skip-deploy
  

4. Dynamic Exports

• Conditional Exports: Use the Exporter class in a service provider:

  public function boot(Exporter $exporter) {
      if ($this->app->environment('production')) {
          $exporter->crawl(false)->paths(['/']);
      }
  }
  

• API-Driven Exports: Trigger exports via HTTP (e.g., admin panel):

  Route::post('/export', function () {
      Artisan::call('export');
      return response()->json(['status' => 'exported']);
  });
  

5. Custom Disks

• Store exports in S3 or remote storage:

  // config/filesystems.php
  'disks' => [
      'export' => [
          'driver' => 's3',
          'bucket' => 'my-static-site',
      ],
  ],
  

Gotchas and Tips

Pitfalls

1. Circular Redirects:

   • Crawling may fail if routes redirect infinitely.
   • Fix: Disable crawling for problematic routes or use paths to whitelist safe routes.

2. Asset Paths:

   • Hardcoded public/ paths in HTML break static exports.
   • Fix: Use Laravel’s asset() helper or configure APP_URL in .env:

     APP_URL=https://your-static-site.com
     

3. Dynamic Content:

   • Exports capture static snapshots. Avoid:
     • User-specific data (e.g., Auth::user()).
     • Time-sensitive content (e.g., now()).
   • Fix: Use middleware to exclude dynamic content:

     if (request()->header('X-Laravel-Export')) {
         return response()->view('static-version');
     }
     

4. Memory Limits:

   • Large sites may hit memory limits during crawling.
   • Fix: Enable streaming:

     'use_streaming' => true,
     

5. Symlinks:

   • Exports may fail on symlinked files/directories.
   • Fix: Update exclude_file_patterns or resolve symlinks manually.

Debugging Tips

• Dry Runs: Test exports locally before deploying:

  php artisan export --dry-run
  

• Verbose Output: Enable debug mode:

  php artisan export --verbose
  

• Check Excluded Files: Verify exclude_file_patterns isn’t blocking critical assets.

Extension Points

1. Custom Crawlers: Extend Spatie\Crawler\Crawler to handle custom routes (e.g., API-generated pages).

2. Post-Processing: Modify exported HTML with a after hook:

   'after' => [
       'optimize' => 'htmlmin export/*.html',
   ],
   

3. Middleware for Exports: Add a middleware to modify responses for static exports:

   public function handle($request, Closure $next) {
       if ($request->header('X-Laravel-Export')) {
           // Serve static version
       }
       return $next($request);
   }
   

Pro Tips

• Incremental Exports: Cache exported files and only re-export changed routes:

  $exporter->paths(array_diff($newRoutes, $cachedRoutes));
  

• Multi-Environment: Use different paths for dev/staging/prod:

  $exporter->paths(config('export.paths.' . config('app.env')));
  

• CI/CD Integration: Automate exports in GitHub Actions:

  - name: Export static site
    run: php artisan export
  - name: Deploy
    uses: netlify/actions/deploy@v1
    with:
      directory: storage/app/export