, 3 min read

Considerations Regarding Simplifications of Saaze

Original post is here eklausmeier.goip.de/blog/2021/09-02-considerations-regarding-simplifications-of-saaze.


This blog is built using a static-site generator called Saaze. Saaze can also serve content fully dynamic. Saaze is kind of the successor of Handle. Saaze and Handle were both written by Gilbert Pellegrom.

Saaze has the following objectives:

  1. Easy to run
  2. Easy to host
  3. Easy to edit
  4. Easy to theme
  5. Fast and secure
  6. Simple to understand and use, simple to extend

Objectives 1 to 5 are based on the fact that all data is kept in files and Saaze is a static-site generator.

The last objective was particular appealing to me. Nevertheless, the source code of Saaze has accumulated a number of irritations:

  1. Too many dependencies to other PHP packages, and dependencies which carry a couple of actual bugs
  2. Dependencies force PHP 7: "ralouphie/mimey 2.1.0 requires php ^5.4|^7.0 -> your php version (8.0.10) does not satisfy that requirement"; remedy: install PHP 7, install everything, then you can use PHP 8 ignoring this message
  3. Dependency trigger fatal error in webserver-log: "PHP Fatal error: Uncaught Illuminate\Contracts\Filesystem\FileNotFoundException"; luckily, this error can be ignored
  4. When using Saaze as a pure static-site generator: there is no incremental re-compilation of only those Markdown files, which have changed
  5. No "transparent sections", i.e., pages with all content for a year, or year-month, etc. For example, WordPress blogs all offer to list all posts for year, month, etc.
  6. Adding relative URLs to the source code often scratched the overly object-oriented approach
  7. The statically generated website (php saaze build) differs in behaviour from dynamic, on-the-fly generated website (php saaze serve)
  8. Overengineered regarding PHP interfaces and dependency-injection; single source-file in one directory for Routing and Templates
  9. Saaze commands, except build-command, are so skinny, that they can be downright removed from the source-code

Regarding dependencies and imported bugs:

  1. erusev/parsedown-extra: This Markdown parser has trouble with HTML tables, also it is not particularly fast. I corrected both with MD4C.
  2. spatie/yaml-front-matter: This YAML front-matter parser has trouble with multiple triple-dash strings (---). I corrected this with dropping spatie's code, and rewriting the functionality.

Regarding the number of dependencies. Saaze currently has the following dependencies according composer.json:

  1. adbario/php-dot-notation (*)
  2. erusev/parsedown-extra (*)
  3. jenssegers/blade
  4. php-di/php-di (*)
  5. ralouphie/mimey (*)
  6. spatie/yaml-front-matter (*)
  7. symfony/console (*)
  8. symfony/finder (*)
  9. symfony/http-foundation
  10. symfony/process
  11. symfony/routing
  12. symfony/yaml
  13. vlucas/phpdotenv (*)

Eight dependencies are marked with (*). I consider them to be unnecessary, i.e., they can easily be disposed.

Luckily, the source code is still relatively small and can be overseen:

~/php/vendor/saaze/core/src: wc `find . -iname \*.php`
   94   161  1710 ./Collections/Collection.php
   85   142  1921 ./Collections/CollectionManager.php
   18    29   368 ./Collections/CollectionParser.php
   65   181  2446 ./Commands/Make/MakeCollectionCommand.php
   22    47   463 ./Commands/Make/MakeCommand.php
   55   141  2051 ./Commands/Make/MakeEntryCommand.php
   87   244  2855 ./Commands/ServeCommand.php
  222   539  6988 ./Commands/BuildCommand.php
  121   246  3577 ./Container/Container.php
   20    31   391 ./Content/MarkdownContentParser.php
  205   446  5176 ./Entries/EntryManager.php
   55   188  1464 ./Entries/EntryParser.php
  152   304  3331 ./Entries/Entry.php
   48    98   786 ./Interfaces/CollectionInterface.php
   21    45   409 ./Interfaces/CollectionManagerInterface.php
   14    24   225 ./Interfaces/CollectionParserInterface.php
   14    27   227 ./Interfaces/ContentParserInterface.php
   65   135  1108 ./Interfaces/EntryInterface.php
   54   134  1206 ./Interfaces/EntryManagerInterface.php
   14    24   211 ./Interfaces/EntryParserInterface.php
   13    20   163 ./Interfaces/RouterInterface.php
   32    73   728 ./Interfaces/TemplateManagerInterface.php
   23    50   415 ./Interfaces/TemplateParserInterface.php
  164   351  5257 ./Routing/Router.php
   33    73   769 ./Templates/BladeTemplateParser.php
  110   232  3352 ./Templates/TemplateManager.php
   73   132  1250 ./helpers.php
   31    46   577 ./Saaze.php
   35    50   886 ./SaazeCli.php
 1945  4213 50310 total