CLI usage

[fvsch]

Priority is having a 1.0 / 1.x that works well for generating a static site when visiting a particular route. But an alternative command-line tool could be nice.

• Maybe with the option to enable the CLI or enable the HTTP action separately?
• Should it use a custom script, e.g. php site/plugins/staticbuilder/cli.php [params]?
• Or maybe extend the Kirby CLI if that becomes possible at some point?

[mogelbrod]

I've written a proof-of-concept CLI for this plugin. It's separated from the kirby CLI and pretty rough, but seems to work fine overall.

The fork also adds support to build additional routes (needed to build sitemap.xml in my case) along with domain URL replacement. The latter is a quick and dirty search and replace to avoid uploading the built content to a separate host.

All changes needs polish or re-thinking, but I figured I'd share it here in case anyone found it interesting.

[fvsch]

Thanks for sharing, @mogelbrod. I don’t know much about CLI usage for PHP scripts so if I decide to implement it separately I’ll probably use some of your code.

Alternatively if you’d like to contribute an implementation that could be great, but I think I might have a few requirements like not adding to the Builder class if it’s not necessary, and perhaps making a templates/cli.php template for all/most of the output (if that makes sense… that was my plan but not sure it’s relevant).

I opened issues for the two other topics you mentioned:

• Routes: Build pages for specific routes (from user config) #11
• For URL rewriting: Figure out: relative URLs, page files, URL Rewriting etc. #14 (I think the issue is more general and it’s my top priority)

I don’t have much experience with managing an open-source project, however small, but if by chance you’d like to be a direct contributor that could be great. Tell me if you’re interested.

[mogelbrod]

It was my first time writing a PHP CLI script as well as the first time in years I wrote something in PHP, so the code might not be idiomatic PHP :)

I'll happily take a look at any issues/possible improvements with the CLI script you can find. The ones I've thought of are:

1. Fewer required arguments: Make kirby-root and site.php arguments optional arguments provided by --kirby and --config or similar. Would be possible to check if the kirby directory or site.php is located in cwd.
2. Addition of itemCallback: It's not necessary for the CLI script to work, but logging progress is important for a CLI in my opinion and I couldn't think of another way that wasn't too complicated. Could be refactored into a generic hook interface similar to how Kirby does it.
3. Argument parsing implementation: I didn't feel like adding an external dependency and therefore just went with something basic. To implement point 1) the parsing would have to support -- args with values.
4. Better handling of errors: Both PHP errors and process exit code when parts of the build fail (building on the current if (isset($stats['missing'])) exit(2);).
5. Logging/output: The $log function is kinda ugly. I don't necessarily agree on moving script output to templates/*.php however. There are multiple snippets that could be logged (result of an item being built, "header", "footer") which would either require multiple template files or a single cli.php which defines functions for each snippet, and by then it's no longer a template.
6. Avoiding headers already sent warnings: $kirby->launch() sends headers, and if the CLI outputs anything beforehand PHP will warn about it.
7. Script name: Maybe rename to cli.php? Not much of a interface though since it only serves one purpose - which is building.

I would love some feedback regarding these points, along with any additional issues you've got. I'll send a PR for the CLI if/when all required things are fixed.

In any case I'll keep working on my fork (will be used to deploy a static site at work), so feel free to grab any code you find useful :)

[fvsch]

…as well as the first time in years I wrote something in PHP, so the code might not be idiomatic PHP :)

You and me both. 😁

Agreed for the template part.

For the script name I wonder if it would be possible to call plugins/staticbuilder/staticbuilder.php and do a context switch to either do what it currently does or require and start core/cli.php.
Since the CLI script has to bootstrap Kirby itself, you could look at https://gist.github.com/bastianallgeier/5f182b30d4c90152b468 which does that (not sure if everything is necessary).

Headers already sent: maybe that's because you run $kirby->launch(), which will probably try to render a HTML page, send its HTTP headers etc.? See the previous point for how Bastian did it.

itemCallback: maybe the instances of $this->summary[] = $log; could be replaced by a log method ($this->log($log);) and that method would store to $this->summary and optionally send the logged array to your code. That last part could be done with a hook, if there's no better idea.

Argument parsing: if at some point we can reimplement on top of Kirby's cli (which uses some good PHP libs for console stuff), it won't be a problem. In the meantime, I'd keep things simple.

For the path to Kirby's bootstrap.php, maybe it should default to __DIR__ . '/../../../kirby/bootstrap.php'. Or mandate that the script is always ran from the root of the project and use [CWD]/kirby/bootstrap.php. Kirby's CLI (https://github.com/getkirby/cli) already does that.

To be consistent with the HTTP version, maybe the script should run in dry-run mode by default, and require a specific flag or command to actually write files?

Finally, when building several pages, you could use $builder->write() and pass it a page collection, instead of using a foreach.

[mogelbrod]

Script name: PHP unfortunately outputs the shebang in the browser, so using the same file as entrypoint for both CLI and browser isn't possible unless dropping it. I like the idea though. Naming it cli.php might suffice for now.

Headers already sent: Replaced the launch() call with the necessary calls inside it, good catch.

Reporting: Sounds good, either log($item) or report($item). $this->summary can be dropped altogether in favor for clients listening to report events like my CLI implementation does it. Adding a hook/trigger implementation feels a bit heavy for a single hook though.

Argument parsing/default paths: Sounds reasonable. I modified the script look in the cwd by default. Enabling basic option value parsing was easy enough; mogelbrod/kirby-staticbuilder@1c4e856

Dry-run by default: I went all the way and converted the script into an actual CLI instead; mogelbrod/kirby-staticbuilder@8f7b622

Page collection: Good idea; mogelbrod/kirby-staticbuilder@91b0689

[fvsch]

Closing feature requests as described in #40.