omz13 / kirby3-wellknown
kirby3 plugin to suport well-known files
Installs: 5 242
Dependents: 2
Suggesters: 1
Security: 0
Stars: 12
Watchers: 3
Forks: 0
Open Issues: 5
Type:kirby-plugin
Requires
- php: >=7.1
- getkirby/composer-installer: ^1.1
Requires (Dev)
- getkirby/cms: ^3.0.1
- jakub-onderka/php-parallel-lint: ^1.0
- localheinz/composer-normalize: ^1.0.0
- omz13/omz13-coding-standard: dev-master
- phpcompatibility/php-compatibility: ^8.2
- phpmd/phpmd: ^2.6
- phpstan/phpstan: ^0.10.3
- phpstan/phpstan-strict-rules: ^0.10.1
- roave/security-advisories: dev-master
This package is auto-updated.
Last update: 2022-12-19 01:14:32 UTC
README
Requirement: Kirby 3 (3.0 RC2 or better)
Coffee, Beer, etc.
This started as a simple plugin. The idea was to have a nice way to set some text files that live in the .well-known
folder. During development I had endless hours disappearing down the rabbit hole that is the specifications for the different files that could exist there. I have held back and kept this plugin deliberately simple, and hope that you do use it because providing these well-known files is a good thing to do. Under-the-hood it has some complicated code to make this really easy for the user. It also generates /robots.txt
because I just needed an excuse to integrate with my omz13/kirby3-xmlsitemap plugin. It also has a built-in blueprint because I wanted to waste hours of time getting this to work (and I'm still not sure why that took me some long: perhaps I have no idea what I am doing and eventually hit on the magic incantation within the code by random luck of hitting the keyboard enough times? Did Bastian fix something in Kirby? Were my MAMP settings wrong? Who cares because it now works and it is really cool. There are now no spelling mistakes in this README now that I have tweaked my code editor (Atom) to spellcheck.
This plugin is free but if you use it in a commercial project to show your support you are welcome to:
Documentation
Purpose
For a kirby3 site, this plugin omz13/wellknown allows easy configuration and provision of well-known and other highly-useful files (viz. robots.txt
)
When would you use this plugin?
- to provide .well-known/security.txt
- to provide a dnt-policy such as .well-known/dnt-policy
- to provide .well-known/humans.txt
- to provide any other (text-based) file in the
.well-known
folder. - to provide /robots.txt.
The functional specification:
- The contents for a well-known file are derived from, in order of priority, an entry from a configuration file, c.f.
site/config/config.php
, or a field incontent/site.txt
. - For
robots.txt
file, thesitemap
content is automatically generated (i.e. interacts with omz13/kirby3-xmlsitemap) and prepended to whatever else you want.
Roadmap
The non-binding list of planned features and implementation notes are:
- MVP
- favicon
- blueprints
- debug headers only in debug mode
Installation
Pick one of the following per your epistemological model:
composer require omz13/kirby3-wellknown
; the plugin will automagically appear insite/plugins
.- Download a zip of the latest release - master.zip - and copy the contents to your
site/plugins/kirby3-wellknown
. git submodule add https://github.com/omz13/kirby3-wellknown.git site/plugins/kirby3-wellknown
.
Configuration
The following mechanisms can be used to modify the plugin's behavior.
via site/config/config.php
-
omz13.wellknown.disable
- optional - defaultfalse
- a boolean which, iftrue
, disables the plugin. -
omz13.wellknown.notfound
- optional - defaulttrue
- a boolean which, iftrue
, causes the plugin to respond with a simple404
instead of the default kirby error page for requests to any files that are not configured. -
omz13.wellknown.not-txt-notfound
- optional - defaulttrue
- a boolean which, iftrue
, causes the plugin to respond with a simple404
instead of the default kirby error page for all requests to.well-known\file.ext
where ext is not atxt
. -
omz13.wellknown.fromSite
- optional - defaultfalse
- a boolean which, iftrue
, causes the content for a well-known file from the site file (content/Site.txt
which is set by the panel viablueprint/site.yml
) to be used in preference to that from the configuration file (site/config/config.php
). Wow. That was a complicated. In other words, if this istrue
, the user can specify the content in the panel, but if false the content can only be specified in the configuration file (for those times when you do not want a user to be able to change things). -
omz13.wellknown.the-XXXX
- optional - a string which provides the content for a request to.well-known/XXXX.txt
(orthe-robots
for/robots.txt
). Note that hyphens are ignored (e.g.dnt-policy
would be specified asomz13.wellknown.the-dntpolicy
). Additionally, line expansion is performed (i.e. any occurrences of\n
will be replaced by a newline). -
omz13.wellknown.x-ping
- optional - iftrue
, then any request to/.well-known/ping.txt
will return a very boring and vanilla response ofpong
. Why would you use this? Because it is a very sweet endpoint to test against to see if your site is alive.
Content fields in content/site.txt
(via blueprint blueprint/site.yml
)
The plugin uses the following content fields. These are all optional; if missing or empty, they are assumed to be not applicable vis-à-via their indicated functionality.
wellknownXXXX
- text - optional - content to provide for well-known fileXXXX.txt
. Note that hyphens are ignored (e.g. the well-known filednt-policy.txt
would be specified as fieldwellknowndntpolicy
.)
Blueprints
This plugin provides the following built-in blueprints (e.g. to make adding fields into the panel's blueprint blueprint/site.yml
easier):
omz13/wellknown
- to be used as anextends
to make entering data forrobots.txt
,security.txt
,dnt-policy.txt
, andhumans.txt
, as easy as:
HeadlineWellKnown: type: headline label: well-known numbered: false TheWellKnown: extends: omz13/wellknown
Hint: If you want to see what is in this blueprint, look in the source code under the blueprints
folder.
Use
-
Configure as above.
-
Use a web browser or whatever to access the well-known files.
-
If it works, see Coffee, Beer, etc above
-
If it doesn't work... file an issue and I will bang my head against the wall while I fix things; or perhaps I'll just sulk, have a cup of really stong coffee, and the got fix thing.
-
Be amazed how my README are either more funny or less funny with each push to the repo; YMMV.
Debug mode
If the kirby site is in debug mode:
- Page requests to any well-known files will have a header
x-omz13-wk
that contains debugging information.
Disclaimer
This plugin is provided "as is" with no guarantee. Use it at your own risk and always test it yourself before using it in a production environment. If you find any issues, please create a new issue.