Considerations Regarding Simplifications of Saaze

· klm's blog

Original post is here: eklausmeier.goip.de

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:

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