Handleiding voor het Documenteren van een Verouderde PHP-Applicatie met Custom Framework voor Junior Ontwikkelaars Inleiding Deze handleiding helpt jou, als junior ontwikkelaar met basiskennis, bij het analyseren, structureren en documenteren van je verouderde PHP-applicatie met een zelfgemaakt (custom) framework. Het doel is om inzicht te krijgen in de software, kritieke onderdelen te identificeren en goede documentatie te maken voor toekomstig onderhoud. Stap 1: Voorbereiding en Vooronderzoek 1.1 Maak een Back-up Voordat je begint, maak een volledige kopie van de codebase. Zo kun je altijd terugkeren als er iets misgaat. 1.2 Verzamel Documentatie en Logboeken Bekijk beschikbare documentatie, changelogs, en projectinformatie. Vraag indien mogelijk collega’s of vorige ontwikkelaars om aanvullende uitleg. 1.3 Stel een Basiskennis op Zorg dat je begrijpt wat PHP is, hoe een webapplicatie werkt, en wat een framework doet. Dit helpt je om patronen te herkennen. Stap 2: Code Analyseren 2.1 Open de Code Gebruik een goede code-editor zoals Visual Studio Code, PHPStorm, of Sublime Text. 2.2 Zoek naar de Structuur - Bestanden en mappen: Noteer de hoofdstructuur. - Entry point: Vind het startbestand (bijvoorbeeld index.php). 2.3 Identificeer Kritieke Componenten - Databaseverbindingen: Zoek naar code die verbinding maakt met de database (bijvoorbeeld PDO of mysqli). - Belangrijke functies of classes: Let op classes met namen als “Controller”, “Model”, of “View”. - API’s of externe services: Noteer koppelingen naar andere systemen. 2.4 Dependencydiagrammen maken - Maak een overzicht van hoe verschillende onderdelen afhankelijk zijn van elkaar. - Gebruik bijvoorbeeld een schematische tekening met pijlen. Voorbeeld: ``` index.php → Router → Controller → Model → Database ``` Stap 3: Betrouwbare Vastlegging van Bedrijfslogica 3.1 Begrijp de Kernfuncties - Loop door de belangrijkste functies en functies die regelmatig worden gebruikt. - Stel vragen: Wat doet deze code? Waarom is deze belangrijk? 3.2 Schrijf Beschrijvingen - Voor elke belangrijke class of functie, noteer: - Wat doet het? - Welke parameters verwacht het? - Wat retourneert het? - Zijn er speciale voorwaarden? 3.3 Gebruik Commentaar en Diagrammen - Voeg korte commentaar toe in de code waar nodig. - Maak eenvoudige flowcharts of diagrammen om bedrijfsprocessen te visualiseren. Voorbeeld: ```php // Functie voor het verwerken van gebruikersaanvragen function processRequest($request) { // Validatie // Verwerking // Response } ``` Stap 4: Documentatie Overzetten naar Een Gestructureerd Formaat 4.1 Kies een Documentatieformaat - Bijvoorbeeld Markdown (.md), Word (.docx), of een wiki. 4.2 Maak een Inhoudsopgave - Inleiding en overzicht - Structuur van de code - Kritieke componenten - Dependencydiagrammen - Bedrijfslogica - Onderhoudsrichtlijnen 4.3 Documenteer Stap voor Stap - Voeg voorbeelden toe uit de code. - Gebruik screenshots van de editor of diagrammen indien nodig. Stap 5: Onderhoudsrichtlijnen en Best Practices 5.1 Codestandaarden - Stel eenvoudige regels op: bijvoorbeeld: gebruik duidelijke naamgeving, commentaar, en vermijd spaghetticode. 5.2 Testen en Debuggen - Beschrijf basisstappen om de app te testen. - Bijvoorbeeld: controleer databaseverbindingen, logbestanden bekijken. 5.3 Veiligheid en Updates - Waarschuw voor verouderde afhankelijkheden. - Raadpleeg beveiligingsrichtlijnen voor PHP. 5.4 Aanbevelingen voor Verbeteringen - Documenteer zwakke plekken. - Stel voor om bepaalde delen te refactoren of te upgraden. Stap 6: Validatie en Kennisoverdracht 6.1 Review - Vraag een collega of meer ervaren ontwikkelaar om je documentatie te bekijken. 6.2 Presentatie - Leg tijdens een korte sessie uit wat je hebt gedaan. - Vraag om feedback. 6.3 Documentatie Bijhouden - Maak het een gewoonte om documentatie bij te werken bij veranderingen. Veelvoorkomende Valkuilen en Tips - Valkuil: Te weinig documentatie. Tip: Noteer alles wat je ontdekt, ook kleine details. - Valkuil: Verkeerde interpretatie van code. Tip: Test functies in een veilige omgeving. - Valkuil: Moeilijk te begrijpen code. Tip: Stel vragen en gebruik debugging tools. - Tip: Gebruik versiebeheer (zoals Git) om veranderingen te volgen. Samenvatting Door deze stappen te volgen, krijg je een duidelijk beeld van je oude PHP-applicatie. Goede documentatie maakt het makkelijker om de code te onderhouden, verbeteren en veilig te houden, zelfs als je zelf niet alles hebt geschreven. Veel succes met je project!

# Technische Handleiding: Documenteren van Verouderde PHP-applicatie ## Inleiding Deze handleiding helpt je bij het documenteren van een verouderde PHP-applicatie met een custom framework. We richten ons op praktische stappen die je kunt volgen, zelfs met beperkte code-analyse ervaring. ## Fase 1: Voorbereiding en Analyse ### 1.1 Omgevingssetup ```bash # Maak een documentatiestructuur aan mkdir documentatie cd documentatie mkdir codebase business-logica afhankelijkheden onderhoud ``` ### 1.2 Eerste Verkenning - **Start met een overzicht**: Maak een lijst van alle mappen en bestanden - **Identificeer toegangspunten**: Zoek naar `index.php`, `app.php`, of andere startbestanden - **Check configuratie**: Zoek naar configuratiebestanden (vaak in `/config` of `/includes`) **Voorbeeld verkenning:** ```php // Voorbeeld: hoofd toegangspunt vinden // Meestal in de root map: index.php <?php require_once 'config/database.php'; require_once 'framework/core.php'; $app = new CustomFramework(); $app->run(); ``` ### 1.3 Codebase Inventory Maak een inventarisatie van: - Aantal PHP-bestanden - Mapstructuur - Database connecties - Externe API calls ## Fase 2: Kritieke Componenten Identificeren ### 2.1 Framework Kern Zoek naar deze essentiële onderdelen: **Routering:** ```php // Voorbeeld: routing mechanisme class Router { public function route($url) { // Zoek naar patroonherkenning if (preg_match('/\/user\/(\d+)/', $url, $matches)) { return new UserController($matches[1]); } } } ``` **Database Laag:** ```php // Voorbeeld: custom database klasse class Database { private $connection; public function query($sql) { // Zoek naar SQL executie return mysqli_query($this->connection, $sql); } } ``` ### 2.2 Belangrijke Mappen Documenteer deze mappen (indien aanwezig): - `/controllers` - Business logica - `/models` - Data verwerking - `/views` - Presentatie laag - `/lib` of `/framework` - Kern functionaliteit - `/helpers` - Hulpfuncties ## Fase 3: Afhankelijkheden in Kaart Brengen ### 3.1 Externe Afhankelijkheden **PHP Extensies:** ```php // Check required extensies in code if (!extension_loaded('mysqli')) { die('MySQLi extensie vereist'); } ``` **Database:** - MySQL/MariaDB versie - PostgreSQL - SQLite **Server Requirements:** - PHP versie (zoek naar `phpversion()` checks) - Web server type (Apache/Nginx) ### 3.2 Interne Afhankelijkheden Maak een dependency map: ``` App Kernel ↓ Router → Controller → Model → Database ↓ View → Template Engine ``` ## Fase 4: Bedrijfslogica Documenteren ### 4.1 Use Cases Identificeren Voor elke belangrijke functionaliteit: **Voorbeeld gebruikersbeheer:** ```markdown ## Gebruikersbeheer ### Functionaliteiten: 1. Registratie - Validatie email - Wachtwoord hashing - Email verificatie 2. Login - Authenticatie - Session management - Remember me functionaliteit 3. Profiel beheer - Gegevens wijzigen - Avatar upload ``` ### 4.2 Code Flow Documenteren **Voorbeeld bestelproces:** ```php // Stap 1: Controller ontvangt request class OrderController { public function create() { // Valideer input $validator = new OrderValidator($_POST); if ($validator->isValid()) { // Verwerk bestelling $order = new Order($_POST); $order->save(); } } } ``` ## Fase 5: Praktische Documentatie ### 5.1 Installatiehandleiding ```markdown # Installatie ## Vereisten: - PHP 5.6+ - MySQL 5.5+ - Apache met mod_rewrite ## Stappen: 1. Database aanmaken 2. Configuratie aanpassen: `/config/database.php` 3. Document root instellen op `/public` 4. Permissies instellen: `chmod 755 uploads/` ``` ### 5.2 Veelvoorkomende Taken **Nieuwe pagina toevoegen:** ```markdown ## Nieuwe pagina toevoegen 1. Route toevoegen in `/config/routes.php`: ```php $router->add('/nieuwe-pagina', 'NieuweController@actie'); ``` 2. Controller aanmaken: ```php class NieuweController { public function actie() { return view('nieuwe-pagina'); } } ``` 3. View aanmaken in `/views/nieuwe-pagina.php` ``` ## Fase 6: Onderhoudsrichtlijnen ### 6.1 Veiligheid **Veiligheidscontroles:** ```php // GOED: Input validatie $gebruiker_id = filter_var($_GET['id'], FILTER_VALIDATE_INT); if ($gebruiker_id === false) { throw new InvalidArgumentException('Ongeldig ID'); } // SLECHT: Direct gebruik $gebruiker_id = $_GET['id']; // Kwetsbaar voor SQL injectie ``` ### 6.2 Debugging Tips **Common Issues:** ```php // Foutopsporing database queries class Database { public function query($sql) { // Log alle queries voor debugging error_log("SQL: " . $sql); return mysqli_query($this->connection, $sql); } } ``` ## Fase 7: Kennisoverdracht ### 7.1 Documentatie Template ```markdown # [Component Naam] ## Doel: [Korte beschrijving van doel] ## Locatie: [Bestandspad] ## Gebruik: ```php // Voorbeeld gebruik $instance = new Component(); $result = $instance->method(); ``` ## Afhankelijkheden: - [Lijst van afhankelijkheden] ## Belangrijke Methodes: - `methodeNaam()` - [beschrijving] ## Veelvoorkomende Problemen: 1. [Probleem 1] - [Oplossing] 2. [Probleem 2] - [Oplossing] ``` ### 7.2 Code Review Checklist - [ ] Zijn er hardcoded credentials? - [ ] Wordt input altijd gevalideerd? - [ ] Zijn SQL queries beveiligd? - [ ] Werkt error handling correct? - [ ] Zijn er deprecated PHP functies? ## Veelvoorkomende Valkuilen en Oplossingen ### Valkuil 1: Te Diep Graven **Probleem:** Je raakt overweldigd door details **Oplossing:** Focus eerst op hoog niveau, dan details ### Valkuil 2: Verouderde PHP Code **Probleem:** Oude PHP syntax (bijv. `mysql_*` functies) **Oplossing:** Documenteer welke updates nodig zijn ### Valkuil 3: Ontbrekende Comments **Probleem:** Geen uitleg bij complexe code **Oplossing:** Voeg comments toe tijdens analyse ## Tips voor Succes 1. **Begin Klein**: Documenteer eerst één module volledig 2. **Gebruik Tools**: PHPStorm, VS Code met PHP extensions 3. **Test je Documentatie**: Laat een collega het volgen 4. **Houd het Bij**: Werk documentatie bij bij wijzigingen 5. **Maak Screenshots**: Van belangrijke admin panels ## Hulpmiddelen ### Code Analyse: - **PHPStan** - Statische analyse - **PHPLOC** - Code metrics - **PHPCodeSniffer** - Coding standards ### Documentatie: - **Markdown** - Voor leesbare documentatie - **Diagrams.net** - Voor architectuur diagrams - **Swagger** - Voor API documentatie ## Conclusie Door deze stappen te volgen, creëer je een complete documentatieset die junior ontwikkelaars helpt de verouderde codebase te begrijpen en te onderhouden. Onthoud: goede documentatie is een levend document dat meegroeit met de applicatie. **Volgende Stappen:** 1. Begin met fase 1 deze week 2. Plan wekelijkse documentatie sessies 3. Review documentatie met ervaren ontwikkelaars 4. Houd een changelog bij van documentatie updates Succes met het documenteren van je PHP-applicatie!