Mijn naam is Rob Van Keilegom. Ik ben een laatstejaarsstudent bij Thomas More campus De Nayer. Als student ICT heb ik dan ook een stage gezocht binnen de IT wereld. Door mijn persoonlijke intresse in web development heb ik besloten een stage te zoeken in deze sector. Zo ben ik bij Uni-t terecht gekomen, een web communication bureau in Mechelen dat valt onder de Gemaco Group. Hier werd mij gevraagd een web applicatie te schrijven zodat werknemers gemakkelijk met elkaar contact kunnen leggen en ook houden. Daaruit is de Connect applicatie ontstaan waarover je in deze scriptie meer zal lezen.
Graag wil ik de collega's bij Uni-t bedanken voor de fijne samenwerking. Ze hebben mij goed bijgestaan en waren altijd bereid om te helpen. Bij deze collega's hoort ook mijn bedrijfspromotor Thomas Rypens die ik speciaal wil bedanken voor altijd tijd vrij te maken en voor de kansen die ik bij Uni-t gekregen heb.
Tot slot wil ik graag mijn hogeschoolpromotor Sofie Beerens bedanken voor de begleiding, de vrijgemaakte tijd, snelle communicatie en voor het nalezen van deze scriptie.
Gemaco Group is een internationaal full-service branding agency actief in 3 continenten en meer dan 15 landen. Al 20 jaar wordt Gemaco als een premiumleverancier van promo items, sales promotion, kleding en fulfilment programma’s erkend. Omwille van hun continue groei worden ze vandaag beschouwd als een internationale speler in branding en als een gerenommeerde leverancier van promo artikelen. Op de site in Mechelen bevinden zich verschillende Gemaco onderdelen. Eén van deze onderdelen is Uni-t, zij specialiseren zich in web applicaties. Hier heb ik dan ook mijn stage gedaan.
Door het snel groeiende personeelsaantal zou Uni-t graag een who is who/intranet app hebben. Deze app kan gebruikt worden voor het terug vinden van gegevens over personeel in het bedrijf en belangrijke/nuttige info voor nieuw personeel. Hierdoor kan iemand gemakkelijk gecontacteerd of terug gevonden worden.
Als antwoord op dat probleem is Uni-t met Gemaco Connect gekomen. Een online tool waarbij personeel kan inloggen om professionele info, alsook persoonlijke info over collega’s, belangrijke en handige weetjes terug te vinden. Ook zal de Gemaco Connect app als centrale login dienen. Zo kunnen gebruikers bij de verschillende andere applicaties in één klik inloggen.
API: Application Programming Interface, een verzameling definities op basis waarvan een computerprogramma kan communiceren met een ander programma of onderdeel.
Command line interface: Het manipuleren van een programma via een console.
Commit: Nadat je aanpassingen aan je code hebt gemaakt, bundel je deze in een commit om dan de commit online naar je codebase door te pushen.
DOM: Document Object Model. Definieert de logische structuur van een website en de manier waarop het kan aangesproken worden.
Endpoint: Een endpoint is een aanspreekpunt, het eindpunt voor communicatie.
Method chaining: Een syntax om meerdere method calls uit te voeren in een enkel statement.
MySQL injectie: Verkeerd invoeren van data in een query waardoor een database onbedoeld gevoelige data terug geeft.
OAuth: Open Authorization. Is een open standaard voor autorisatie. Werkt op basis van tokens en wordt heel vaak gebruikt voor API's
ORM: Object-Relational Mapping. Dit is een techniek voor het converteren van data tussen twee incompatibele systemen in object georiënteerde talen. Dit maakt van de database een virtueel object dat je dan kan aanspreken vanuit je code. In Laravel is dit Eloquent.
Preprocessor: Een programma dat een type van data omzet naar een ander type alvorens dat nieuwe type te kunnen runnen. bv: scss naar css.
Production: Kort voor production server. Verwijst naar de server waar de website opstaat die voor iedereen toegankelijk is.
Repository: In dit gebruik, een centrale plek waar al de code wordt opgeslagen.
Staging: Kort voor staging server. Verwijst naar de webserver die gebruikt werd om nieuwe wijzigingen op te testen voor deze door te pushen naar production.
Syntax: Set van taalregels voor een programmeertaal.
Voor ik verder in ga op de Gemaco Connect app ga ik eerst even kort de tools opsommen die ik dagelijks gebruikte.
Atom is een tekst editor die out of the box heel compact en modern is. Het voordeel aan Atom is dat enkel de basis, die iedereen nodig heeft wordt geïnstalleerd. Daarna kan je community packages installeren die het best bij jou en je programmeertaal passen. Atom draait op macOS, Linux en Windows, is gemaakt door GitHub en is volledig gratis.
Om databases te manipuleren maak ik gebruik van HeidiSQL. Deze tool maakt het heel gemakkelijk om data en tabellen te bewerken, SQL queries uit te voeren en data te importeren en exporteren. HeidiSQL is gratis en werkt enkel op Windows.
Dit is een tool die ik pas leerde kennen bij Uni-t. Het is een website die je codebase verbindt met de webserver waarop de website staat. Elke keer als je een wijziging aan je code maakt, pikt Envoyer deze op. Envoyer test dan de code, dit wil zeggen dat het alle vereiste packages en dergerlijke gaat installeren die je applicatie nodig heeft. Als je eventueel tests hebt geschreven kan Envoyer deze ook uitvoeren. Wanneer Envoyer alles correct kan uitvoeren zal het de code op de server plaatsen die je gelinkt hebt (staging of production) en is je online website geüpdatet.
Als versie beheer systeem gebruikte ik Git. Dit is een veel gebruikte tool die het gemakkelijk maakt aanpassingen aan je code bij te houden en terug te draaien. Source Tree is een grafische gebruikers interface voor git. Deze vergemakkelijkt het gebruik van git dat normaal via een command line interface gaat. Dit geeft, onder andere, een visuele representatie van al je commits weer. SourceTree draait op macOS en Windows, is gemaakt door Atlassian (Bitbucket/Confluence) en is volledig gratis.
InVision is een gratis web en mobiel prototyping platform. Deze werd door de designer van Uni-t gebruikt om de designs te delen. Hij laadt de Photoshop bestanden op in InVision, waar ik deze dan eenvoudig kon bekijken. Op deze manier was het voor mij heel eenvoudig om de front-end na te bouwen.
Om API endpoints te testen gebruik ik Postman. Met Postman kan je heel gemakelijk het endpoint ingeven, het type van communicatie instellen en eventuele data meesturen. Het antwoord van het endpoint kan dan op verschillende manieren weergegeven worden. De meest voor de hand liggende manier is JSON. Postman zal de JSON dan ook formatteren zodat deze goed leesbaar is. Postman draait op macOS, Linux, Windows of als Chrome extensie en is volledig gratis.
Bugsnag voegt error monitoring toe aan je applicatie. Dat wil zeggen dat wanneer er een error voorkomt bij de gebruiker, deze wordt opgevangen door Bugsnag. Bugsnag zal dan een mail sturen waarin de error aangegeven wordt, wanneer deze gebeurd is en op welke pagina de gebruiker was. Bugsnag heeft ook een overzichtelijk dashboard waar je alle errors kunt bekijken. Dit maakt het heel gemakkelijk fouten terug te vinden in je applicatie.
Hieronder ga ik de tools beschrijven die nodig waren bij het schrijven van de front end van de Connect applicatie. Dit zijn programma's om code te verwerken, maar ook packages die het eenvoudiger maken een werkende front end op te zetten.
Als front-end package manager maakte ik gebruik van NPM.
Dit is de meest populaire package manager voor JavaScript.
Een zeer handige tool om veel gebruikte packages binnen te halen.
NPM houdt alle packages, met hun versie nummer, bij in een package.json bestand.
De packages zelf worden bijgehouden in een node_modules map in de root van je project.
Een package is toe te voegen door npm install font-awesome --save uit te voeren in de console.
De --save optie zorgt er voor dat de package bijgehouden wordt in het package.json bestand.
Hieronder vind je een voorbeeld van een package.json bestand. Dit bevat oa. Font Awesome, Gulp, JQuery en Vue.
Ik vind het ook belangrijk om toch Font Awesome even kort aan te halen.
Dit is een gratis CSS toolkit die zeer eenvoudig schaalbare SVG iconen toevoegt aan je project.
Nadat je hun CSS bestand hebt toegevoegd kan je dan eenvoudig een icoon weergeven door volgende HTML toe te voegen:
<i class="fa fa-flag"></i>.
De iconen zijn van hele hoge kwaliteit, ook op retina schermen.
Ook zijn ze te kleuren op dezelfde manier als je je letter type kleur geeft.
Als toolkit voor het preprocessen van .scss naar .css bestanden en het minifyen
en samenvoegen van meerdere scripts of stylesheets gebruikte ik Gulp.
Dit werd standaard meegeleverd met Laravel tot versie 5.4.
Elixir is een uitbreiding op Gulp. Deze zorgt voor de ondersteuning van CSS, javascript en method chaining.
Nadat je al je code hebt geschreven kan je gulp uitvoeren in de command line.
Alle opdrachten die uitgevoerd moeten worden, moeten beschreven worden in een javascript file: gulpfile.js.
Hier vind je een voorbeeld van een gulp file. Als je geen 2de parameter meegeeft geeft Gulp de file de naam all.
In de eerst scripts method call zie je Gulp 5 scripts nemen en deze samenvoegen in all.js.
In de tweede scripts method call neemt Gulp 3 scripts en voegt deze samen in register.js.
SASS is een style sheet taal die wordt geïnterpreteerd als CSS. Deze kan gezien worden als een uitbreiding op CSS. Dit wil zeggen dat elke geldige CSS ook geldige SASS is. SASS maakt het onder andere mogelijk om variable en geneste CSS blokken te gebruiken. Het nesten van CSS blokken maakt je code veel duidelijker. SASS is ook compatible met andere CSS tools.
Voor de registratie werd mij gevraagd om Vue.js te gebruiken. Dit is een opensource javascript framework waar ik nog nooit van had gehoord. Vue is vanaf het begin gebouwd met de bedoeling heel uitbreidbaar te zijn. Vue maakt het heel gemakkelijk om data en DOM te linken en weer te geven met hun template syntax.
Hieronder zie je een verkorte versie van de Vue app verbonden is met de registratie pagina.
Met el: '#register_app' hangt Vue zich vast in het #register_app element op de pagina.
Onder data() zie je al de variablen die Vue moet bijhouden.
In methods definieer je de functies die je nodig hebt in je applicatie.
Hier zie je de calculateData functie, die de verjaardag van de gebruiker omzet naar een string.
De mounted functie wordt uitgevoerd wanneer de website volledig is geladen en Vue zich er in heeft vast geklikt.
Hier wordt er data in de first_name variable geplaatst.
Op elke plek waar de variable voorkomt op de website zal nu 'Rob' staan.
Hier zie je een klein voorbeeld van hoe Vue in HTML wordt gebruikt.
v-if kijkt of first_name gelijk is aan 'Rob'.
Als dat niet zo is zal de waarde in first_name weergegeven worden met @{{ first_name }}.
Het design voor de webinterface werd aangeleverd door Uni-t. Er werd gekozen te vertrekken van de template OneUI omdat dhr. Seeger (een frontend designer bij Uni-t) zich op dit template gebaseerd had bij het maken van de designs. Dit maakte het frontend werk een stuk makkelijker voor mij. Ik heb de template overgenomen en alle data eruit gehaald. Op deze manier bleven enkel de header en navigatie balk over. De navigatie balk heb ik dan aangepast naar de huidige navigatie, in de header zijn enkele knoppen verwijderd. In de figuur ziet je de de oorspronkelijke template.
Hieronder ga ik alle pagina's overlopen waarmee de gebruiker in aanraking komt.
Op het welkom scherm kan je kiezen tussen Senior en Rookie. Senior is voor reeds geregistreerde gebruikers. Zij kunnen hier inloggen en worden dan doorgestuurd naar het dashboard. Voor nieuwe gebruikers bestaat de Rookie kant. Zij kunnen hier selecteren om een nieuw account te maken. Zo worden ze dan doorgestuurd naar een registratie flow.
Na Rookie te selecteren in het welkom scherm komt de gebruiker in de registratie flow. Hier loopt de gebruiker door een luchtige tekst waar hij dan zijn gegevens kan invullen. Het was heel belangrijk dat dit iets aangenaams moest zijn en geen saai formulier.
Hieronder vind je de volledige tekst die de gebruiker moest doorlopen. Alles tussen [ en ] zijn invulbare velden.
Alles tussen @{{ en }} zijn velden ingevuld door Vue.
@{{ step3.birthday_string }} zal de datum bevatten die ingevuld is bij de verjaardag omgezet naar een string.
@{{ step1.first_name }} zal de naam bevatten die is ingevuld in stap 1.
Het dashboard, dat ook de home pagina is van de Connect applicatie bestaat uit verschillende widgets. Er is een notificatie widget [1]. Hierin kunnen meldingen geplaatst worden die iedereen gezien moet hebben. Daaronder bevindt zich een status bar [2]. Deze toont hoeveel velden je hebt ingevuld op je profiel. Hoe meer velden je invult, hoe hoger je gemaco rank wordt, om uiteindelijk Gemaco All-Star te worden. Dan is er een widget voor nieuwe collega's [3]. Dit zijn mensen die recent een profiel hebben aangemaakt op de Connect applicatie. Er is een widget voor verjaardagen [4] en een voor mensen die er x aantal jaar werken [5]. Bovendien is er ook een widget waarin alle opkomende evenmenten getoond kunnen worden [6]. Verder is er ook een widget die de laatste nieuwe Instagram posts toont [7] van de verschillende bedrijfen onder Gemaco. Nieuwe gebruikers krijgen ook een todo lijst te zien die ze kunnen afvinken. Deze bevat todo's zoals: stel je mail in, maak een slack account aan, enz...
Links van het dashboard bevindt zich een navigatie balk. Hieronder ga ik één voor één alle pagina's overlopen die hier gelinkt staan.
De colleagues pagina bevat een overzicht van alle onderdelen van de Gemaco Group. Op deze pagina zie je de logo's van alle departementen met per departement een toepasselijke cover foto.
Als je dan doorklikt op een department krijg je een overzicht van alle werknemers. In het overzicht krijgt je direct hun profiel en cover foto te zien. Naast foto's staat er ook al enkele nuttig informatie, zoals: naam, intern nummer en functie binnen het bedrijf. Je kan hier dan doorklikken om naar het profiel van een werknemer te gaan.
Onder de calendar link vind je een grote kalender. Deze bevat evenementen, verjaardagen en werk jubilea. Voor de laatste twee wordt data gebruikt uit de profielen. Op deze pagina kan je ook evenementen toevoegen aan de kalender via het formulier rechts. Er kan gekozen worden tussen een evenement voor heel het bedrijf of voor een specifiek departement.
In de afbeeldingen hieronder zie je de volledige calendar pagina, een ingezoomd stuk van de calendar pagina en de 2 pop-up's die je te zien krijgt wanneer je op een verjaardag of workiversary event klikt.
Op de Tips & Tricks pagina komt een overzicht van handige weetjes binnen het bedrijf. Momenteel bevat deze data zoals de WiFi code. De tips werken als een accordion, dit wil zeggen dat initieel enkel de titels worden weergegeven. Als hier op klikt schuift de tip open en toont de beschrijving. Klik je op een andere tip dan schuift de huidige dicht en de nieuwe tip open.
Data toevoegen kan via het administratie menu dat enkel toegankelijk is voor administrators.
Via het profiel krijg je alle data te zien die bij de registratie werd ingegeven. Verder kan je hier ook je sociale media profielen invullen, je slack account linken, relatie status aanpassen en eventueel ook tags toevoegen. De bedoeling van de tags is dat deze aangeven wat jouw sterke punten zijn binnen het bedrijf. Ook is er een kleine widget waarin colleaga's getoond worden. Zo kun je gemakkelijk een heel departement verkennen of zien welke collegas deze persoon heeft.
Het aanpassen van je profiel kan door rechts bovenaan op Edit Profile te klikken. Om je slack account te linken, klik je op de slack link waardoor je doorverwezen wordt naar de Slack website. Op de Slack website kan je dan kiezen welk team je wilt linken. Ook kan je hier een mail aanvragen om je wachtwoord te resetten.
Onder het Administration sub menu vind je links om alle data te bekijken en toe te voegen. Deze pagina's tonen een lijst met alle data die van dat type aanwezig is. Ook staat er telkens een klein formulier waar je een item kan toevoegen. Bij elke bestaand item staat een knop om het aan te passen of te verwijderen.
Hier zie je een voorbeeld van de notificatie admin pagina.
Er zijn nog enkele extra's. Zo staat er in de navigatie nog een Quick Link sub menu. Hier kan je snel doorklikken naar de Vacay, Sammisch en andere interne bedrijfsapplicaties. Met de knop links van de zoek balk kan je de navigatie kleiner maken.
Bovenaan de pagina vind je een zoek balk. Hier kan je personen zoeken op naam, e-mail of nummerplaat.
De connect Applicatie is volledig mobiel vriendelijk. Hieronder ziet u een voorbeeld van het dashboard op een kleiner scherm.
Hier zal ik het hebben over achterliggende technologieën en en tools die gebruikt werden bij het maken van de backend.
Composer is een package manager voor PHP.
Via een composer.json bestand in de root directory van je project wordt aangegeven
welke packages het project nodig heeft om te functioneren.
Alle packages worden dan geplaatst in een vendor map in je project root.
Met het command composer install worden dan alle packages geïnstalleerd.
Met composer update kan je gemakkelijk alle packages updaten.
Eén van de packages die ik heb geïnstalleerd met composer is LightSAML.
Je installeert de package op volgende manier:
composer require lightsaml/lightsaml
Composer voegt de package dan toe aan je vendor folder. En voegt de package toe als required in je composer.json file.
Hieronder vind je een voorbeeld van een composer.json file.
Je ziet de verschillende packages die nodig zijn voor je project. Waaronder het Laravel framework.
Onder require-dev zet je de packages die enkel nodig zijn in een development omgeving.
Bijvoorbeeld: phpunit, een package voor tests te schrijven.
Je ziet onder scripts ook enkele commands staan die worden uitgevoerd.
Hier zie je onder andere hoe je .env bestand wordt aangemaakt.
Je leest enkele pagina's verder meer over het .env bestand.
Laravel is een gratis, opensource framework geschreven in PHP.
Het is een snel groeiend framework met een heel modulair pakketsysteem.
Laravel komt samen met Artisan, een CLI die je helpt bij het bouwen van je app.
Zo kan je een lijst opvragen van alle mogelijke commando's door php artisan list uit te voeren in je console.
Daarnaast kan je ook zelf commando's toevoegen.
Dit is dan ook het framework dat werd gebruikt om de Connect applicatie op te zetten.
Hieronder zal ik iets dieper ingaan op de verschillende onderdelen van het framework.
Dit is de enviroment file van Laravel. Hier wordt alle gevoelige data, die eigen is aan de omgeving waar de website draait, bijgehouden. Hierin zitten onder andere database credentials en API keys.
Het Eloquent ORM dat bij Laravel hoort zorgt voor een ActiveRecord implementatie.
Dit betekent dat elke table in de database een bijhorend model heeft dat gebruikt wordt om met de tabel te werken.
Je kan een leeg model toevoegen met het Artisan commando: php artisan make:model Department.
Alle models bevinden zich in de app folder.
Hieronder vind je het Department model.
Het heeft de attributen name, description, profile_picture, cover_picture.
In de users functie zie je hoe er een relatie wordt gelegd tussen het departement model en het user model.
Hierdoor kan je eenvoudig alle users van een department ophalen en omgekeerd.
Soms wil je een attribuut dat een afgeleide is van een andere waarde.
Deze moet dan niet opgeslagen worden in de databank want dan krijg je meerdere velden met praktisch dezelfde data.
Daarvoor dient de getAdminRoleAttribute mutator.
Deze creëert een aanspreekbaar admin_role attribute op het model.
In dit voorbeeld zal de mutator dan een string terug geven met daarin het id van het departement.
Dit zijn PHP scripts die worden uitgevoerd om tabellen in een databank te manipuleren.
Deze gebruik je om alle tabellen in je databank aan te maken of om aanpassingen terug te draaien.
Je kan een migratie aanmaken met het commando: php artisan make:migration create_departments_table.
Migraties zijn terug te vinden in de database/migrations folder.
In het voorbeeld onderaan zie je hoe de departments tabel wordt aangemaakt. Je ziet ook elke kolom die wordt aangemaakt en welk type data deze kan bevatten.
$table->timestamps() zorgt ervoor dat er created_at en updated_at
kolommen worden aangemaakt.
Deze velden worden automatisch ingevuld door laravel bij het aanmaken en updaten van een model.
$table->softDeletes() zorgt ervoor dat er een deleted_at kolom wordt aangemaakt.
Deze kolom voegt de soft deletes functionaliteit toe.
Dat wil zeggen dat er nooit echt verwijderd wordt, maar de huidige tijd in het deleted_at veld wordt geplaatst.
Om deze functionaliteit te kunnen gebruiken moet je ook use SoftDeletes toevoegen aan je model,
zoals in het voorbeeld hier boven.
Als een gebruiker een pagina opvraagt wil je soms nog een controle doen voor je de pagina terug geeft.
Een voorbeeld van deze controlles is of de gebruiker wel rechten heeft om deze pagina te bekijken.
Voor dit soort controlles dient Middleware. Alle Middleware bevindt zich onder app/Http/Middleware.
Hieronder zie je een voorbeeld van middleware. De middleware die ik hier geschreven heb, kijkt of de gebruiker de pagina wel opvraagt via het veilige https protocol. Als dit niet het geval is zal de gebruiker doorgestuurd worden naar de veilige pagina. Ook wordt er nog een check gedaan of de website op productie draait. Dit gebeurt omdat de staging versie geen https protocol ondersteunt.
Controllers behandelen de aanvragen van de gebruikers.
Als er data opgehaald moet worden om weer te geven, doet de controller dit en stuurt dan de data terug mee naar de gebruiker.
Alle controllers zijn terug te vinden onder app/Http/Controllers.
In onderstaand voorbeeld zie je een stuk van de DepartmentController.
De index functie haalt alle departementen op en stuurt deze terug naar de gebruiker.
De web.php file bevindt zich in de routes folder.
Hier worden aanspreekbare end points van je website gedefineerd, de methode waarop ze aanspreekbaar zijn en door welke controller ze behandeld moeten worden.
Routes kunnen gegroepeerd worden met Route::group om bijvoorbeeld alle routes in die group via de zelfde middleware te laten gaan.
In onderstaand voorbeeld zie je een Route::group met de web middleware.
Dit is een standaard middleware van laravel die automatisch zorgt voor handige functies zoals cookies om ingelogd te blijven.
Dan zie je hoe het root pad / doorgestuurd wordt naar de login functie van de AuthController.
Ook wordt deze route de naam home gegeven om deze later gemakkelijker aan te kunnen spreken.
Views staan hier opgelijst omdat ze een onderdeel van Laravel zijn, maar passen even goed onder Front-End. Een view is de pagina die de gebruiker terug gestuurd krijgt. Het is dus een HTML pagina maar deze is uitgebreid met Blade, een templating engine. Blade maakt het heel gemakkelijk om php variablen in je HTML in te vullen.
In het voorbeeld zie je @extends('layouts.dashboard'), dat wil zeggen dat deze view de standaard dasboard view uitbreidt.
De standaard dasboard view bevat onderdelen die op elke pagina voorkomen zoals de navigatie.
Verder zie je @foreach ($tips as $key => $tip).
Dit is ook blade syntax en wordt gebruikt om door alle tips te lopen.
In die loop zie je dan {{ $tip->title }}.
Hierdoor wordt de titel van de tip in het html document geplakt.
Als database management systeem gebruikte ik MySQL. Dit is het meest voorkomende en bekendste database systeem. De meeste interactie met de database ging via het eloquent model. Dit is heel goed voor standaard acties, zoals gegevens ophalen en wegschrijven, maar voor andere actires moet je toch nog zelf queries schrijven. Hiervoor heeft Laravel de Query Builder. De Query Builder beschermt je applicatie ook tegen MySQL injectie.
In onderstaand voorbeeld zie je hoe ik de todos tabel selecteer.
Daarna voeg ik de todo_positions tabel toe.
Dit is het equivalent voor inner join.
Dan neem ik enkel de todo's waar department_id gelijk is aan het megegeven ID.
->whereNull('deleted_at') zorgt er voor dat de rijen die een soft delete timestamp hebben niet worden meegegeven.
Eloquent voegt dit deeltje zelf toe, maar in de query builder moeten we dit dus zelf toevoegen.
Daarna sorteer ik de resultaten op position en neem ik alle kolommen van de todos tabel.
Om alle uploads van foto's te behandelen maakte ik gebruik van Uploadcare. Deze tool zorgt voor een scherm (foto hier onder) waar de gebruiker een foto kan selecteren. Hij krijgt een upload knop te zien, door daar op te klikken en een foto te selecteren krijgt wordt de foto tijdelijk in een veld gestoken. Dit veld wordt dan naar de back-end verzonden wanneer de gebruiker op '(profiel) opslaan' klikt. Voor de Connect applicatie had de gebruiker de keuze een foto te selecteren van zijn computer, Facebook, Google Drive, Dropbox, Instagram, Evernote of een foto te trekken met zijn webcam. Uploadcare zorgt er ook voor dat je je bestanden niet zelf moet bewaren. Ze houden deze zelf bij op hun server. De afbeeldingen worden naar de Uploadcare servers gestuurd via het beveiligde HTTPS protocol en kunnen enkel uitgelezen worden met een correct API key en secret.
Hieronder zie je hoe je een upload behandelt met Uploadcare in de back-end.
Eerst maak je een Uploadcare\Api object aan.
Dan roep je de getFile functie aan op dat object en geef je de waarde van het Uploadcare veld op de website mee.
Daarna roep je de store() functie op, deze functie upload de foto naar de uploadcare servers.
Als de foto op de Uploadcare servers staat roep je getUrl() op op het object.
Deze geeft de URL terug waar de foto staat. Deze URL slagen we op in onze database om te weten waar de foto staat.
Slack is een tool, gemaakt voor teams, om gemakkelijk samen te kunnen werken. Slack werkt op je mobiel, je desktop en in je browser. Binnen de Gemaco groep wordt veel gebruik gemaakt van Slack als intern communicatie middel. Daarom hebben we besloten dit ook te implementeren in de Connect applicatie. De applicatie stuurt push notificaties naar Slack wanneer er een nieuwe notificatie wordt toegevoegd of wanneer er een nieuwe gebruiker is.
Hieronder zie je een voorbeeld van zo een Slack bericht.
Uni-t had graag één centrale database waarin alle gebruikers werden bijgehouden. Deze moest extern zijn bij een bedrijf dat hierin gespecialiseerd is. Op deze manier was de database altijd veilig en up to date. Daarom hebben wij voor Stormpath gekozen. De bedoeling was dat alle gebruikers in Stormpath werden opgeladen. Als een gebruiker dan inlogt op de Connect applicatie, wordt nagegaan of deze gebruiker een account heeft op Stormpath en of het ingegeven wachtwoord overeenkomt met het wachtwoord uit Stormpath. Als dat zo was werd de gebruiker ingelogd en werd alle gebruikersdata uit Stormpath doorgestuurd naar de Connect applicatie.
Stormpath had een Laravel package, dat nauwelijks gedocumenteerd was. Het werkte ook niet op de recentste versie van Laravel. Na veel lezen, opzoeken en de Connect applicatie met één minor versie te downgraden heb ik uiteindelijk alles werkend gekregen. Stormpath had een gratis pakket waarmee je de database 10000 keer kan aanspreken per maand. Dit lijkt veel maar was een getal waar we snel tegen aan zaten. Door de Connect applicatie zuiniger te maken, en de Stormpath database minder aan te spreken was het uiteindelijk mogelijk om onder 10000 te blijven.
Er is veel tijd in gekropen om alles met Stormpath werkend te krijgen. Na alle optimalisaties werkte dit wel heel goed. Spijtig genoeg kreeg ik een week later een mail van Stormpath. Hierin stond dat Stormpath was overgekocht door Okta, een concurrent van Stormpath, en dat Stormpath werd afgesloten binnen enkele weken. Hierdoor moest ik op zoek naar een plaatsvervanger. Ik heb vele opties bekeken en er waren twee bedrijven die vaak terug kwamen. Dit waren Okta en OneLogin. Zij doen beide ongeveer het zelfde als Stormpath maar waren allebei betalend. De diensten die ze aanbieden zijn ook heel uitgebreid. Door het hoge prijskaartje en hun grote aanbod van diensten, heb ik ervoor gekozen een andere oplossing te zoeken.
Samen met Gemaco, heb ik besloten een eigen API te bouwen die als centraal aanspreekpunt kan dienen voor alle Gemaco applicaties die gegevens van gebruikers en departementen moeten ophalen en wijzigen. Laravel heeft hier heel goed package voor: Laravel Passport. Hier kan je verder meer over lezen.
Bij Gemaco draaien verschillende applicaties zoals bijvoorbeeld de Vacay applicatie waarin gebruikers ... Om herhaaldelijk inloggen in verschillende applicaties tegen te gaan, werd gevraagd Single Sign-On te implementeren in de Connect applicatie. Dit betekent dat de andere applicaties aan de Connect applicatie kunnen vragen of er iemand is ingelogd. Als dit zo is antwoordt de Connect app met wie er is ingelogd zodat de andere applicatie deze gebruikers dan ook automatisch kan inloggen. Op deze manier moeten de gebruikers telkens enkel op de Connect app inloggen om toegang te krijgen tot alle andere alle andere applicaties. Om dit te bereiken maakte ik gebruik van SAML zodat de applicaties kunnen praten met elkaar.
Om dit te kunnen bereiken moet er kunnen gecommuniceerd worden tussen
eenderzijds de Connect applicatie en anderzijds de andere applicaties van Gemaco.
Deze communicatie gebeurt via SAML. SAML staat voor Security Assertion Markup Language.
Dit is een XML gebaseerde standaard voor het uitwisselen van authenticatie- en autorisatiegegevens.
Een authenticatie gaat als volgt:
Eerst stuurt de externe applicatie een AuthnRequest naar de Connect applicatie.
De Connect applicatie stuurt een response met daarin de gegevens van de ingelogde gebruiker.
De externe applicatie krijgt deze aan en logt de gebruiker in die voldoet aan de gegevens in het response.
De gebruiker is nu ingelogd tot zijn sessie vervalt, en kan de externe applicatie gebruiken.
Om met SAML te kunnen werken heb ik gebruik gemaakt van de LightSAML package.
Dit is een SAML package voor PHP. Je kan dit installeren door composer require lightsaml/lightsaml uit te voeren.
Hieronder zie je een voorbeeld van een AuthnRequest dat ik toegevoegd heb aan één van de externe applicaties.
Er wordt een AuthnRequest object aangemaakt.
Hier wordt de AssertionConsumerServiceUrl in gezet.
Dit is de URL waar de Connect applicatie zijn antwoord naar gaat sturen.
Het protocol wordt op POST gezet. Er wordt een uniek ID gegenereerd en een timestamp aangehangen.
Daarna wordt de destination toegevoegd. Dit is de plek waar de request naartoe gestuurd moet worden.
Dan wordt de Vacay applicatie als issuer geset. Hierdoor weet de Connect applicatie waar de request vandaan komt.
Er wordt een httpResponse aangemaakt met de AuthnRequest als bericht en deze wordt verstuurd.
Omdat Stormpath niet langer bruikbaar was, hebben we besloten Passport te gebruiken.
Dit is een package voor Laravel dat voor een volledige OAuth2 implementatie zorgt.
Je kan passport toevoegen aan je project door composer require laravel/passport uit te voeren.
Om data uit de Passport applicatie (die ik vanaf nu kortweg API zal noemen) te kunnen halen moet je je eerst authenticeren. Op deze manier weet de API welke gebruiker welke data ophaalt en aanpast. Zo kunnen we van de API uit ook beheren welke gebruiker welke rechten heeft. Zo mag een gebruiker bijvoorbeeld enkel zijn eigen data aanpassen, niet die van een ander. Om dit te verwezelijken maken we gebruik van OAuth2 password grant. Dat wil zeggen dat de gebruiker eerst met zijn gegevens moet inloggen om zo een token te krijgen. Elke token is uniek per gebruiker en vervalt na een bepaalde tijd. Met die token kan de gebruiker dan data ophalen en aanpassen in de API.
Om de API aan te spreken vanuit andere applicaties gebruikte ik Guzzle.
Guzzle is een PHP HTTP client, wat betekent dat je er endpoints mee kan aanspreken.
Guzzle kan je installeren door composer require guzzlehttp/guzzle:~6.0 uit te voeren.
Hieronder zie je hoe de Connect applicatie zich authenticeert bij de API.
Er wordt eerst een nieuwe Guzzle client aangemaakt.
Dan wordt het authenticatie endpoint aangesproken, dat is :/oauth/token.
Als gegevens worden het email adres en het wachtwoord van de gebruiker meegegeven.
Deze gegevens heeft hij net ingevuld bij het inloggen.
Ook wordt er een client_id en client_secret meegegeven.
Hierdoor weet de API van welke applicatie de aanvraag komt.
De Connect applicatie krijgt zijn eigen client_id en client_secret,
later krijgen de andere Gemaco applicaties dit ook.
Als de gebruiker de foute credentials heeft ingegeven, stuurt de API de statuscode 401.
Dat is de HTTP code voor Unauthorized.
Als de gebruiker de correcte credentials heeft in gegeven stuurt de API statuscode 200 terug.
Dat is de HTTP code voor OK.
Samen met statuscode 200 zal de API een acces_token terug sturen.
Dit is de unieke code die de gebruiker nodig heeft om data uit de API te halen.
Deze codes worden bij de Connect applicatie in de database bewaard.
Na het succesvol inloggen doet de Connect applicatie nog een request,
deze request spreekt het endpoint /user aan en stuurt zijn access_token in de Authorization header.
Hiermee kan de API zien dat de gebruik zich heeft ingelogd en stuurt deze de user data voor deze gebruiker terug.
Nu we de Passport applicatie als centraal punt hebben kunnen andere Gemaco applicaties aangepast worden zo dat ze ook data uit deze API kunnen halen. Op deze manier moet de data maar op één plek aangepast worden om ze overal aan te passen. Verandert een departement bijvoorbeeld van naam, dan volstaat het dit in deze API aan te passen om ook alle andere applicaties up to date te brengen.
Om de implementatie van de API in andere applicaties gemakkelijker te maken voor developers, moest deze gedocumenteerd worden.
Als documentatie tool heb ik gekozen voor Swagger UI.
Swagger UI zorgt er voor dat je je API heel gemakkelijk kunt visualiseren.
Met Swagger UI kan je je API bovendien ook heel gemakkelijk testen vanuit je browser.
Swagger PHP zorgt er dan weer voor dat je de Swagger UI documentatie kunt genereren door comments in je code toe te voegen.
De L5 Swagger package, die je installeert via composer require "darkaonline/l5-swagger:~4.0",
dient als wrapper rond de Swagger UI en Swagger PHP package.
Hieronder zie je een voorbeeld van de comment die je in je code toevoegt.
@SWG\Get geeft aan op welke manier je de endpoint moet aanspreken.
path="/api/v1/departments" laat zien over welke endpoint het gaat.
@SWG\Response toont welke antwoorden je kan verwachten van de API.
Verder kan je nog een beschrijving en tags meegeven.
Deze comments staan bij elke endpoint en genereren onderstaande documentatie. Je kan de documentatie van de Passport applicatie terug vinden op: https://passport.gemaco-group.com/.
Hierboven heb ik al uitgelegd dat ik MySQL gebruikte als database management systeem. Hier ga ik iets verder ingaan op de database structuur.
Dit is de database structuur van de Connect applicatie. Deze bevat alle todo's, notificaties en calender items, enz...
Ook wordt er voor elke user een access token bijgehouden.
Dit is de token die eerder besproken is in het Guzzle hoofdstuk, de token die de user nodig heeft om zich te authoriseren bij de API.
Er zijn ook *_positions tabellen, deze houden bij in welke volgorde de todo's en tips & tricks weergegeven moeten worden.
Op deze manier kunnen de belangrijkste items bovenaan staan.
De checked_todos tabel houdt bij welke todo's de user al aangevinkt heeft.
Er wordt ook bijgehouden welke roles de gebruiker heeft.
Deze roles beslissen welke toegang de gebruiker op de Connect applicatie heeft en lopen gelijk met de roles op de API.
Hieronder ziet je de database structuur van de API.
Deze bevat alle data van de gebruikers en de departementen.
Ook hier is een roles tabel die beslist welke toegang de gebruiker op de API heeft.
Er is een aparte user_has_permissions tabel waar een gebruiker aparte/extra rechten kan krijgen op de API.
Deze tabel wordt nog niet gebruikt maar is al aangemaakt voor eventuele eenvoudige implementatie later.
De department_user tabel koppelt gebruikers aan departementen.
Wat niet in dit schema te zien is zijn de tabellen die het Passport package zelf aanmaakt.
Deze tabellen bevatten alle nodige data voor een werkende OAuth integratie.
Laravel gebruikt een speciale manier voor het opbouwen van de queries.
Op deze manier zorgt laravel er voor dat de query enkel doet wat hij zou moeten doen.
Als een gebruiker in de zoek functie 'rob@uni-t.be'; drop table users; zou typen
wordt dit niet:
SELECT * FROM users WHERE email = 'rob@uni-t.be'; drop table users;.
Deze query zou er voor zorgen dat de volledige users tabel verwijderd wordt.
Laravel zorgt er voor dat de query als volgt wordt uitgevoerd:
SELECT * FROM users WHERE email = 'rob@uni-t.be; drop table users;'.
Hier wordt er gezocht in de users tabel op rob@uni-t.be; drop table users; wat geen resultaat zal terug geven.
Laravel zorgt er zelf voor dat Cross-Site Scripting niet mogelijk is. Stel dat de gebruiker in het intresses veld op zijn profiel het volgende invult:
HTML, PHP, <script>alert("spam spam spam!")</script>
Dit zou er voor zorgen dat elke keer als het profiel van die gebruiker geopend wordt er een melding spam spam spam komt.
Een melding is niet schadelijk, maar het is begrijpelijk dat dit voor andere doeleinden kan gebruikt worden.
Laravel voorkomt dit door HTML tags te 'escapen'.
Dit wil zeggen dat HTML code wordt omgezet naar een string die door de browser enkel kan geïnterpreteerd als tekst.
Als je op de edit profile pagina van de Connect applicatie op de save knop klikt wordt de server aangesproken om je profiel op te slagen.
Het kan voorkomen dat een malafide website dat verzoek om je profiel op te slagen nabootst.
Als je bent ingelogd op de Connect applicatie, en je bezoekt de malafide website zal de server denken dat het verzoek van de
edit profile pagina komt. Dit heet Cross-Site Request Forgery.
Om dit te voorkomen, om zeker te zijn dat de verzoeken enkel van de Connect applicatie komen worden er bij elke verzoek
een CSRF token meegestuurd. Deze token wordt tijdelijk aangemaakt als de edit profile pagina wordt aangevraagd,
en wordt meegestuurd als het profiel wordt opgeslagen. Laravel controlleert standaard of deze token aanwezig en correct is.
Als een malafide website het verzoek probeert na te bootsen zal er een CSRF token mismatch error verschijnen.
Het was niet de eerste keer dat ik met het Laravel framework werkte. Ik vond het spijtig dat het vele werk voor integratie met Stormpath verloren is gegaan. Ondanks de switch van Stormpath naar Laravel Passport, en de hele API zelf te moeten schrijven heb ik de te behalen doelstellingen toch behaald en heb ik zelfs nog enkele uitbreidingen kunnen doen op bestaande interne applicaties. Door de grootte van de Connect applicatie en de API zelf op te bouwen op het Laravel framework heb ik met toch veel meer kunnen verdiepen in Laravel. Hier heb ik dan vooral functionaliteiten geleerd die ik voordien nog niet kende. Dit zijn dan vooral handige functies en methoden die standaard met laravel worden meegeleverd. Laravel is heel goed gedocumenteerd en er is veel informatie over te vinden op het internet. Ook heb ik veel best practices bijgeleerd, wat de beste manier is om je code structuur op te bouwen en enkele tools voor in een professionele omgeving gebruikt worden zoals Bugsnag en Envoyer. Het was heel leuk om eens te zien hoe het er in zo een professionele omgeving aan toe ging en hier deel van te kunnen uitmaken.