Skip to main content

Development Setup & Workflow

Complete guide for setting up and working with the Profile PS3 codebase.

Prerequisites​

Required Software​

  • PHP: 8.3 or higher
  • Composer: 2.x (latest stable)
  • Node.js: 20.x (see .nvmrc for exact version)
  • npm: 10.x (comes with Node.js)
  • Git: For version control
  • Database: MySQL 8.0+ / MariaDB 10.3+ / SQLite 3.35+
  • Laravel Herd: Modern Laravel development environment (macOS/Windows)
  • VS Code: With PHP Intelephense, Laravel Extra Intellisense extensions
  • TablePlus or phpMyAdmin: Database management
  • Postman or Insomnia: API testing

Initial Setup​

1. Clone Repository​

cd Z:\Repos
git clone [email protected]:rhino-group/profileps3.git
cd profileps3

2. Install Dependencies​

# Install PHP dependencies
composer install

# Install Node dependencies
npm install

3. Environment Configuration​

# Copy environment file
cp .env.example .env

# Generate application key
php artisan key:generate

4. Configure Database​

Option A: SQLite (Quickest for development)

DB_CONNECTION=sqlite

Create database file:

touch database/database.sqlite

Option B: MySQL

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=profileps3
DB_USERNAME=root
DB_PASSWORD=

Create database:

mysql -u root -p
CREATE DATABASE profileps3;
exit;

5. Run Migrations & Seeders​

# Run migrations
php artisan migrate

# Seed database with sample data
php artisan db:seed

6. Build Frontend Assets​

# Development build
npm run dev

# Or production build
npm run build

7. Start Development Server​

# Option A: Using Laravel Herd (recommended)
# Herd automatically serves the application
# Access at: http://profileps3.test

# Option B: Using php artisan serve
php artisan serve
# Access at: http://localhost:8000

8. Login Credentials​

Default Admin Account:

Email: [email protected]
Password: password

Default User Account:

Email: [email protected]
Password: password

⚠️ Change these credentials immediately in production!

Development Workflow​

Running Development Services​

Profile PS3 includes a convenient composer run dev command that runs all services:

composer run dev

This concurrently runs:

  • php artisan serve — Laravel dev server (port 8000)
  • php artisan queue:listen — Queue worker for background jobs
  • php artisan pail --timeout=0 — Real-time log streaming
  • npm run dev — Vite dev server with HMR (Hot Module Replacement)

Or run individually:

# Terminal 1: Laravel
php artisan serve

# Terminal 2: Queue worker
php artisan queue:listen

# Terminal 3: Vite
npm run dev

# Terminal 4: Log viewer
php artisan pail

Database Management​

Fresh Migration (drops all tables and recreates):

php artisan migrate:fresh --seed

Rollback Last Migration:

php artisan migrate:rollback

Check Migration Status:

php artisan migrate:status

Run Specific Seeder:

php artisan db:seed --class=UserSeeder

Asset Compilation​

Development (with HMR):

npm run dev

Production Build (minified):

npm run build

Watch Mode (rebuild on file changes):

npm run watch

Filament Optimization​

Optimize Filament Assets:

php artisan filament:optimize

Clear Filament Cache:

php artisan filament:optimize-clear

Testing​

Running Tests​

Profile PS3 uses Pest for testing (modern PHPUnit alternative).

Run All Tests:

php artisan test

Run Specific Test File:

php artisan test tests/Feature/ProjectTest.php

Run Tests with Coverage:

php artisan test --coverage

Run Tests in Parallel (faster):

php artisan test --parallel

Writing Tests​

Feature Test Example (tests/Feature/ProjectTest.php):

use App\Models\User;
use App\Models\Project;

test('user can create project', function () {
    $user = User::factory()->create(['approved' => 'approved']);
    
    $this->actingAs($user);
    
    $response = $this->post('/app/projects', [
        'projectAddress' => '123 Main St',
        'projectCity' => 'Denver',
        'state_id' => 1,
        'country_id' => 1,
        'projectType' => 1,
        'projectStage' => 1,
    ]);
    
    $response->assertRedirect();
    expect(Project::count())->toBe(1);
});

test('unapproved user cannot create project', function () {
    $user = User::factory()->create(['approved' => 'pending']);
    
    $this->actingAs($user)
        ->get('/app')
        ->assertForbidden();
});

Unit Test Example (tests/Unit/ProjectTest.php):

use App\Models\Project;

test('project number is auto-generated', function () {
    $project = Project::factory()->create(['projectNum' => null]);
    
    expect($project->projectNum)->toStartWith('PRJ-');
    expect($project->projectNum)->toHaveLength(17);
});

Test Database​

Tests use in-memory SQLite by default:

phpunit.xml:

<env name="DB_CONNECTION" value="sqlite"/>
<env name="DB_DATABASE" value=":memory:"/>

Debugging​

Laravel Debugbar​

Enable in Development:

DEBUGBAR_ENABLED=true

Access debugbar at bottom of page to view:

  • SQL queries
  • Route information
  • Memory usage
  • Execution time
  • Session data

Logging​

View Logs:

tail -f storage/logs/laravel.log

# Or use Laravel Pail (better formatting)
php artisan pail

Log Channels:

  • single — All logs in one file
  • daily — Rotate logs daily
  • stack — Multiple channels
  • stderr — Output to stderr

Xdebug Setup (VS Code)​

Install Xdebug:

# macOS (via Homebrew)
pecl install xdebug

# Windows (via XAMPP/Herd)
# Already included

Configure php.ini:

[xdebug]
zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_port=9003

VS Code launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/app": "${workspaceFolder}"
      }
    }
  ]
}

Code Quality​

PHP CodeSniffer​

Run Linting:

./vendor/bin/phpcs

Auto-fix Issues:

./vendor/bin/phpcbf

PHPStan (Static Analysis)​

Profile PS3 uses Larastan (PHPStan for Laravel):

./vendor/bin/phpstan analyse

Configuration: phpstan.neon

Laravel Pint (Code Formatting)​

Format Code:

./vendor/bin/pint

Check Without Formatting:

./vendor/bin/pint --test

Git Workflow​

Branching Strategy​

  • main — Production-ready code
  • develop — Integration branch for features
  • feature/feature-name — Feature branches
  • fix/bug-name — Bug fix branches
  • release/version — Release branches

Commit Message Convention​

Follow Conventional Commits:

feat: add ProGanics BSM calculator
fix: resolve project deletion bug
docs: update calculator documentation
refactor: improve query performance
test: add project creation tests

Pull Request Checklist​

  • Tests passing (php artisan test)
  • Code linted (./vendor/bin/pint)
  • Static analysis passing (./vendor/bin/phpstan analyse)
  • Database migrations tested
  • Documentation updated
  • Changelog updated

Performance Optimization​

Caching​

Cache Configuration:

php artisan config:cache
php artisan route:cache
php artisan view:cache

Clear All Caches:

php artisan optimize:clear

Query Optimization​

Enable Query Logging:

DB::enableQueryLog();
// ... perform queries
dd(DB::getQueryLog());

Use Debugbar to identify N+1 queries.

Asset Optimization​

Minify Assets (production):

npm run build

Vite automatically:

  • Minifies JavaScript
  • Minifies CSS
  • Optimizes images
  • Generates asset hashes

Deployment​

Pre-Deployment Checklist​

  • Environment variables configured
  • Database backed up
  • Dependencies updated (composer install --no-dev)
  • Assets compiled (npm run build)
  • Tests passing
  • Migrations ready

Deployment Steps​

# 1. Pull latest code
git pull origin main

# 2. Install dependencies (production only)
composer install --optimize-autoloader --no-dev

# 3. Run migrations
php artisan migrate --force

# 4. Clear and cache
php artisan optimize:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan filament:optimize

# 5. Restart queue workers
php artisan queue:restart

# 6. Build frontend assets
npm ci
npm run build

Environment Variables (Production)​

APP_ENV=production
APP_DEBUG=false
APP_URL=https://profileps3.com

LOG_LEVEL=warning
LOG_CHANNEL=daily

SESSION_DRIVER=redis
CACHE_STORE=redis
QUEUE_CONNECTION=redis

MAIL_MAILER=mailgun
FILESYSTEM_DISK=s3

Troubleshooting​

Common Issues​

"Class not found" Errors:

composer dump-autoload

Asset Not Loading:

npm run build
php artisan optimize:clear

Permission Errors:

chmod -R 775 storage bootstrap/cache

Migration Errors:

php artisan migrate:fresh --seed

Getting Help​