Build

Project

Quality

Community

Spiral Framework Starter Template

This is an opinionated modified version of the Spiral Framework which aims at providing a Domain-Driven Design (DDD) structure.

📄 About

To be added...

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

🚀 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-starter-tpl repository as starting point.

   git clone \
     [email protected]:wayofdev/spiral-starter-tpl.git \
     ~/projects/spiral-starter-tpl && \
   cd ~/projects/spiral-starter-tpl

2. Generate .env file

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

   $ make env \
       SHARED_SERVICES_NAMESPACE=ss \
       COMPOSE_PROJECT_NAME=spiral-starter-tpl

   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-starter-tpl \
       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-starter-tpl.docker to see Laravel welcome page.

🧰 Project Architecture

The project architecture of wayofdev/spiral-starter-tpl 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-starter-tpl 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