Core Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation

   composer require wirbelwild/kiwa-core
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       Wirbelwild\Kiwa\Core\KiwaServiceProvider::class,
   ],
   

2. Basic Configuration Publish the config file:

   php artisan vendor:publish --provider="Wirbelwild\Kiwa\Core\KiwaServiceProvider" --tag="config"
   

   Update config/kiwa.php with your site’s root directory (e.g., public_html).

3. First Route Define a route in routes/web.php:

   use Wirbelwild\Kiwa\Core\Facades\Kiwa;
   
   Kiwa::get('/', function () {
       return Kiwa::view('home');
   });
   

4. Run the Dev Server

   php artisan kiwa:serve
   

   Access http://localhost:8000 to see your static site.

First Use Case: Static Page with Twig

Create a Twig template (resources/views/home.twig):

<!DOCTYPE html>
<html>
<head>
    <title>Home</title>
</html>

Render it via the route above. Kiwa compiles Twig to static HTML on demand.

Implementation Patterns

1. Static Content Generation

• Workflow: Use Kiwa::view() to render Twig templates dynamically during development. In production, pre-generate static HTML with:

  php artisan kiwa:generate
  

• Integration Tip: Pair with Laravel’s task scheduling to regenerate static content nightly:

  // app/Console/Kernel.php
  protected function schedule(Schedule $schedule) {
      $schedule->command('kiwa:generate')->daily();
  }
  

2. Dynamic Routes with Static Output

• Pattern: Use route parameters to generate unique static pages:

  Kiwa::get('/blog/{slug}', function ($slug) {
      return Kiwa::view('blog.post', ['slug' => $slug]);
  });
  

• Production: Pre-generate all blog posts with a custom Artisan command:

  php artisan kiwa:generate --paths="blog/*"
  

3. Asset Management

• Pattern: Leverage Laravel Mix/Vite for assets, but serve them statically:

  // routes/web.php
  Kiwa::get('/css/app.css', function () {
      return file_get_contents(public_path('css/app.css'));
  });
  

• Tip: Use Kiwa::asset() helper for versioned assets:

  <link rel="stylesheet" href="{{ asset('css/app.css?v=1.0') }}">
  

4. Middleware for Static Sites

• Pattern: Apply middleware to routes (e.g., caching headers):

  Kiwa::get('/products', function () {
      return Kiwa::view('products');
  })->middleware(\Wirbelwild\Kiwa\Core\Middleware\CacheHeaders::class);
  

5. API-Like Endpoints

• Use Case: Serve JSON data for SPAs or static site generation:

  Kiwa::get('/api/posts', function () {
      return response()->json(['posts' => Post::all()->toArray()]);
  });
  

• Tip: Cache API responses with CacheHeaders middleware.

Gotchas and Tips

Pitfalls

1. Twig Auto-Reloading

   • Issue: Twig templates aren’t auto-reloaded in production after kiwa:generate.
   • Fix: Clear the cache and regenerate:

     php artisan cache:clear && php artisan kiwa:generate
     

2. Route Caching Conflicts

   • Issue: Laravel’s route caching may override Kiwa’s static routes.
   • Fix: Disable Laravel’s route cache or use Kiwa’s generate command before deploying.

3. Asset Paths in Production

   • Issue: Hardcoded asset paths (e.g., /css/app.css) break if the site root changes.
   • Fix: Use Kiwa::asset() helper or configure asset_url in kiwa.php.

4. Dynamic Content in Static Pages

   • Issue: Mixing dynamic data (e.g., user sessions) with static generation.
   • Tip: Use Kiwa for static content and Laravel’s traditional routes for dynamic parts, then merge them.

Debugging

• Enable Debug Mode:

  // config/kiwa.php
  'debug' => env('APP_DEBUG', false),
  

  This shows Twig errors and route debug info.

• Check Generated Files:

  php artisan kiwa:generate --dry-run
  

  Lists files that would be generated without writing them.

Extension Points

1. Custom Template Engines

   • Extend Wirbelwild\Kiwa\Core\Engines\EngineInterface to support other templating languages (e.g., Blade).

2. Pre-Generation Hooks

   • Override KiwaServiceProvider::boot() to add logic before static generation:

     public function boot() {
         Kiwa::extend('pre_generate', function () {
             // Pre-process data (e.g., fetch latest blog posts)
         });
     }
     

3. Custom Storage Adapter

   • Implement Wirbelwild\Kiwa\Core\Storage\StorageInterface to write static files to S3, etc.

4. Middleware for Static Validation

   • Create middleware to validate static HTML (e.g., check for broken links) during generation:

     Kiwa::get('/validate', function () {
         return Kiwa::view('home')->middleware(ValidateStaticLinks::class);
     });