Skip to content

Development Setup

This guide provides comprehensive instructions for setting up a local development environment for the Stratpoint Timesheet Application.

Prerequisites

System Requirements

Operating System: - macOS 10.15+ (Catalina or later) - Ubuntu 20.04 LTS or later - Windows 10/11 with WSL2

Hardware Requirements: - 8GB RAM minimum (16GB recommended) - 50GB free disk space - Multi-core processor (4+ cores recommended)

Required Software

Core Development Tools: - Git 2.30+ - Docker Desktop 4.0+ - Docker Compose 2.0+ - Node.js 16+ with npm - PHP 8.0+ (for local development without Docker) - Composer 2.0+

Recommended Tools: - Visual Studio Code or PhpStorm - Postman or Insomnia (API testing) - MySQL Workbench (database management) - Redis Desktop Manager (cache management)

Environment Setup

1. Repository Setup

Clone the Repository: 

# Clone the main repository
git clone https://github.com/stratpoint/timesheet-web.git
cd timesheet-web

# Set up Git configuration
git config user.name "Your Name"
git config user.email "your.email@stratpoint.com"

# Create development branch
git checkout -b feature/your-feature-name

Repository Structure: 

timesheet-web/
├── app/                    # Laravel application code
├── config/                 # Configuration files
├── database/              # Migrations and seeders
├── docker/                # Docker configuration
├── public/                # Web root and frontend assets
├── resources/             # Views and frontend source
├── routes/                # Route definitions
├── storage/               # Application storage
├── tests/                 # Test files
├── .env.example           # Environment template
├── docker-compose.yml     # Docker services
├── composer.json          # PHP dependencies
├── package.json           # Node.js dependencies
└── webpack.mix.js         # Asset compilation

2. Docker Development Environment

Start Development Environment: 

# Copy environment configuration
cp .env.example .env.local

# Edit environment variables for local development
nano .env.local

Environment Configuration (.env.local): 

# Application
APP_NAME="Timesheet Dev"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:8080

# Database
DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=timesheet_dev
DB_USERNAME=timesheet
DB_PASSWORD=timesheet123

# Cache
CACHE_DRIVER=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

# Redis
REDIS_HOST=redis
REDIS_PASSWORD=null
REDIS_PORT=6379

# Mail (for testing)
MAIL_MAILER=log
MAIL_HOST=localhost
MAIL_PORT=1025

# AWS (use local storage for development)
FILESYSTEM_DISK=local

# JWT
JWT_SECRET=your_dev_jwt_secret

# Debug
LOG_LEVEL=debug
LOG_ALL_DB_QUERIES=true

Docker Compose for Development: 

# docker-compose.dev.yml
version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: docker/Dockerfile.dev
    ports:
      - "8080:80"
    volumes:
      - .:/var/www/html
      - ./docker/apache/sites-available:/etc/apache2/sites-available
    environment:
      - APP_ENV=local
    depends_on:
      - mysql
      - redis
    networks:
      - timesheet-dev

  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: root123
      MYSQL_DATABASE: timesheet_dev
      MYSQL_USER: timesheet
      MYSQL_PASSWORD: timesheet123
    ports:
      - "3306:3306"
    volumes:
      - mysql_dev_data:/var/lib/mysql
      - ./database/dev-data:/docker-entrypoint-initdb.d
    networks:
      - timesheet-dev

  redis:
    image: redis:6.0-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_dev_data:/data
    networks:
      - timesheet-dev

  mailhog:
    image: mailhog/mailhog
    ports:
      - "1025:1025"
      - "8025:8025"
    networks:
      - timesheet-dev

volumes:
  mysql_dev_data:
  redis_dev_data:

networks:
  timesheet-dev:
    driver: bridge

Start Development Environment: 

# Build and start containers
docker-compose -f docker-compose.dev.yml up -d

# Install PHP dependencies
docker-compose exec app composer install

# Install Node.js dependencies
docker-compose exec app npm install

# Generate application key
docker-compose exec app php artisan key:generate

# Run database migrations
docker-compose exec app php artisan migrate

# Seed development data
docker-compose exec app php artisan db:seed --class=DevelopmentSeeder

# Build frontend assets
docker-compose exec app npm run dev

3. Local Development (Without Docker)

Install PHP and Extensions: 

# Ubuntu/Debian
sudo apt update
sudo apt install php8.0 php8.0-fpm php8.0-mysql php8.0-redis \
    php8.0-xml php8.0-mbstring php8.0-curl php8.0-zip \
    php8.0-gd php8.0-intl php8.0-bcmath php8.0-dev

# macOS (using Homebrew)
brew install php@8.0 mysql redis composer

Install and Configure MySQL: 

# Ubuntu/Debian
sudo apt install mysql-server-8.0

# macOS
brew install mysql
brew services start mysql

# Create development database
mysql -u root -p
CREATE DATABASE timesheet_dev;
CREATE USER 'timesheet'@'localhost' IDENTIFIED BY 'timesheet123';
GRANT ALL PRIVILEGES ON timesheet_dev.* TO 'timesheet'@'localhost';
FLUSH PRIVILEGES;

Install and Start Redis: 

# Ubuntu/Debian
sudo apt install redis-server
sudo systemctl start redis-server

# macOS
brew install redis
brew services start redis

Application Setup: 

# Install Composer dependencies
composer install

# Install Node.js dependencies
npm install

# Copy and configure environment
cp .env.example .env
php artisan key:generate

# Run migrations and seeders
php artisan migrate
php artisan db:seed

# Build frontend assets
npm run dev

# Start development server
php artisan serve --host=0.0.0.0 --port=8080

Development Workflow

1. Frontend Development

Asset Compilation: 

# Development build (with source maps)
npm run dev

# Watch for changes (auto-rebuild)
npm run watch

# Production build (optimized)
npm run production

# Hot module replacement (advanced)
npm run hot

Frontend Structure: 

public/app/
├── css/
│   ├── lib/           # Third-party CSS
│   └── mine/          # Custom styles
├── js/
│   ├── lib/           # Third-party JavaScript
│   └── mine/          # Application JavaScript
│       ├── app.module.js
│       ├── controllers/
│       ├── services/
│       ├── directives/
│       └── filters/
└── partials/          # AngularJS templates

Development Commands: 

# Lint JavaScript
npm run lint:js

# Lint CSS
npm run lint:css

# Run frontend tests
npm run test

# Format code
npm run format

2. Backend Development

Laravel Artisan Commands: 

# Generate controller
php artisan make:controller TimelogController --resource

# Generate model
php artisan make:model Timelog -m

# Generate migration
php artisan make:migration create_timelogs_table

# Generate seeder
php artisan make:seeder TimelogSeeder

# Generate middleware
php artisan make:middleware AuthenticateUser

# Generate job
php artisan make:job ProcessTimelogApproval

# Generate mail class
php artisan make:mail TimelogApprovalNotification

Database Operations: 

# Run migrations
php artisan migrate

# Rollback migrations
php artisan migrate:rollback

# Refresh database
php artisan migrate:refresh

# Seed database
php artisan db:seed

# Generate model factory
php artisan make:factory TimelogFactory

Queue and Job Processing: 

# Process queue jobs
php artisan queue:work

# Process specific queue
php artisan queue:work --queue=emails

# List failed jobs
php artisan queue:failed

# Retry failed jobs
php artisan queue:retry all

3. Testing

PHPUnit Configuration: 

<!-- phpunit.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="./vendor/phpunit/phpunit/phpunit.xsd"
         bootstrap="vendor/autoload.php"
         colors="true">
    <testsuites>
        <testsuite name="Unit">
            <directory suffix="Test.php">./tests/Unit</directory>
        </testsuite>
        <testsuite name="Feature">
            <directory suffix="Test.php">./tests/Feature</directory>
        </testsuite>
    </testsuites>
    <php>
        <server name="APP_ENV" value="testing"/>
        <server name="DB_CONNECTION" value="sqlite"/>
        <server name="DB_DATABASE" value=":memory:"/>
    </php>
</phpunit>

Running Tests: 

# Run all tests
php artisan test

# Run specific test suite
php artisan test --testsuite=Feature

# Run specific test
php artisan test tests/Feature/TimelogTest.php

# Run tests with coverage
php artisan test --coverage

# Run tests in parallel
php artisan test --parallel

Test Examples: 

// tests/Feature/TimelogTest.php
<?php

namespace Tests\Feature;

use Tests\TestCase;
use App\Models\User;
use App\Models\Timelog;

class TimelogTest extends TestCase
{
    public function test_user_can_create_timelog()
    {
        $user = User::factory()->create();

        $response = $this->actingAs($user)
            ->postJson('/api/v2/timelogs', [
                'startTime' => '2024-01-15 09:00:00',
                'stopTime' => '2024-01-15 17:00:00',
                'description' => 'Development work',
                'tasktype_id' => 1
            ]);

        $response->assertStatus(201)
                ->assertJsonStructure([
                    'header' => ['status', 'title'],
                    'body' => ['data']
                ]);

        $this->assertDatabaseHas('timelogs', [
            'user_id' => $user->id,
            'description' => 'Development work'
        ]);
    }
}

Debugging and Development Tools

1. Laravel Telescope (Development Profiler)

Installation: 

composer require laravel/telescope --dev
php artisan telescope:install
php artisan migrate

Access: http://localhost:8080/telescope

2. Laravel Debugbar

Installation: 

composer require barryvdh/laravel-debugbar --dev

3. IDE Configuration

VS Code Extensions: - PHP Intelephense - Laravel Extension Pack - GitLens - Docker - ESLint - Prettier

PhpStorm Plugins: - Laravel Plugin - PHP Annotations - .env files support

4. Database Tools

Laravel Tinker: 

# Interactive PHP shell
php artisan tinker

# Example usage
>>> User::count()
>>> Timelog::where('user_id', 1)->get()
>>> Cache::flush()

Database Seeding for Development: 

// database/seeders/DevelopmentSeeder.php
<?php

namespace Database\Seeders;

use Illuminate\Database\Seeder;

class DevelopmentSeeder extends Seeder
{
    public function run()
    {
        // Create test users
        \App\Models\User::factory(50)->create();

        // Create test projects
        \App\Models\Project::factory(20)->create();

        // Create test timelogs
        \App\Models\Timelog::factory(1000)->create();
    }
}

Common Development Tasks

1. Adding a New Feature

# Create feature branch
git checkout -b feature/new-feature

# Generate necessary files
php artisan make:controller NewFeatureController
php artisan make:model NewFeature -m
php artisan make:request NewFeatureRequest

# Write tests
php artisan make:test NewFeatureTest

# Implement feature
# ... code implementation ...

# Run tests
php artisan test

# Commit changes
git add .
git commit -m "Add new feature"
git push origin feature/new-feature

2. Database Schema Changes

# Create migration
php artisan make:migration add_column_to_table

# Edit migration file
# Run migration
php artisan migrate

# Update model if necessary
# Update tests
# Update seeders/factories

3. API Development

# Create API controller
php artisan make:controller Api/V2/NewApiController --api

# Add routes
# Write API tests
# Update API documentation

This development setup guide provides a comprehensive foundation for contributing to the Stratpoint Timesheet Application while maintaining code quality and development best practices.