Development Guide

Guide for developers working on the ITeas Tools Integration Platform.

Prerequisites

• Docker and Docker Compose
• Git
• PHP 8.3+ (for local development without Docker)
• Composer

Getting Started

Clone the Repository

git clone <repository-url>
cd web-iteas-tools-integration

Setup Docker Secrets

Create secret files in docker/secrets/:

mkdir -p docker/secrets/app docker/secrets/db

# Database secrets
echo "your_password" > docker/secrets/db/db_password.txt
echo "your_root_password" > docker/secrets/db/db_root_password.txt

# Application secrets
echo "your_cookie_key" > docker/secrets/app/cookie_validation_key.txt
# ... create other required secret files

See docker-compose-local-dev.yml for the complete list of required secrets.

Start Development Environment

docker-compose -f docker-compose-local-dev.yml up -d

The application will be available at:

• Application: http://127.0.0.1:8000
• Documentation: http://127.0.0.1:8080
• Mailpit (mail testing): http://127.0.0.1:8025

Install Dependencies

docker-compose -f docker-compose-local-dev.yml exec php composer install

Or if working locally:

cd src
composer install

Common Development Tasks

Running Migrations

Apply all migrations:

cd src
php yii migrate

Non-interactive (for scripts):

php yii migrate --interactive=0

Console Commands

Run console commands:

cd src
php yii <controller>/<action>

# Examples:
php yii autotask/sync
php yii jamf/update-devices

Running Tests

Execute all tests:

cd src
vendor/bin/codecept run

Run specific suites:

vendor/bin/codecept run unit
vendor/bin/codecept run functional
vendor/bin/codecept run unit,functional

Cache Management

Clear all caches:

cd src
php yii cache/flush-all

Code Generation with Gii

When YII_ENV=dev, Gii is available for generating code:

Access at: http://127.0.0.1:8000/gii

Available generators:

• Model Generator
• CRUD Generator
• Controller Generator
• Module Generator

Project Structure

src/
├── assets/          Asset bundles (CSS/JS)
├── commands/        Console controllers
├── components/      Application components
│   ├── interfaces/  Component interfaces
│   ├── traits/      Reusable traits
│   └── validators/  Custom validators
├── config/          Configuration files
│   ├── web.php           Web app config
│   ├── console.php       Console config
│   ├── db.php            Database config
│   ├── coreComponents.php Core components
│   ├── modules.php       Module definitions
│   └── params.php        Parameters
├── controllers/     Web controllers
├── core/            Core exceptions
├── mail/            Email templates
├── messages/        i18n translations
├── migrations/      Database migrations
├── models/          Models
│   ├── autotask/    Autotask models
│   ├── db/          ActiveRecord models
│   ├── jamf/        Jamf models
│   ├── search/      Search models
│   ├── view/        View models
│   └── yt/          YouTrack models
├── modules/         Yii2 modules
├── runtime/         Generated files
├── tests/           Test suites
├── views/           View templates
├── web/             Web root
└── widgets/         UI widgets

Adding a New Module

1. Create module directory: src/modules/mymodule/
2. Create Module.php:

   <?php
   namespace app\modules\mymodule;
   
   class Module extends \yii\base\Module
   {
       public $controllerNamespace = 'app\modules\mymodule\controllers';
   }

3. Register in src/config/modules.php:

   'mymodule' => [
       'class' => \app\modules\mymodule\Module::class
   ]

4. Create migrations directory and add to console config if needed

Adding a New Component

1. Create component class in src/components/
2. Register in src/config/coreComponents.php:

   'myComponent' => [
       'class' => \app\components\MyComponent::class,
       'property' => $configurator->getVar('MY_VAR')
   ]

3. Access via Yii::$app->myComponent

Environment Variables

Configuration uses iteas\envLoader\Configurator:

$configurator->getVar('VAR_NAME')           // Read from env
$configurator->getVar('VAR_NAME_FILE')      // Read from file
$configurator->getVar('VAR', 'default')     // With default
$configurator->getVar('VAR', false, 'bool') // Type casting

Debugging

Debug Module

When YII_ENV_DEV=true:

• Debug toolbar available at bottom of pages
• Access debug panel at /debug
• View requests, queries, logs, profiling

Logging

Logs are written to:

• src/runtime/logs/app.log (local dev)
• Graylog (when ENABLE_LOGGING=true)

Code Style

Follow Yii2 conventions:

• PSR-2 coding standards
• Use type hints for PHP 8.3+
• Document classes and methods with PHPDoc
• Keep controllers thin, models fat
• Use components for reusable business logic

Git Workflow

1. Create feature branch from master
2. Make changes and commit
3. Push and create merge request
4. After review, merge to master
5. Tags trigger production deployment