pushword/flat-file

Transform Pushword in a FlatFile CMS.

1.0.0-rc153 2025-11-17 15:42 UTC

Requires

• league/csv: ^9.0
• pushword/core: *
• spatie/yaml-front-matter: ^2.0

MIT

• Robin@PiedWeb

README

Transform Pushword in a FlatFile CMS.

Documentation

Visit pushword.piedweb.com

Contributing

If you're interested in contributing to Pushword, please read our contributing docs before submitting a pull request.

Credits

• PiedWeb
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

Schéma du flux pw:flat:sync

flowchart TD
    Start([Commande: pw:flat:sync]) --> Check{FlatFileSync.mustImport}

    Check -->|Fichiers plus récents que DB| Import[IMPORT: Fichiers → Base de données]
    Check -->|DB plus récente ou pas de fichiers| Export[EXPORT: Base de données → Fichiers]

    %% BRANCHE IMPORT
    Import --> ImportMedia1[1. Import médias depuis mediaDir]
    ImportMedia1 --> ImportMedia1Finish[finishImport médias]
    ImportMedia1Finish --> ImportMedia2[2. Import médias depuis contentDir/media]
    ImportMedia2 --> ImportMedia2Finish[finishImport médias]
    ImportMedia2Finish --> ImportPages[3. Import pages depuis contentDir]
    ImportPages --> ImportPagesFinish[finishImport pages]

    ImportPagesFinish --> ImportProcess[Pour chaque fichier .md]
    ImportProcess --> ImportCheck{Page existe en DB?}
    ImportCheck -->|Non| ImportCreate[Créer nouvelle Page]
    ImportCheck -->|Oui| ImportCompare{Fichier plus récent?}
    ImportCompare -->|Oui| ImportUpdate[Mettre à jour Page]
    ImportCompare -->|Non| ImportSkip[Ignorer]
    ImportCreate --> ImportFlush[Flush DB]
    ImportUpdate --> ImportFlush
    ImportSkip --> ImportFlush
    ImportFlush --> ImportLinks[Convertir liens markdown relatifs en slugs]
    ImportLinks --> ImportRelations[Traiter relations parentPage, mainImage, etc.]
    ImportRelations --> ImportEnd[Import terminé]

    %% BRANCHE EXPORT
    Export --> ExportPages[1. Exporter toutes les pages]
    ExportPages --> ExportPageLoop[Pour chaque Page en DB]
    ExportPageLoop --> ExportPageCheck{Fichier existe et plus récent?}
    ExportPageCheck -->|Oui et pas --force| ExportPageSkip[Ignorer]
    ExportPageCheck -->|Non ou --force| ExportPageWrite[Écrire .md avec front matter YAML]
    ExportPageSkip --> ExportMedias
    ExportPageWrite --> ExportMedias[2. Exporter tous les médias]

    ExportMedias --> ExportMediaLoop[Pour chaque Media en DB]
    ExportMediaLoop --> ExportMediaYaml[Écrire .yaml avec métadonnées]
    ExportMediaYaml --> ExportMediaCopy{CopyMedia configuré?}
    ExportMediaCopy -->|Oui| ExportMediaCopyFile[Copier fichier média]
    ExportMediaCopy -->|Non| ExportEnd
    ExportMediaCopyFile --> ExportEnd[Export terminé]

    ImportEnd --> End([Fin])
    ExportEnd --> End

    style Start fill:#e1f5ff
    style Import fill:#fff4e1
    style Export fill:#e1ffe1
    style ImportEnd fill:#d4edda
    style ExportEnd fill:#d4edda
    style End fill:#e1f5ff

Loading

Détails du processus

Décision Import/Export

La méthode FlatFileSync->mustImport() détermine la direction :

• Scanne récursivement le répertoire de contenu
• Pour chaque fichier .md, compare filemtime() avec Page->getUpdatedAt()
• Si un fichier est plus récent que sa page en DB → IMPORT
• Sinon → EXPORT

Import (Fichiers → DB)

1. Import médias globaux (mediaDir)

   • Parcourt récursivement le répertoire
   • Pour chaque fichier : vérifie si plus récent que Media->getUpdatedAt()
   • Met à jour ou crée l'entité Media
   • Lit les métadonnées depuis .yaml ou .json (deprecated) si présents

2. Import médias locaux (contentDir/media)

   • Même processus pour les médias spécifiques au contenu

3. Import pages (contentDir)

   • Parse chaque fichier .md avec front matter YAML
   • Extrait le slug (depuis front matter ou nom de fichier)
   • Met à jour ou crée l'entité Page
   • Convertit les liens markdown relatifs en slugs absolus
   • Traite les relations (parentPage, mainImage, translations, etc.)

Export (DB → Fichiers)

1. Export pages

   • Pour chaque Page en DB :
     • Vérifie si le fichier .md existe et est plus récent (sauf avec --force)
     • Génère le front matter YAML avec toutes les propriétés
     • Écrit le fichier {slug}.md

2. Export médias

   • Pour chaque Media en DB :
     • Écrit un fichier .yaml avec les métadonnées
     • Si copyMedia est configuré, copie également le fichier média