Skip to main content
Set up your local development environment for Zoo Arcadia with PHP, MySQL/MariaDB, and Node.js.

​
Prerequisites

Before starting development, ensure you have the following installed:

PHP 8.2+

With Apache or PHP built-in server

MySQL/MariaDB

Version 8.0+ or MariaDB 11.4+

Node.js 18+

For asset compilation with Gulp

Composer

For PHP dependency management

​
Installation Steps

1

Clone the Repository

Clone the Zoo Arcadia repository to your local machine:
git clone https://github.com/your-username/zoo-arcadia.git
cd zoo-arcadia
2

Install Dependencies

Install both PHP and Node.js dependencies:
composer install
3

Configure Environment Variables

Copy the example environment file and configure it:
cp .env.example .env
Edit .env with your local configuration:
.env
# Database Configuration
DB_HOST=localhost
DB_NAME=zoo_arcadia
DB_USER=root
DB_PASS=root

# SMTP Configuration (for contact forms)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=tls
SMTP_USER=[email protected]
SMTP_PASS=your-app-password
SMTP_FROM_EMAIL=[email protected]
SMTP_FROM_NAME=Arcadia Zoo

# Zoo Contact Email
ZOO_EMAIL=[email protected]

# Environment
APP_ENV=development

# Cloudinary (Optional - for image uploads)
CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=your-api-key
CLOUDINARY_API_SECRET=your-api-secret
4

Initialize the Database

Run the database deployment script:
deploy_database.bat
The script automatically detects your MySQL/MariaDB installation from:
  • C:\Program Files\MariaDB 11.4\bin\mariadb.exe
  • C:\xampp\mysql\bin\mysql.exe
  • C:\wamp64\bin\mysql\mysql8.0.31\bin\mysql.exe
5

Build Assets

Compile SCSS and JavaScript files:
npx gulp buildCss
npx gulp buildJs
6

Start Development Server

Start the PHP development server:
php -S localhost:3001 -t public
Or use Apache/XAMPP/WAMP and point the document root to the public/ directory.

​
PHP Configuration

​
Required Extensions

Ensure the following PHP extensions are enabled in php.ini: 
extension=gd
extension=pdo_mysql
extension=zip
extension=curl
extension=mbstring
extension=openssl

​
SSL Certificate Setup (Windows)

On Windows, you may need to configure SSL certificates for SMTP to work properly.
  1. Download the latest CA bundle from curl.se
  2. Save it to a location like C:\php\cacert.pem
  3. Update your php.ini:
php.ini
[curl]
curl.cainfo = "C:\php\cacert.pem"

[openssl]
openssl.cafile = "C:\php\cacert.pem"

​
Switching Between Environments

Zoo Arcadia provides helper scripts to switch between local and Docker configurations:
Run switch-to-local.bat (Windows) to configure for local development:
switch-to-local.bat
@echo off
echo Switching to Local configuration...

REM Create .env.local backup if needed
if not exist .env.local (
    copy .env .env.local >nul
)

REM Update .env for local development
powershell -Command "(Get-Content .env) -replace 'DB_HOST=db', 'DB_HOST=localhost' -replace 'DB_USER=zoo_user', 'DB_USER=root' -replace 'DB_PASS=zoo_password', 'DB_PASS=root' | Set-Content .env"

echo ✅ Switched to Local configuration
This changes:
  • DB_HOST: db → localhost
  • DB_USER: zoo_user → root
  • DB_PASS: zoo_password → root

​
Database Configuration

​
Connection Settings

For local development, use these default credentials:
SettingValue
Hostlocalhost
Port3306
Databasezoo_arcadia
Userroot
Passwordroot (or your local MySQL password)

​
Database Users

The initialization script creates two database users:
  • Username: zoo_admin@localhost
  • Password: secure_password (change in production)
  • Privileges: ALL PRIVILEGES on zoo_arcadia.*
  • Purpose: Database administration and migrations
  • Username: zoo_app@localhost
  • Password: app_password (change in production)
  • Privileges: SELECT, INSERT, UPDATE, DELETE on zoo_arcadia.*
  • Purpose: Runtime application queries

​
Verify Installation

Check that everything is working:
1

Test Database Connection

mysql -u root -p zoo_arcadia
Run a test query:
SELECT COUNT(*) FROM users;
2

Check Compiled Assets

Verify that CSS and JS files exist:
ls -la public/build/css/
ls -la public/build/js/
3

Access the Application

Open your browser to:
http://localhost:3001
You should see the Zoo Arcadia homepage.

​
Common Issues

If port 3001 is busy, use a different port:
php -S localhost:8000 -t public
Update gulpfile.js proxy settings accordingly.
  • Verify MySQL/MariaDB is running
  • Check credentials in .env
  • Ensure the zoo_arcadia database exists
  • Test connection: mysql -u root -p
  • Clear node_modules/: rm -rf node_modules && npm install
  • Check Node.js version: node --version (requires 18+)
  • Run Gulp tasks individually: npx gulp buildCss, npx gulp buildJs
  • Install SSL certificates (see PHP Configuration section)
  • Use an app-specific password for Gmail
  • Test with a different SMTP provider

​
Next Steps

Docker Deployment

Learn how to run Zoo Arcadia with Docker

Database Schema

Explore the database structure

Asset Pipeline

Understand the build process

API Reference

Browse the API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us