Blosxom Dir Provider Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require bloghoven/blosxom-dir-provider-bundle
   

   Enable the bundle in config/bundles.php:

   Bloghoven\BlosxomDirProviderBundle\BlosxomDirProviderBundle::class => ['all' => true],
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="Bloghoven\BlosxomDirProviderBundle\BlosxomDirProviderBundle" --tag="config"
   

   Update config/blosxom_dir_provider.php with your directory structure:

   'directories' => [
       'posts' => [
           'path' => storage_path('app/posts'),
           'format' => 'Y-m-d-His', // Optional: Date format for filenames
       ],
   ],
   

3. First Use Case Inject the provider into a controller/service:

   use Bloghoven\BlosxomDirProviderBundle\Service\BlosxomDirProvider;
   
   public function __construct(private BlosxomDirProvider $blosxomDirProvider) {}
   
   public function listPosts() {
       $posts = $this->blosxomDirProvider->getPosts();
       return view('posts.index', compact('posts'));
   }
   

Implementation Patterns

Directory-Based Workflow

1. File Naming Convention Use consistent filenames (e.g., 2023-10-15-1430-post-title.md) to leverage the provider’s auto-parsing:

   // Automatically parsed from filename
   $post = $this->blosxomDirProvider->getPost('2023-10-15-1430-post-title');
   

2. Integration with Laravel Filesystem Combine with Laravel’s Storage facade for cross-platform paths:

   $path = storage_path('app/posts/' . $post->filename);
   if (Storage::exists($path)) { ... }
   

3. Front Matter Support Use YAML front matter in Markdown files for metadata:

   ---
   title: My Post
   tags: [laravel, php]
   ---
   # Content...
   

   Access via:

   $metadata = $this->blosxomDirProvider->getPostMetadata($filename);
   

Common Patterns

• Dynamic Routing Register routes dynamically based on directory contents:

  Route::get('/posts/{filename}', [PostController::class, 'show'])
       ->where('filename', '.*');
  

• Caching Posts Cache parsed posts to avoid repeated filesystem reads:

  $posts = Cache::remember('blosxom_posts', now()->addHours(1), function() {
      return $this->blosxomDirProvider->getPosts();
  });
  

• Event-Driven Updates Listen for file changes (e.g., using laravel-filemanager or spatie/laravel-activitylog) to trigger post updates.

Gotchas and Tips

Pitfalls

1. Case Sensitivity Filesystem paths are case-sensitive on Linux. Ensure consistent naming:

   // Avoid:
   $this->blosxomDirProvider->getPost('Post-Title.md'); // Fails if stored as 'post-title.md'
   

2. Missing Front Matter If a Markdown file lacks YAML front matter, metadata will be null. Validate files:

   if (empty($post->metadata->title)) {
       throw new \InvalidArgumentException("Missing title in front matter.");
   }
   

3. Permission Issues Ensure the Laravel storage directory is writable:

   chmod -R 755 storage/app/posts
   

Debugging

• Log File Paths Add debug logs for file paths:

  \Log::debug('Post path:', [$post->path]);
  

• Validate Config Check config/blosxom_dir_provider.php for typos in directory paths or formats.

Extension Points

1. Custom Metadata Parsing Extend the provider by overriding the parseFrontMatter() method in a service binding:

   $this->app->bind(BlosxomDirProvider::class, function($app) {
       return new CustomBlosxomDirProvider($app['config']);
   });
   

2. Add File Filters Filter files by extension or custom logic:

   $this->blosxomDirProvider->setFileFilter(function($file) {
       return str_ends_with($file, '.md') && !str_contains($file, 'draft-');
   });
   

3. Integrate with Markdown Parsers Use spatie/laravel-markdown to render content:

   use Spatie\Markdown\MarkdownRenderer;
   
   $renderer = app(MarkdownRenderer::class);
   $content = $renderer->toHtml($post->content);