Build

Project

Quality

Community

Spiral Demo with Temporal Workflows.

This project demonstrates the implementation of web application transfers using Temporal.io with Spiral Framework.

It showcases how to handle complex, distributed workflows in a reliable and maintainable way.

📄 About

Imagine moving an entire website between servers - files, databases, domains - with zero downtime and automatic failure recovery.

This is exactly what this project achieves through durable Workflows.

🙏 If you find this repository useful, consider giving it a ⭐️. Thank you!

→ The Challenge

This project uses Website Transfer from Server A to Server B as an example scenario because it shows many common distributed system challenges:

• Network issues during file transfer
• Database backup corruption
• DNS propagation delays
• Server configuration problems
• Timeout issues during large transfers

Traditional approaches require complex error handling, manual recovery procedures, and often lead to extended downtimes. This project offers a robust solution.

→ The Solution

Using Temporal.io, this app demonstrates reliable, self-healing website transfer system that:

• Automatically retries failed operations
• Resumes from the last successful step after crashes
• Provides real-time transfer status visibility
• Handles long-running operations gracefully
• Maintains consistency during the entire process

For example, here's how a website transfer is initiated:

$ make up
$ make ssh
$ php app.php website:transfer

You can monitor the workflow execution through the Temporal UI at:

https://temporal.spiral-app-temporal-demo.docker

The system then automatically orchestrates the entire process:

graph TD
    A[Start Transfer] --> B[Backup Files]
    B --> C[Release Domain]
    C --> D[Backup Database]
    D --> E[Transfer Backups]
    E --> F[Allocate Space]
    F --> G[Restore Database]
    G --> H[Restore Files]
    H --> I[Attach Domain]
    I --> J[Complete]

Loading

→ Use Cases

This example can be adapted for various scenarios:

• Website migrations between hosting providers
• Server infrastructure updates
• Disaster recovery procedures
• Development environment replication

The architecture provided serves as a template for implementing other complex, distributed workflows in your applications.

🚀 Features

This starter template includes several added, changed, and removed features:

→ Framework Modifications

• Added:
  • To be added...
• Changed:
  • To be added...
• Removed:
  • To be added...

→ Development Tools

• Added:
  • Style checker package for custom rule-sets to php-cs-fixer — wayofdev/php-cs-fixer-config
  • Phive support for managing PHP tools
    • ergebnis/composer-normalize composer plugin for normalizing composer.json file
    • maglnet/ComposerRequireChecker to check whether a specific composer package uses imported symbols that aren't part of its direct composer dependencies
  • Application dockerization using docker-compose and Makefile — use make help to view available commands
    • docker-php-dev as PHP development environment with XDebug support out of the box

→ Testing

• Added:
  • Configured PHPUnit for unit testing.
  • Integrated Pest PHP for elegant console support and architecture testing.
  • Infection for mutation testing to ensure quality.
  • Mutation test reports are uploaded Stryker Mutator Dashboard.

→ Static Analysis

• Added:
  • Static analysis tool — PHPStan and it's extensions:
    • phpstan/extension-installer — automatic installation of PHPStan extensions
    • phpstan/phpstan-deprecation-rules — rules for detecting usage of deprecated classes, methods, properties, constants and traits.
    • larastan/larastan for Laravel-specific static analysis.
  • Psalm static analysis tool and it's extensions:
    • psalm/plugin-laravel — Psalm plugin for Laravel
    • psalm/plugin-phpunit — Psalm plugin for PHPUnit
  • PHP Rector for automated code upgrades and refactoring, maintaining modern code standards.

→ Continuous Integration

• Added:
  • GitHub action workflows for:
    • Continuous integration which includes coding standards checks, unit testing and static analysis
    • Automatic pull-request labeling
  • Git pre-commit hooks using pre-commit package

→ Deployments

• Added:
  • Deployer for automatic deployments to staging and production servers with support of GitHub Environments
  • For more information see Deployments section

→ Services

• Added:
  • Mailpit service to simplify email testing in development. Mailpit is an email testing tool that provides a web interface for viewing and managing test emails sent by the application.
  • MinIO service for object storage, compatible with the Amazon S3 API. This enables the application to store and retrieve files in a development environment.
  • Temporal service is included by default for managing distributed workflows. The configuration for Temporal is located in the separate docker-compose.temporal.yaml file, allowing easier integration with the main application.

🚩 Requirements

To use this repository, you need to meet the following requirements:

• Operating System: macOS Monterey+, Linux, or Windows with WSL2.
• Docker: Version 26.0.0 or newer. Installation guides:
  • How To Install and Use Docker on Ubuntu 22.04
  • How To Install Docker Desktop on Mac
• Cloned, configured and running docker-shared-services to support system-wide DNS, routing, and TLS support via Traefik.

💿 Installation

Note

You should configure, set up, and run the docker-shared-services repository to ensure system-wide TLS and DNS support.

→ Docker Shared Services

Check full instructions in docker-shared-services repository.

1. Create shared project directory:

   mkdir -p ~/projects/infra && cd ~/projects/infra

2. Clone docker-shared-services repository:

   git clone \
   [email protected]:wayofdev/docker-shared-services.git \
   ~/projects/infra/docker-shared-services && \
   cd ~/projects/infra/docker-shared-services

3. Create .env file:

   make env

4. Install root certificate and generate default project certs:

   make cert-install

5. Run shared services:

   make up

→ Spiral Starter Template

1. Clone repository:

   After forking or creating generating repository from template, you can clone it to your local machine. In this example we will use spiral-app-temporal-demo repository as starting point.

   git clone \
     [email protected]:wayofdev/spiral-app-temporal-demo.git \
     ~/projects/spiral-app-temporal-demo && \
   cd ~/projects/spiral-app-temporal-demo

2. Generate .env file

   Generate .env file from .env.example file using Makefile command:

   $ make env \
       SHARED_SERVICES_NAMESPACE=ss \
       COMPOSE_PROJECT_NAME=spiral-app-temporal-demo

   Change generated .env file to match your needs, if needed.

   (Optional): to re-generate .env file, add FORCE=true to the end of command:

   $ make env \
       SHARED_SERVICES_NAMESPACE=ss \
       COMPOSE_PROJECT_NAME=spiral-app-temporal-demo \
       FORCE=true

3. Build, install and run. This will also generate Laravel app key:

   $ make
   
   # or run commands separately
   $ make hooks
   $ make install
   $ make key
   $ make prepare
   $ make up

4. Open your browser and navigate to https://api.spiral-app-temporal-demo.docker to see Laravel welcome page.

🧰 Project Architecture

The project architecture of wayofdev/spiral-app-temporal-demo follows a structured approach with distinct layers:

• Domain: Contains core business logic and entities.
• Bridge: Connects the domain layer with external systems or services.
• Infrastructure: Handles interactions with external systems, such as databases, APIs, or file systems.
• Support: Provides general-purpose helper classes that assist various parts of the application.
• DatabaseSeeders: Handles database seeding logic.
• DatabaseFactories: Manages database factory definitions.
• Tests: Contains test cases for various layers of the application.

Each layer has defined dependencies, ensuring a clear separation of concerns and facilitating maintainability and scalability.

For more information check deptrac.yaml located in repository app folder.

🪄 Template

This project was generated from the spiral/app repository using the command: composer create-project spiral/app spiral-app-temporal-demo with the following selected options:

View Setup Options

Which application preset do you want to install?
> [1] Web

Create a default application structure and demo data?
> [1] Yes

Would you like to use SAPI?
> [1] Yes

Do you need Cycle ORM?
> [1] Yes

Which collections do you want to use with Cycle ORM?
> [2] Laravel Collections

Which validator component do you want to use?
> [3] Laravel Validator

Do you want to use Queue component?
> [1] Yes

Do you want to use Cache component?
> [1] Yes

Do you want to use Mailer component?
> [1] Yes

Do you want to use Storage component?
> [1] Yes

Which template engine do you want to use?
> [3] Plain PHP

Do you need Data Grid?
> [1] Yes

Do you want to use the Event Dispatcher?
> [1] Yes

Do you need a cron jobs scheduler?
> [1] Yes

Do you need Translator?
> [0] No

Do you need the Temporal?
> [1] Yes

Do you need the RoadRunner Metrics?
> [1] Yes

Do you need the Sentry?
> [1] Yes