Browse Source

Updated the whole doc

master
Diane 1 year ago
parent
commit
21b3ca91df
No known key found for this signature in database GPG Key ID: B13153D92467FCC1
  1. 100
      README.md

100
README.md

@ -2,27 +2,97 @@
My blog.
## Requirements
- PHP 7.3+
- Composer
- PDO
- PDO PgSQL
- PostgreSQL 11+
## Set up a local work environment
My environment is based on Apache, and is made to flawlessly work with that.
I have no example configuration for anything else than Apache / PHP.
### Requirements
- Apache 2.4+
- mod_rewrite
- mod_php7
- mod_env: not required, but highly recommended to set once and never again environment variables.
### Project setup
```
$ git clone https://git.sr.ht/~artemis/artemix.org
$ cd artemix.org
$ composer install
```
Now, you need to point your `DocumentRoot` to `artemix.org/public`.
You should define the environment variables for `DB_DSN` and `AUTH_TOKEN`.
- `DB_DSN` will be the PostgreSQL connection string, see the [PDO][pdo] docs on how to create it
- `AUTH_TOKEN` will be used for authenticating the blog's owner on `/admin`.
It can be generated by entering `php artemis.php new:key` and answering prompted questions.
[pdo]: https://www.php.net/manual/en/ref.pdo-pgsql.connection.php
### Database setup
Once you've configured your environment, you'll have to set up the database tables.
To do that, run `vendor/bin/phinx migrate`, which will create the database.
You're all set!
## Architecture
- `gulpfile.ts`: Entry-point for building
- `builder/`: Static site generator
- `tasks/`: Every gulp async task to be used in the `gulpfile.ts`
- `apps/`: Every web-app based on `artemix.org`
- `search/`: `search.html` web app
- `db/`: Migrations, as handled by phinx (may change for something simpler in the future)
- `public/`: Entrypoint, static resources (e.g. icons)
- `index.php`: Every request's entry point. It may be useful to read it to get
a hang on what's happening on every request.
- `assets/`: Every asset should be stored here
- `gpg/`: The public ASC keys should be stored here
- `resources/`: HTML page templates and base resources that need to be built (CSS / JS)
- `assets/`: base CSS and javascript that will need to be built, if changed
- `templates/`: HTML page templates, in the twig templating format
- `src/`: The website's source code
- `Actions/`: Every HTTP request handler, this is what's referenced in `routes.php`
- `Commands/`: Every CLI command (which must be registered in `artemis.php` to be usable)
- `Helpers/`: Basic PHP helper functions, to make a dev's life easier
- `Services/`: OOP service classes, this contains the core backend logic
- `Renderers/`: A series of classes made to provide a simpler interface to render common HTML documents
- `Repositories/`: A series of classes made to provide an interface to interact with the database in a SRP-compliant way
- `Types/`: Basic PHP data classes to help dealing with a few types
- `Action.php`: HTTP request handler (action) interface
- `Command.php`: CLI command handler interface
- `ParsedownExtended.php`: Custom snippet that wraps Parsedown as dependency. Just stupidly located
- `Runner.php`: Core class containing all the logic required to bootstrap the request handling system
- `artemis.php`: The CLI tool, which allows to minify base resources and create keys
- `config.php`: The configuration file, which contains environment-agnostic and non-secret data
- `routes.php`: The configuration file, which contains every defined Siler route
## How to work in development
### Notes
To develop the static website / static site generator, you only need the local dependencies.
The website doesn't have a concept of "middleware", but instead relies on two mechanisms to run preliminary checks
(such as the authentication guard, to make sure only authorized users can access the admin panel).
Run `yarn`, then `yarn watch` to start working.
1. A "route" in siler's way is simply a code snippet that will be invoked on URI match.
If a route `A` executes on `/a`, and a route `B` executes on `/a/b`, having the router set up as `['A', 'B']` will
execute the actions for `A`, *then* `B`.
2. This mechanism has been extended with one concept: continue / breaks. If an action's `__invoke` method returns the boolean value `false` (and nothing else), the router won't continue to try to match actions.
To develop a web-app, you need a built version of the latest `artemix.org` website.
...
To obtain that, run `yarn` then `npx gulp prepareForDev`.
The website **heavily** relies on [PHP-DI](http://php-di.org/) to provide access to any instance from actions.
It is *strongly* advised to get to understand the logic dealt by the `Runner::__construct` and `Runner::http`
methods before starting to dig further into the code.
## TODO
...
- redesign the inline `<code></code>` block to be clearer
- implement per-directory grouping of articles
- try to add support for asciidoc
- reindent every app
You should *never* interact with the database directly from an Action (by injecting the `Database` service),
but you should instead create a repository that will wrap the database access request logic into clear and simple
PHP methods.
Loading…
Cancel
Save