Jekyll Provider Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Monolithic vs. Microservices: The package is a Symfony Bundle (Laravel-compatible via Symfony Bridge), meaning it’s designed for integration into a monolithic PHP application (or a Laravel app using Symfony components). If the target system is a headless CMS or decoupled architecture, this bundle may introduce unnecessary coupling between PHP backend and static site generation (Jekyll).
• Static Site Generation (SSG) Alignment: The bundle abstracts Jekyll integration, which is a Ruby-based SSG tool. This introduces a foreign dependency (Ruby/Jekyll) into a PHP stack, requiring additional tooling (Docker, CI/CD pipelines) for cross-language compatibility.
• Use Case Fit:
  • Good Fit: If the product requires dynamic PHP backend + static Jekyll frontend (e.g., blog with user-generated content + static pages).
  • Poor Fit: If the system is fully dynamic (no static pages) or already uses a PHP-based SSG (e.g., Laravel + Vite/Inertia).

Integration Feasibility

• Symfony Compatibility: Laravel (v8+) has partial Symfony compatibility, but this bundle assumes a full Symfony ecosystem (e.g., dependency injection, event system). Potential friction points:
  • Laravel’s service container differs from Symfony’s in some areas (e.g., autowiring, configuration).
  • Configuration structure may not align with Laravel’s config/ conventions.
• Jekyll Dependency:
  • Requires Ruby and Jekyll installed (either locally or in CI/CD).
  • Build process must be orchestrated (e.g., triggering Jekyll builds on content changes).
• Database vs. Filesystem:
  • Jekyll operates on Markdown files, while Laravel typically uses a database. The bundle must bridge these (e.g., syncing Laravel models to Jekyll’s _posts/ structure).

Technical Risk

Key Questions

1. Why Jekyll?
   • Is there a specific feature (e.g., plugins, theming) that justifies Ruby over PHP-based SSG (e.g., Laravel + Markdown parsing)?
   • Could Laravel + Vite + Markdown-it achieve the same goal without Ruby?
2. Deployment Model
   • Will Jekyll run locally (dev) and in CI/CD (prod), or is it embedded in the PHP stack?
   • How will content sync between Laravel (DB) and Jekyll (files) be handled?
3. Team Expertise
   • Does the team have Ruby/Jekyll experience? If not, will this introduce a learning curve?
4. Alternatives
   • Has Laravel’s ecosystem (e.g., spatie/laravel-markdown, tightenco/ziggy for static routes) been considered?
   • Would a headless CMS (e.g., Strapi, Directus) be a better fit for dynamic + static content?

Integration Approach

Stack Fit

• Compatible Stack:
  • Laravel v8+ (Symfony 5+ compatibility).
  • Ruby 3.x + Jekyll 4.x (required for the bundle).
  • Docker (recommended for isolating Ruby dependencies).
  • CI/CD: GitHub Actions/GitLab CI with Ruby/Jekyll steps.
• Incompatible Stack:
  • Lumen (micro-framework, lacks Symfony features).
  • Pure PHP SSG (e.g., Parsedown, PHP-Markdown).
  • Serverless (Jekyll’s build process may not fit FaaS models).

Migration Path

1. Assessment Phase
   • Audit existing content structure (DB vs. files).
   • Define static vs. dynamic content boundaries.
2. Proof of Concept (PoC)
   • Set up a Dockerized Jekyll instance.
   • Test Laravel ↔ Jekyll content sync (e.g., export DB posts to Markdown).
   • Verify Symfony Bundle compatibility in Laravel (may require shims).
3. Incremental Rollout
   • Phase 1: Static pages (e.g., /blog) generated by Jekyll, served via Laravel’s web server.
   • Phase 2: Dynamic content (e.g., user profiles) served via Laravel API, static content via Jekyll.
   • Phase 3: Full hybrid mode (e.g., Jekyll for marketing pages, Laravel for user dashboards).

Compatibility

• Configuration:
  • The bundle uses Symfony’s YAML/XML config. Laravel uses config/. Solution:
    • Create a Laravel config publisher to convert Symfony configs to Laravel’s format.
    • Use environment variables for critical settings (e.g., Jekyll source path).
• Dependency Injection:
  • Laravel’s container may need custom bindings for Symfony services (e.g., BloghovenJekyllProvider).
• Routing:
  • Jekyll generates static routes. Laravel must avoid conflicts (e.g., use Route::prefix('api') for dynamic routes).

Sequencing

1. Setup Ruby/Jekyll Environment
   • Dockerfile:

     FROM ruby:3.2
     RUN gem install jekyll bundler
     COPY Gemfile Gemfile.lock ./
     RUN bundle install
     

2. Integrate Bundle
   • Composer: composer require bloghoven/jekyll-provider-bundle.
   • Laravel Service Provider:

     use Bloghoven\JekyllProviderBundle\BloghovenJekyllProviderBundle;
     
     class JekyllServiceProvider extends ServiceProvider {
         public function register() {
             $this->app->register(BloghovenJekyllProviderBundle::class);
         }
     }
     

3. Configure Content Sync
   • Example: Use a Laravel command to export DB posts to Jekyll’s _posts/:

     Post::all()->each(function ($post) {
         File::put(
             storage_path('jekyll/_posts/' . $post->slug . '.md'),
             "---\ntitle: {$post->title}\ndate: {$post->published_at}\n---\n{$post->content}"
         );
     });
     

4. Automate Builds
   • GitHub Actions:

     - name: Build Jekyll
       run: |
         docker run --rm -v $(pwd)/storage/jekyll:/srv/jekyll jekyll/jekyll:latest jekyll build
     

5. Serve Static Files
   • Configure Laravel’s web server (Nginx/Apache) to serve storage/jekyll/_site/ at /blog.

Operational Impact

Maintenance

• Ruby Dependencies:
  • Pros: Jekyll is stable; updates are managed via Gemfile.
  • Cons: Ruby versioning may conflict with other services (e.g., Rails apps).
• PHP Dependencies:
  • Bundle may require Symfony polyfills in Laravel, increasing maintenance.
• Content Management:
  • Double-editing risk: Content must be maintained in both DB (Laravel) and Markdown (Jekyll).
  • Solution: Implement a CMS-like UI (e.g., Laravel Nova/Telescope) for Markdown editing.

Support

• Debugging Complexity:
  • Issues may span PHP (Laravel) and Ruby (Jekyll), requiring cross-language debugging.
  • Example: A broken Markdown template could manifest as a 500 error in Laravel (if routes conflict).
• Vendor Lock-in:
  • Low-star package with no active maintenance (last commit: ?). Risk of abandonware.
  • Mitigation: Fork the bundle and submit changes upstream.

Scaling

• Performance:
  • Jekyll builds are CPU-intensive. For large sites:
    • Use incremental builds (Jekyll’s --incremental flag).
    • Offload builds to a separate service (e.g., AWS Lambda + EFS).
• Traffic Spikes:
  • Static files (Jekyll) scale well, but dynamic content (Laravel) may bottleneck.
  • Solution: Use CDN (e.g., Cloudflare) for static assets.

Failure Modes

|