README.md (8688B)
1 # Memory Backend 2 3 Een php/symfony applicatie om te gebruiken voor het opslaan van spelers en spellen van het javascript memory spel. Het is de bedoeling dat je *alleen* aan de frontend werkt. We hebben die backend juist gemaakt om de situatie te simuleren waarin je als developer geen mogelijkheid hebt om een deel van de applicatie (deze backend in dit geval) zelf aan te passen. Dat gezegd hebbende is het best mogelijk dat je dingen in de backend tegenkomt die echt beter moeten. We hebben dat ding redelijk snel in elkaar gezet, dus we doen geen enkele garantie over hoe goed het is. Het staat je dus zeker vrij om dit aan te passen en een pull-request te doen. 4 5 We maken bij deze applicatie gebruik van [de LexikJWTAuthenticationBundle](https://github.com/lexik/LexikJWTAuthenticationBundle). Bekijk eventueel de code om te onderzoeken hoe dat ding werkt. 6 7 ## Installatie en opstarten 8 9 Clone deze repository ergens op je lokale machine. Installeer vervolgens de dependencies met behulp van composer. De applicatie maakt gebruik van een sqlite3 database en doctrine. Pas eventueel de gegevens aan in de configuratie om een ander pad naar de database in te stellen. Tenslotte kun je met de console de corresponderende tabellen aanmaken. Uiteindelijk `cd` je in de directory `public` en kun je de server opstarten. 10 11 ```shell 12 # installatie van de dependencies 13 php composer.phar install #of composer install 14 15 # opzetten van de database 16 php bin/console doctrine:schema:update --force 17 18 #runnen van de app 19 cd public 20 php -S localhost:8000 21 ``` 22 23 ### Backend draaien met docker 24 25 ```shell 26 # Bouwen en taggen image 27 docker build . -t memory-backend 28 # Runnen van docker image 29 docker run -p 8000:8000 -d -v memory-backend-data:/usr/src/memory-backend/var --name memory-backend memory-backend 30 ``` 31 32 ## PDO foutmelding 33 34 Mocht je de foutmelding krijgen dat er een PDO-dependecy niet gevonden kan worden, dan moet je de `php.ini` aanpassen, zodat de extensies `pdo-sqlite3`, `sodium` en `sqlite3` gevonden kunnen worden. 35 36 __Let op__: om het runnen van de applicatie wat eenvoudiger te maken, hebben we zowel de private als de publieke sleutel in git gezet (in `config/jwt`). Dit is natuurlijk niet zoals het hoort, want je moet nooit je private sleutel in versiebeheer zetten. Je kunt natuurlijk altijd zelf een private en publieke sleutel maken, mocht je dat willen. Bekijk eventueel [deze documentatie](https://digitalfortress.tech/php/jwt-authentication-with-symfony/) om te zien hoe je één en ander helemaal goed opzet. 37 38 ## Het vullen van de database 39 40 Het database-schema is vrij eenvoudig van opzet: er is een tabel `player` en een tabel `game` (die op een wat ingewikkelde manier met elkaar verbonden zijn: zie [deze blog om te lezen waarom](https://www.doctrine-project.org/projects/doctrine-orm/en/latest/reference/association-mapping.html#one-to-many-unidirectional-with-join-table)). Check de entiteiten in `App/Entity/` om een beeld te krijgen van hoe deze twee zich tot elkaar verhouden. 41 42 In de directory `create` vind je een aantal scripts (eigenlijk gewoon `cURL` calls) die je kunnen helpen met het opzetten en testen van de applicatie. Als je de server hebt draaien kun je deze scripts op de hieronder gegeven volgorde draaien om spelers en spellen aan te maken. Hierbij wordt er van uitgegaan dat de applicatie draait op `localhost:8000`. Als je het ergens anders draait, moet je vanzelfsprekend de nodige gegevens aanpassen. 43 44 bestandsnaam | omschrijving 45 ----|---- 46 `create_users.sh` | Om een aantal spelers in de database aan te maken 47 `create_games.sh` | Om een aantal spellen in de database op te slaan 48 49 Hierna kun je checken of het inloggen werkt. Als je een speler of een admin inlogt, krijg je van de applicatie een JWT terug. Sla deze op in respectievelijk `player_token` en `admin_token` zodat je de onderstaande scripts kunt gebruiken om te checken of alles goed werkt. Bestudeer ook de scripts zelf om inzicht te krijgen in de API's. 50 51 In de code is hard geprogrammeerd dat de gebruiker met gebruikersnaam 'Henk' de `ROLE_ADMIN` heeft. 52 53 bestandsnaam | omschrijving 54 ----|---- 55 `login_player.sh` | Om een speler in te loggen; sla het teruggegeven jwt op in het bestand `player_token` 56 `check_player.sh` | Om het jwt van een ROLE_USER te checken 57 `change_prefs.sh` | Om de voorkeuren van een speler aan te passen 58 `login_admin.zsh` | Om een administrator in de loggen; sla het teruggegeven jwt op in het bestand `player_token` 59 `check_admin.sh` | Om het jwt van een ROLE_ADMIN te checken 60 `failed_login_user.sh` | Om een speler met verkeerde credentials te checken 61 62 ## Connectie maken vanaf een frontend 63 64 In deze repository vind je ook een directory `frontend`, met daarin één pagina: `index.html`. Deze pagina kun je gebruiken om je setup te checken. Start in deze directory een locale server op die naar een *andere poort* dan de backend zelf luistert (bijvoorbeeld poort 8080). 65 66 ```shellΩ 67 # in de directory frontend 68 php -S localhost:8080 69 ``` 70 71 Om vanaf een frontend connectie te maken met deze backend is het noodzakelijk om de frontend in hetzelfde domein te hebben draaien als de backend; als je de frontend op een ander domein draait, of gewoon als bestand op je file-system opent, krijg je [CORS-errors](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors). 72 73 74 Ga vervolgens met een browser naar `localhost:8080/`. Als het goed is zie je nu een test-pagina. Klik op de knop om de connectie te testen. Hiermee wordt een call gedaan naar `localhost:8000/frontend` die de huidige datum teruggeeft. De test-pagina toont vervolgens deze datum onder het formulier: 75 76  77 78 79 ## End-points 80 81 De applicatie heeft de volgende end-points. Ze spreken redelijk voor zich, maar bestudeer eventueel de Controllers en [de gegenereerde documentatie](http://localhost:8000/api/docs). 82 83 ### ANONYMOUS 84 85 Methode en end-point | return value | omschrijving 86 ----|----|---- 87 `GET /scores` | 200 Ok | Overzicht van de spelers en hun score (ongesorteerd) 88 `POST /register` | 201 Created | Registeren van een speler 89 " | 400 Illegal Request | Als de opgestuurde gegevens niet kloppen met het model 90 `POST /api/login_check` | 200 Ok | Als de credentials kloppen met de speler, komt hier een JWT terug 91 " | 401 Unauthorized | Als de credentials niet kloppen (specifiek password niet bij username) 92 `POST /game` | 201 Created | Opslaan van game voor speler 93 " | 400 | Als request niet overeenkomt met het model 94 95 ### ROLE_USER 96 97 Methode en end-point | return value | omschrijving 98 ----|----|---- 99 `GET /api/player/{id}` | 200 Ok | Alle gegevens van speler `id` 100 " | 404 Not Found | Als de `id` niet gevonden is 101 `GET /api/player/{id}/games` | 200 Ok | De spellen die de speler met `id` heeft gespeeld 102 " | 404 Not Found | Als de `id` niet gevonden is 103 `GET /api/player/{id}/preferences` | 200 Ok | De voorkeuren van speler `id` (api en kleuren voor gesloten en gevonden kaarten) 104 " | 404 Not Found | Als de `id` niet gevonden is 105 `POST /api/player/{id}/preferences` | 204 No Content | Aanpassen van de voorkeuren van speler `id` (api en kleuren voor gesloten en gevonden kaarten) 106 " | 404 Not Found | Als de `id` niet gevonden is 107 `GET /api/player/{id}/email` | 200 Ok | Het email-adres van speler `id` 108 " | 404 Not Found | Als de `id` niet gevonden is 109 `PUT /api/player/{id}/email` | 204 No Content | Aanpassen van het email=adres van speler `id` 110 " | 404 Not Found | Als de `id` niet gevonden is 111 112 ### ROLE_ADMIN 113 114 Methode en end-point | return value | omschrijving 115 ----|----|---- 116 `GET /api/admin/aggregate` | 200 Ok | Totaal aantal gespeelde spellen en spelers; overzicht van de gekozen api's 117 `GET /api/admin/players` | 200 Ok | Overzicht van gebruikersnamen en email-adressen van alle spelers 118 `GET /api/admin/dates` | 200 Ok | Totaal van het aantal gespeelde spelletjes per dag 119 120 ## Logging 121 122 De applicatie maakt gebruik van [monolog](https://github.com/Seldaek/monolog) voor het bijhouden van log-bestanden. De logs worden bijgehouden in `var/log/`. In totaal zijn vier verschillende logs gedefinieerd: 123 124 naam | omschrijving 125 ----|---- 126 `dev` | hierin komen alle meldingen (met niveau `INFO` of hoger) te staan 127 `request` | de requests met de gevonden route (zo die er is) 128 `monolog` | alle gebeurtenissen op de database (vanaf level `INFO`) 129 `error` | alle foutmelden die door de applicatie worden gegenereerd 130 131 Om de leesbaarheid van de logs wat te vergroten wordt de volledige melding wat gekort. Het standaard-formaat is `datetime \t request \t message`. Dit gebeurt in de klasse `src\Util\CustomFormatter`. Bestudeer de code in deze klassen wanneer je het formaat toch nog anders wilt hebben. De logs zelf zijn gedefinieerd in `config/packages/monolog.yaml`.