White-labeling van een Laravel-supportportaal

Beheren: het werk organiseren

De opleiding vroeg naast de software om deelproducten zoals een analyse, systeemontwerp en implementatieplan. In mijn plan van aanpak bracht ik die werkzaamheden bij elkaar en verdeelde ik ze in taken. Zo werkte ik tijdens het project ook aan de onderbouwing en overdracht van wat ik bouwde.

Die taken plande ik in Jira, in sprints van twee weken. Ik besprak de voortgang en het vervolgwerk aan het einde van een sprint en had iedere week overleg met mijn begeleider. Toen de autorisatieopdracht groter werd, splitste ik het werk verder op en plande ik opnieuw.

Analyseren: van praktijksituatie naar requirements

Om de opdracht te begrijpen verzamelde ik informatie in gesprekken en draaide ik mee met supportmedewerkers. Die gesprekken maakten duidelijk waar de huisstijl in het portaal moest doorwerken. De huisstijl moest aanpasbaar worden terwijl de bestaande ticketfuncties behouden bleven. Dat betekende dat ik verder moest kijken dan de instellingenpagina: een aangepaste naam of afbeelding moest ook elders in het portaal terugkomen.

Ik beschreef de relevante feiten en relaties in een Conceptual Enterprise Model (CEM). Daarbij gebruikte ik CogNIAM, een methode voor feitgebaseerde modellering. Vanuit die analyse werkte ik de requirements uit: wat moest een beheerder kunnen wijzigen en welke voorwaarden golden daarvoor? Dat maakte de opdracht concreet in onder meer een portaalnaam, contactadres, voorpaginatekst, afbeeldingen en themakeuze. Aan die requirements koppelde ik acceptatiecriteria waarmee de gewenste handelingen konden worden gecontroleerd.

Ontwerpen: een ontwerp dat bij Laravel past

Bij het technische onderzoek trof ik bestaande rollen, permissies en mediaopslag aan. Mijn uitbreiding moest met die onderdelen samenwerken. Ik tekende de gegevens, handelingen en componenten uit en besprak het ontwerp met mijn begeleider. Mijn eerste klassendiagram sloot nog onvoldoende aan op Laravel. Ik herzag het om de verantwoordelijkheden beter te verdelen over modellen, weergaven en controllers.

Met UML (Unified Modeling Language) werkte ik uit welke klassen samen de instellingenmodule vormen. In het herziene klassendiagram verbond ik het instellingenmodel met de controller, het formulier en de seeder die beginwaarden invult. De requestklasse voor het controleren van wijzigingen kreeg daarin ook een plek. Het diagram hielp om die samenhang te bespreken tijdens het uitwerken van de module.

Deze uitsnede beschrijft de verantwoordelijkheden in het ontwerp. De bewaarde ontwerp- en codebeelden zijn niet overal gelijk bijgewerkt; daaruit is dus geen definitief databaseschema af te leiden.

Realiseren: de instellingenmodule bouwen en toetsen

Van schermontwerp naar instellingenformulier

Ik begon de interface met een schermontwerp in Penpot. Na het inrichten van mijn lokale ontwikkelomgeving werkte ik dat uit met Blade en Livewire binnen het bestaande Laravel-portaal. Met Blade bouwde ik de weergavecomponenten; Livewire verbond de formuliergegevens met die weergave en verzorgde het dynamische deel van de interface.

Via de nieuwe menuoptie kwam een bevoegde beheerder bij de opgeslagen instellingen. Daar kon die bijvoorbeeld een naam wijzigen, een logo uploaden of een thema selecteren. Bij het versturen controleerde een Form Request de invoer, waarna de controller de waarden en afbeeldingen verwerkte voor gebruik in het portaal. In het formulier nam ik meldingen op voor ongeldige invoer en verwerkte wijzigingen.

Het activiteitendiagram werkte de beheerhandeling uit, inclusief de foutpaden. Als ophalen mislukte, moest een melding volgen en kon de beheerder de instellingen opnieuw openen. Bij een opslagfout ging de handeling terug naar het bewerken. Validatie en autorisatie stonden in dit oorspronkelijke ontwerp nog niet als afzonderlijke stappen; die licht ik hieronder toe.

Instellingen centraal bewaren en opvragen

De portaalnaam en andere instellingen waren op verschillende plaatsen nodig. Ik voegde een instellingenmodel met een tabel toe aan de bestaande database, legde de tabelstructuur vast in een migratie en vulde de beginwaarden met een seeder. Een helperfunctie bundelde vervolgens het ophalen van instellingen. Daardoor hoefde ik die opvraaglogica niet in iedere controller of weergave opnieuw te schrijven.

Instellingen worden vaak gelezen en relatief weinig gewijzigd. Vanuit die gedachte nam ik caching op om databaseverzoeken te beperken. De bewaarde codebeelden tonen een cache-opvraag met een databasefallback en het schrijven naar de cache na het opslaan. Hoe de cache volledig werd gevuld en ververst, is daarmee niet vastgesteld; ook heb ik geen meting van snelheidswinst.

Validatie bij de aanvraag houden

Een tekstveld, afbeelding en themakeuze vragen elk om andere controles. Voor uploads golden bijvoorbeeld grenzen aan bestandstype en grootte, terwijl het gekozen thema in de configuratie moest bestaan. Ik bracht de regels en foutmeldingen onder in een Laravel Form Request: een aparte klasse die de aanvraag controleert voordat de controller de wijziging verwerkt.

Validatie kon ook in de controllermethoden staan. In mijn verantwoording beschreef ik het risico dat de regels dan over meerdere methoden verspreid zouden raken. Met de Form Request hield ik ze bij elkaar en bleef de controller gericht op het verwerken van de invoer. Voor afbeeldingen maakte ik een uploadvak waar een beheerder bestanden naartoe kon slepen; voor de opslag sloot ik aan op de bestaande mediaoplossing.

Wat de tests lieten zien

Ik schreef unit- en featuretests voor het instellingenmodel en de controller, zodat ik opslag en verzoekafhandeling na wijzigingen opnieuw kon controleren. De bewaarde PHPUnit-run bevatte mijn uitbreiding én bestaande tests van het portaal en eindigde met 58 geslaagde en 9 mislukte tests. Bij drie zichtbare fouten was een externe testafbeelding niet bereikbaar. Van alle negen fouten samen zijn de oorzaak en het eventuele herstel niet volledig vastgelegd.

Daarnaast hield ik de acceptatie van de requirements bij. De acceptatietabel registreert verschillende instellingenhandelingen als afgerond, met beperkingen bij het beheer van rollen en permissies. Dat is een afzonderlijke registratie van geaccepteerde handelingen; zij verandert de uitslag van de geautomatiseerde tests niet. Geen van beide is voor deze terugblik opnieuw uitgevoerd.

Autorisatie uitbreiden binnen het portaal

De toegang tot de instellingen moest aansluiten op de bestaande rollen en permissies. Tijdens het werk werd deze taak groter: ik werkte ook aan controles elders in het ticketsysteem. Daarvoor gebruikte ik policies om regels rond modellen te bundelen en gates voor afzonderlijke acties. Zo kon ik de controles binnen de bestaande Laravel-structuur organiseren.

Mijn presentatie en stageverslag beschrijven die bredere uitvoering. De bewaarde codefragmenten laten daar een deel van zien; volledige dekking van alle routes en permissies is daarmee niet aangetoond.

Een thema kiezen en een thema toevoegen

Voor de thema’s bouwde ik voort op de bestaande Tailwind-opzet, met een apart bestand met kleurvariabelen per thema. Een beheerder kon op de instellingenpagina kiezen uit de geregistreerde thema’s. Voor een nieuw thema moest een ontwikkelaar eerst de configuratie en een bijbehorend CSS-bestand toevoegen. In het implementatieplan beschreef ik die stappen, zodat duidelijk was welk werk via de beheerpagina kon en waarvoor nog ontwikkeling nodig was.

Adviseren: de oplossing onderbouwen en overdragen

Om de technische samenhang uit te leggen werkte ik een architectuuradvies uit met het C4-model. Op componentniveau liet ik zien hoe de routes, controller, autorisatie, het formulier en de opslag samenwerkten.

Het diagram bevat zowel mijn uitbreiding als de bestaande voorzieningen waarop die steunde. In de onderbouwing legde ik mijn keuzes voor onder meer de helper en Form Request uit. Het implementatieplan maakte de overdracht praktisch: hoe richt je de opslag in met de migratie en seeder, voeg je een thema toe en controleer je de uitbreiding?

Mijn begeleider reviewde mijn code en gaf feedback op het schermontwerp en de documentatie. Ik verwerkte die opmerkingen tijdens het project. Volgens mijn stageverslag werd mijn ontwikkelbranch samengevoegd met de gezamenlijke ontwikkelbranch. Bij de eindpresentatie demonstreerde ik de uitbreiding en lichtte ik mijn technische keuzes toe. Daarmee leverde ik de beheerpagina, de onderbouwing en de implementatie-instructies samen over.

De oorspronkelijke applicatie is voor deze terugblik niet opnieuw uitgevoerd. De documentatie, presentatie en bewaarde code- en testbeelden onderbouwen de interne integratie en demonstratie; productiegebruik is niet vastgesteld.