Merge pull request #496 from leepeuker/add-developer-documentation

Add some documentation for interested developers

docs/development/database-migrations.md

@@ -0,0 +1,15 @@
+Movary uses [phinx](https://phinx.org/) to manage database migrations
+
+In order to create a new migration, run the following command:
+
+```php
+php vendor/bin/phinx create MyNewMigration -c ./settings/phinx.php
+```
+
+Make sure to use CamelCase, so the first character of your migration name has to be capitalized and preferably any words are capitalized as well. So in the name `my new migration`,
+the words begin with a capital letter and the spaces are removed.
+
+The `-c` parameter tells Phinx to use the configurations that are in `phinx.php`. To create a migration for MySQL, you'll have to update your `.env` file to `DATABASE_MODE=mysql`
+and set up the appropriate configuration (such as password, host, etc.) to connect to your MySQL database.
+
+To make a migration for SQlite3, you can update your `.env` file to `DATABASE_MODE=sqlite`.

docs/development/file-structure.md

@@ -0,0 +1,26 @@
+### Backend
+
+Most of the backend files are in the `/src` directory. The main `index.php` is in `/public`.
+
+Within the `/src` directory, various other directories are located.
+
+- `/src/Api` - Contains usage of external APIs (such as Trakt, Plex, Jellyfin, etc.)
+- `/src/Command` - Contains Movary CLI commands  (which can be executed via `php /bin/console.php`)
+- `/src/HttpController` - Contains files processing HTTP requests. Controllers and middleware are located here, for both the HTTP requests directed at the API and just the usual
+  web interface.
+- `/src/Service` - Contains core Movary components, such as the routing system, the processing of external API data and some other stuff. Note: The `/src/api` directory is mainly
+  meant for *connecting* with the external APIs and sending HTTP requests, whereas the external API stuff in `/src/Service` mainly handles how to process the data from those
+  external APIs.
+- `/src/Util` - Contains basic utility files to keep consistency throughout the project
+- `/src/Domain` - Contains the core Movary domain implementation, e.g. what is a movie in Movary (required movary and tmdb ids) or a watch date (required user and movary ids) and
+  how to create or delete those
+
+### Templates
+
+The frontend of Movary is mainly regular HTML5, but it also uses the [twig framework](https://twig.symfony.com/) from Symfony, to use dynamic templates. This allows us to use
+cleaner code when injecting PHP code in HTML. So instead of using `<?php echo $variable ?>`, we can now use `{{ $variable }}` and the twig engine will automatically translate the
+clean code into the PHP code. See their documentation for more information.
+
+### Frontend assets
+
+The CSS, Javascript and the images are located in `/public`.

docs/development/setup.md

@@ -0,0 +1,30 @@
+To set up a basic local development environment follow these steps:
+
+- run `cp .env.development.example .env` and edit the `.env` file to customize the local environment 
+- run `make build` to build the docker containers using compose and run all necessary steps for an initial setup like
+  - create the database
+  - install composer dependencies
+  - run database migrations
+  - create the storage symlink
+
+The application should be up-to-date and running locally now. 
+
+Use the following cli commands to manage your local environment:
+
+- run `make down` to stop all containers
+- run `make up` to start all containers again (`build` is only for the initial setup!)
+- run `make reup` to stop and restart all containers
+- run `make reup` to stop and restart all containers
+- run `make app_database_migrate` execute the database migrations
+- run `make app_jobs_process` process the next job from the queue (see database table `job_queue`)
+
+### Api docs
+
+Checkout the API docs via the url path `{your-movie-url}/docs/api`.
+
+This uses the schema defined in the file `/docs/openapi.json`
+
+### Useful links
+
+- [Trakt API docs](https://trakt.docs.apiary.io/)
+- [TMDB API docs](https://developers.themoviedb.org/3)

docs/development/structure.md

@@ -0,0 +1,75 @@
+### Routing
+
+When someone visits Movary, a request wil be sent to the Router, which is configured via `/settings/routes.php`.
+
+To add a new route, go to the file `settings/routes.php` and add this new line:
+
+```php
+$routes->add('<HTTP_METHOD>', '/your/url/path', [Web\Some\Controller::class, 'Method']);
+```
+
+Replace <HTTPMethod> with either `GET`, `POST`, `PUT` or `DELETE` and put this line of code in either the `addWebRoutes` function or the `addApiRoutes` function. It should be
+in `addWebRoutes` if it's a route that the user will be visiting on the website and in the `addApiRoutes` if it's not.
+
+Movary uses [FastRoute](https://github.com/nikic/FastRoute) to manage most of the routing stuff (only the middleware is added by us) and for more info, visit their git repo.
+
+### Middleware
+
+Middlewares are methods that check if the user is allowed to do this. For example, to check if someone is allowed to access the settings page, the middleware `UserIsAuthenticated`
+will be used and to check if the user is an admin, the middleware `UserIsAdmin` is used.
+
+All the middleware are in the namespace `Movary\HttpController\Web\Middleware` and use the interface `MiddlewareInterface`.
+
+#### Writing new middlewares
+
+To add new middlewares, first create a new file like `/src/HttpController/Web/Middleware/MyNewMiddleware.php`.
+
+Then copy-paste this in the new file:
+
+```php
+<?php declare(strict_types=1);
+
+namespace Movary\HttpController\Web\Middleware;
+
+class MyNewMiddleware implements MiddlewareInterface
+{
+    public function __invoke() : ?Response
+    {
+        // Add your own code here
+    }
+}
+```
+
+Change the class name and you're set to start writing your own middleware! The code in the `__invoke()` method is the code that will be executed if the middleware is added to a
+route and the route is visited by an user.
+
+#### Adding a new middleware to a route
+
+To add a middleware to a route, add the middleware class in an array to the `$routes->add()` method in a fourth parameter like this:
+
+```php
+$routes->add('<HTTPMETHOD>', '/your/url/path', [Web\Some\Controller::class, 'Method'], [Web\Middleware\MyNewMiddleware::class, Web\Middleware\MyNewMiddlewareTwo::class]);
+```
+
+### HTTP Controllers
+
+The HTTP controllers are all located in `/src/HttpController`. These are the methods that will be executed when the route is visited.
+
+The controllers for the website have the namespace `namespace Movary\HttpController\Web` and the API-related controllers have `namespace Movary\HttpController\Web`.
+
+### Data Transfer Objects (DTO)
+
+Data Transfer Objects (DTO) are frequently used in Movary and can be found throughout the whole backend.
+
+A DOT is used to transfer data between classes and processes in a statically defined typesafe manner (in opposite to for example arrays).
+
+For a different (perhaps better) explanation, visit this [Stackoverflow thread](https://stackoverflow.com/q/1051182/12096297)
+
+### Dependency injections, bootstrapping and the Factory
+
+The basic bootstrapping of the application is configured in the `bootstrap.php`. 
+
+The `bootstrap.php` will create and return a PSR7 confirm ContainerInterface, containing the dynamic and manually configured dependency wiring.
+This is loaded in the `public/index.php` when processing a HTTP request or in the `bin/console.php` when processing cli commands.
+
+If you need to wire a dependency manually (e.g. which implementation of an interface to use or depending on a scalar type) extend the definitions array in the `bootstrap.php` and create a factory method if necessary.

mkdocs.yml

@@ -46,5 +46,9 @@ nav:
       - Letterboxd: features/letterboxd.md
       - Trakt TV: features/trakt.md
       - Netflix: features/netflix.md
-  - Development: 'development.md'
+  - Development: 
+      - Setup: development/setup.md
+      - Directory structure: development/file-structure.md
+      - How does the backend work?: development/structure.md
+      - Database migrations: development/database-migrations.md
   - FAQ: 'faq.md'