Flat File Cms Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require checlou/flat-file-cms-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Checlou\FlatFileCMSBundle\CheclouFlatFileCMSBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console checlou:flat-file-cms:install
   

   Edit config/packages/checlou_flat_file_cms.yaml to define:

   • pages_directory: Path to your Markdown files (e.g., data/cms/pages/).
   • default_locale: Default language (e.g., en).

3. First Use Case Create a Markdown file (e.g., data/cms/pages/home.md):

   ---
   title: Home
   slug: home
   ---
   # Welcome to our site!
   This is a **Markdown** CMS page.
   

   Access it in a controller:

   use Checlou\FlatFileCMSBundle\Service\PageService;
   
   class PageController extends AbstractController
   {
       public function show(PageService $pageService)
       {
           $page = $pageService->getPage('home');
           return $this->render('page/show.html.twig', ['page' => $page]);
       }
   }
   

Implementation Patterns

Workflows

1. Page Management

   • Create/Update: Edit Markdown files directly in pages_directory.
   • Delete: Remove the file or set is_published: false in YAML frontmatter.
   • Preview: Use Twig to render raw content before publishing:

     {{ page.content|raw }}
     

2. Routing Dynamically generate routes in config/routes.yaml:

   checlou_flat_file_cms.page:
       path: /{slug}
       controller: Checlou\FlatFileCMSBundle\Controller\PageController::show
       methods: GET
   

3. Localization Organize files by locale (e.g., data/cms/pages/en/home.md, data/cms/pages/fr/home.md). Fetch pages with:

   $pageService->getPage('home', 'fr');
   

4. Templating Extend Twig with custom filters (e.g., markdown_to_html) or create reusable blocks:

   {% extends 'base.html.twig' %}
   {% block content %}
       {{ include('cms/page_content.html.twig', {'content': page.content}) }}
   {% endblock %}
   

5. Asset Handling Reference images/attachments in Markdown:

   ![Alt text](uploads/images/logo.png)
   

   Serve static files via Symfony’s asset system or a custom route.

Integration Tips

• Symfony Forms: Validate frontmatter fields (e.g., title, slug) with a custom form type.
• APIs: Expose pages via API Platform or a custom controller:

  $pageService->getAllPages(); // Returns array of Page objects
  

• Cache: Clear cache after file changes:

  php bin/console cache:clear
  

• Events: Listen for checlou_flat_file_cms.page.save to trigger post-save logic.

Gotchas and Tips

Pitfalls

1. File Permissions Ensure the pages_directory is writable by the web server:

   chmod -R 775 data/cms/
   

   Debug: Check storage/logs/dev.log for Permission denied errors.

2. Frontmatter Parsing

   • YAML frontmatter must be valid (e.g., no trailing commas).
   • Use YAML lint tools to validate.
   • Fix: Manually edit files or pre-process with a script.

3. Slug Conflicts

   • Slugs must be unique per locale.
   • Workaround: Append a suffix (e.g., home-v2) or use UUIDs.

4. Markdown Limitations

   • No native support for shortcodes or custom syntax.
   • Solution: Use Twig includes or pre-process Markdown with a library like league/commonmark.

5. Case Sensitivity

   • Slugs are case-sensitive in routes.
   • Tip: Normalize slugs in frontmatter (e.g., slug: "{{ slug|lower }}").

Debugging

• Missing Pages: Verify pages_directory path in config and file existence.
• Twig Errors: Check if content is rendered as raw Markdown (use |raw filter).
• Locale Fallback: Ensure default_locale is set in config.

Extension Points

1. Custom Fields Extend the Page entity or use a custom frontmatter parser:

   # config/packages/checlou_flat_file_cms.yaml
   checlou_flat_file_cms:
       custom_fields:
           - 'meta_title'
           - 'meta_description'
   

2. File Watcher Auto-reload pages on file changes (e.g., with Symfony’s FileSystemWatcher or a custom CLI command).

3. Media Library Integrate with VichUploaderBundle or Spatie Media Library for file attachments:

   ---
   attachments:
       - { path: 'uploads/docs/guide.pdf', label: 'User Guide' }
   ---
   

4. Revision History Use Git hooks or a database-backed system (e.g., Doctrine) to track changes.

Config Quirks

• Caching: Disable cache_enabled in config for development:

  checlou_flat_file_cms:
      cache_enabled: false
  

• File Extensions: Only .md files are parsed by default. Add support for .markdown in config:

  checlou_flat_file_cms:
      allowed_extensions: ['md', 'markdown']