Local Development Setup

Set up a complete local development environment for Viax using Laragon, which provides Apache, MySQL, and PHP in a single package.

This guide focuses on Windows with Laragon. For macOS/Linux, use MAMP, XAMPP, or manual Apache/MySQL setup.

Why Local Development?

Faster Development

No network latency, instant response times for API calls

Offline Work

Develop without internet connection

Safe Testing

Test destructive operations without affecting production data

Full Control

Complete access to database, logs, and server configuration

Step 1: Install Laragon

Download Laragon

Visit Laragon Website

Go to laragon.org

Download Full Version

Download Laragon Full (includes Apache, MySQL, PHP, Redis, Memcached)File size: ~150 MB

Run Installer

Double-click the installer
Choose installation directory (default: C:\laragon)
Complete installation wizard

Start Laragon

Launch Laragon

Open Laragon from Start Menu or desktop shortcut

Start Services

Click “Start All” button (bottom-left)Services that will start:

Apache (port 80)
MySQL (port 3306)

Verify Services

Check that icons turn green:

🟢 Apache
🟢 MySQL

Test Apache

Open browser and visit: http://localhostYou should see Laragon welcome page

Step 2: Set Up Backend

Copy Backend Files

Using PowerShell
Manual Copy

# Navigate to Viax project
cd C:\path\to\viax

# Copy backend to Laragon www directory
Copy-Item -Path .\backend -Destination C:\laragon\www\viax\backend -Recurse

# Verify
Test-Path C:\laragon\www\viax\backend\health.php

Open File Explorer
Navigate to your Viax project folder
Copy the backend folder
Navigate to C:\laragon\www
Create folder viax
Paste backend inside viax

Final structure:

C:\laragon\www\viax\backend\
├── auth/
├── conductor/
├── user/
├── admin/
├── config/
└── health.php

Verify Backend URL

Open browser and test:

http://localhost/viax/backend/health.php

Expected response:

{"status":"ok","timestamp":"2024-11-01 10:30:00"}

Step 3: Set Up Database

Create Database

HeidiSQL (Recommended)
phpMyAdmin
Command Line

HeidiSQL is included with Laragon.

Open HeidiSQL

Laragon > Database button > Opens HeidiSQL automatically

Connect to MySQL

Connection should be automatic:

Host: localhost
User: root
Password: (empty by default)

Create Database

Right-click on connection
“Create new” > “Database”
Name: viax
Collation: utf8mb4_unicode_ci
Click OK

Access phpMyAdmin

Laragon > Menu > MySQL > phpMyAdminOr visit: http://localhost/phpmyadmin

Create Database

Click “New” in left sidebar
Database name: viax
Collation: utf8mb4_unicode_ci
Click “Create”

# Open Laragon terminal
# Laragon > Terminal button

mysql -u root -p
# Press Enter (no password by default)

CREATE DATABASE viax CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
SHOW DATABASES;
EXIT;

Import Database Schema

Locate SQL File

Find the database file in your Viax project:

basededatos.sql or
basededatosfinal.sql

Import in HeidiSQL

Select viax database in left panel
File > Load SQL file
Select your .sql file
Click “Execute” (F9)
Wait for import to complete

Verify Tables

Expand viax database in HeidiSQL. You should see:

usuarios
conductores
solicitudes_servicio
viajes
documentos_conductor
configuracion_precios
administradores
audit_logs
empresas

Alternative: Import via Command Line

mysql -u root viax < C:\path\to\basededatos.sql

Configure Database Connection

File: C:\laragon\www\viax\backend\config\database.php

<?php
class Database {
    private $host = 'localhost';
    private $db_name = 'viax';
    private $username = 'root';
    private $password = 'root';  // Laragon default (or empty '')
    private $conn;
    
    public function getConnection() {
        $this->conn = null;
        
        try {
            $dsn = "mysql:host={$this->host};dbname={$this->db_name};charset=utf8mb4";
            $this->conn = new PDO($dsn, $this->username, $this->password);
            $this->conn->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
            $this->conn->setAttribute(PDO::ATTR_DEFAULT_FETCH_MODE, PDO::FETCH_ASSOC);
        } catch(PDOException $exception) {
            error_log("Connection error: " . $exception->getMessage());
            throw new Exception("Database connection failed");
        }
        
        return $this->conn;
    }
}
?>

Laragon’s default MySQL password is root. Some installations use empty password ''.

Step 4: Install PHP Dependencies

Install Composer (if not included)

Laragon usually includes Composer. Verify:

# Open Laragon terminal
composer --version

If not installed:

Laragon > Menu > Tools > Quick add > Composer
Or download from getcomposer.org

Install Backend Dependencies

# Open Laragon terminal
cd C:\laragon\www\viax\backend

# Install dependencies
composer install

# Verify installation
ls vendor/

Installed packages:

PHPMailer (email sending)
JWT library (future authentication)
Other PHP dependencies

Step 5: Configure Flutter for Local Backend

For Android Emulator

Android emulator maps localhost to 10.0.2.2:

flutter run --dart-define=API_BASE_URL=http://10.0.2.2/viax/backend

For Physical Android Device

Find Your Local IP

ipconfig
# Look for "IPv4 Address" (e.g., 192.168.1.100)

Connect Device to Same WiFi

Ensure your phone is on the same network as your computer

Run App

flutter run --dart-define=API_BASE_URL=http://192.168.1.100/viax/backend

For iOS Simulator

iOS Simulator can use localhost:

flutter run --dart-define=API_BASE_URL=http://localhost/viax/backend

Permanent Configuration (Development)

Edit .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Viax Local (Emulator)",
      "request": "launch",
      "type": "dart",
      "program": "lib/main.dart",
      "args": [
        "--dart-define=API_BASE_URL=http://10.0.2.2/viax/backend"
      ]
    },
    {
      "name": "Viax Local (Device - Update IP)",
      "request": "launch",
      "type": "dart",
      "program": "lib/main.dart",
      "args": [
        "--dart-define=API_BASE_URL=http://192.168.1.100/viax/backend"
      ]
    }
  ]
}

Step 6: Test the Setup

Test Backend Endpoints

Health Check
System Verification
Test Login Endpoint

curl http://localhost/viax/backend/health.php

Expected:

{"status":"ok"}

curl http://localhost/viax/backend/verify_system_json.php

Expected:

{
  "success": true,
  "database": "connected",
  "tables": [...],
  "php_version": "8.3.x"
}

Test from Flutter App

Run the App

flutter run --dart-define=API_BASE_URL=http://10.0.2.2/viax/backend

Test Registration

Open the app
Tap “Crear cuenta” (Create account)
Fill in registration form
Submit

Verify in Database

Open HeidiSQL and check usuarios table:

SELECT * FROM usuarios ORDER BY id DESC LIMIT 1;

You should see the new user you just created.

Development Workflow

Daily Workflow

Start Services

Open Laragon
Click “Start All”
Wait for services to turn green

Start Development

cd C:\path\to\viax
flutter run --dart-define=API_BASE_URL=http://10.0.2.2/viax/backend

Monitor Logs

Flutter logs: In terminal where app is running
Backend logs: C:\laragon\www\viax\backend\logs\
Apache logs: C:\laragon\bin\apache\apache-X.X.X\logs\
MySQL logs: Laragon > Menu > MySQL > Log file

Hot Reload

Press r in Flutter terminal for hot reload
Press R for hot restart
Press q to quit

Database Development

View Live Data:

-- Recent users
SELECT * FROM usuarios ORDER BY fecha_registro DESC LIMIT 10;

-- Active trips
SELECT * FROM solicitudes_servicio WHERE estado = 'pendiente';

-- Online drivers
SELECT * FROM conductores WHERE disponibilidad = 1;

Reset Test Data:

-- Clear all trips
DELETE FROM viajes;
DELETE FROM solicitudes_servicio;

-- Clear test users (keep admin)
DELETE FROM usuarios WHERE id > 1;

-- Reset auto-increment
ALTER TABLE usuarios AUTO_INCREMENT = 2;

Backend Development

Enable Error Display: Add to top of PHP files during development:

<?php
// DEVELOPMENT ONLY - Remove in production
error_reporting(E_ALL);
ini_set('display_errors', 1);
ini_set('log_errors', 1);
ini_set('error_log', __DIR__ . '/logs/php_errors.log');

// Your code...
?>

Logging:

// Log to file
error_log("Debug info: " . json_encode($data));

// Log to custom file
file_put_contents(
    __DIR__ . '/logs/debug.log',
    date('Y-m-d H:i:s') . " - " . json_encode($data) . "\n",
    FILE_APPEND
);

Troubleshooting

Laragon won't start

Port conflicts:

Check if port 80 is in use:
```
netstat -ano | findstr :80
```
Stop conflicting service:
- Skype (uses port 80)
- IIS (Windows web server)
- Other web servers
Or change Apache port:
- Laragon > Menu > Apache > httpd.conf
- Change Listen 80 to Listen 8080
- Restart Laragon
- Use http://localhost:8080/viax/backend

Database connection failed

Solutions:

Verify MySQL is running (green icon in Laragon)

Check credentials:

$username = 'root';
$password = 'root';  // or '' (empty)

Test connection manually:

mysql -u root -p
# Enter password: root
SHOW DATABASES;

Check database exists:
```
SHOW DATABASES LIKE 'viax';
```

404 Not Found on backend URLs

Check:

Files are in correct location:
- Should be: C:\laragon\www\viax\backend\
- Not: C:\laragon\www\backend\
Verify URL path:
- Correct: http://localhost/viax/backend/health.php
- Wrong: http://localhost/backend/health.php
Check file permissions (should auto-set by Laragon)

Composer not found

Install Composer:

Laragon > Menu > Tools > Quick add > Composer
Restart Laragon
Verify: composer --version

Or download from getcomposer.org

Flutter can't connect from emulator

Android Emulator:

Must use 10.0.2.2 not localhost

Verify with:

# In emulator via adb shell
curl http://10.0.2.2/viax/backend/health.php

Physical Device:

Must be on same WiFi network
Use computer’s IP (not localhost)
Disable Windows Firewall temporarily to test

Email sending not working

PHPMailer Configuration:For local development, configure SMTP in backend:

// backend/auth/email_service.php
$mail->SMTPDebug = 2; // Enable debug output
$mail->Host = 'smtp.gmail.com';
$mail->SMTPAuth = true;
$mail->Username = 'your-email@gmail.com';
$mail->Password = 'your-app-specific-password';
$mail->SMTPSecure = 'tls';
$mail->Port = 587;

Or use Mailtrap.io for testing emails.

Advanced Configuration

Enable PHP Extensions

Edit php.ini

Laragon > Menu > PHP > php.ini

Uncomment Extensions

Remove ; from extensions you need:

extension=gd
extension=mysqli
extension=pdo_mysql
extension=openssl
extension=mbstring

Restart Apache

Laragon > Stop All > Start All

Virtual Hosts (Optional)

Create a pretty URL like viax.local:

Create Virtual Host

Laragon > Menu > Apache > sites-enabled > AddContent:

<VirtualHost *:80>
    DocumentRoot "C:/laragon/www/viax/backend"
    ServerName viax.local
    <Directory "C:/laragon/www/viax/backend">
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

Update Hosts File

Edit C:\Windows\System32\drivers\etc\hosts (as Administrator):Add:

127.0.0.1 viax.local

Restart Apache

Laragon > Stop All > Start All

Test

Visit: http://viax.local/health.phpUse in Flutter:

--dart-define=API_BASE_URL=http://viax.local

Performance Tips

Increase PHP Memory

In php.ini:

memory_limit = 256M
upload_max_filesize = 20M
post_max_size = 20M

Enable OpCache

In php.ini:

opcache.enable=1
opcache.memory_consumption=128

MySQL Optimization

In HeidiSQL, run:

SET GLOBAL innodb_buffer_pool_size=256M;

Disable Xdebug

Comment out in php.ini:

;zend_extension=xdebug

Useful Laragon Commands

# Quick access
Laragon > Terminal    # Opens terminal in www folder
Laragon > Root        # Opens C:\laragon in explorer
Laragon > www         # Opens C:\laragon\www in explorer

# Database
Laragon > Database    # Opens HeidiSQL
Laragon > Menu > MySQL > phpMyAdmin

# Logs
Laragon > Menu > Apache > Error log
Laragon > Menu > MySQL > Error log

# Configuration
Laragon > Menu > Apache > httpd.conf
Laragon > Menu > PHP > php.ini
Laragon > Menu > MySQL > my.ini

Local Development Ready! You now have a complete local environment for Viax development with hot reload, database access, and full debugging capabilities.

Get Started

Core Concepts

Setup & Deployment

​Local Development Setup

​Why Local Development?

Faster Development

Offline Work

Safe Testing

Full Control

​Step 1: Install Laragon

​Download Laragon

​Start Laragon

​Step 2: Set Up Backend

​Copy Backend Files

​Verify Backend URL

​Step 3: Set Up Database

​Create Database

​Import Database Schema

​Configure Database Connection

​Step 4: Install PHP Dependencies

​Install Composer (if not included)

​Install Backend Dependencies

​Step 5: Configure Flutter for Local Backend

​For Android Emulator

​For Physical Android Device

​For iOS Simulator

​Permanent Configuration (Development)

​Step 6: Test the Setup

​Test Backend Endpoints

​Test from Flutter App

​Development Workflow

​Daily Workflow

​Database Development

​Backend Development

​Troubleshooting

​Advanced Configuration

​Enable PHP Extensions

​Virtual Hosts (Optional)

​Performance Tips

Increase PHP Memory

Enable OpCache

MySQL Optimization

Disable Xdebug

​Useful Laragon Commands

Build docs developers (and LLMs) love

Local Development Setup

Why Local Development?

Step 1: Install Laragon

Download Laragon

Start Laragon

Step 2: Set Up Backend

Copy Backend Files

Verify Backend URL

Step 3: Set Up Database

Create Database

Import Database Schema

Configure Database Connection

Step 4: Install PHP Dependencies

Install Composer (if not included)

Install Backend Dependencies

Step 5: Configure Flutter for Local Backend

For Android Emulator

For Physical Android Device

For iOS Simulator

Permanent Configuration (Development)

Step 6: Test the Setup

Test Backend Endpoints

Test from Flutter App

Development Workflow

Daily Workflow

Database Development

Backend Development

Troubleshooting

Advanced Configuration

Enable PHP Extensions

Virtual Hosts (Optional)

Performance Tips

Useful Laragon Commands