# laravel/valet architecture

> Architecture diagram of the GitHub repository laravel/valet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/laravel/valet
- Repository: https://github.com/laravel/valet

## Overview

##### Project Type & Purpose
- Valet is a CLI-driven development environment specifically tailored for Laravel (and more broadly PHP) development on MacOS. Its purpose is to simplify local development by configuring Nginx and DnsMasq to serve your sites on a *.test domain without the overhead of more heavyweight environments like Vagrant.
- The project is structured as a command-line application (located mainly under the “cli” directory) that sets up and manages background services and routes requests to local projects using a driver-based approach.

##### Core Components
A. Command-Line Interface (CLI)/Control Module:
– Located in the “cli” directory, this is the user-facing layer where commands (e.g., “valet install”, “valet link”) are interpreted.
– Includes core files such as Valet.php, app.php, and helper scripts in the “includes” directory.
– Manages overall coordination of configuration and invoking sub-components.

B. Web Server & Service Routers:
– Nginx: Valet configures Nginx to run in the background for serving websites, with configuration stubs (see “cli/stubs/nginx.conf”, “cli/stubs/site.valet.conf”, etc.).
– DnsMasq: Integrated (see cli/Valet/DnsMasq.php and tests) to handle DNS resolution of *.test domains to localhost.
– PHP-FPM: Managed via cli/Valet/PhpFpm.php to handle PHP request processing.
– Tools for tunnelling: e.g., Cloudflared and Ngrok integration for sharing local sites publicly (referencing cli/Valet/Cloudflared.php and cli/Valet/Ngrok.php).

C. Driver System (for Site Routing/Customization):
– The “cli/Valet/Drivers” directory holds multiple drivers like BasicValetDriver, LaravelValetDriver, and many “Specific” drivers (e.g., WordPress, Craft, Drupal, etc.).
– These drivers encapsulate logic specific to different project frameworks and directory layouts – a plug-in architecture that makes Valet flexible across various PHP projects.
– The system chooses the appropriate driver based on the project structure, ensuring the correct environment is served.

D. Configuration & Utility Components:
– Configuration: Handled via cli/Valet/Configuration.php, which reads and writes Valet settings (a global config “.valetrc” or “.valetphprc” in test fixtures).
– Diagnostics and Upgrade utilities: (“cli/Valet/Diagnose.php”, “cli/Valet/Upgrader.php”) to assist in troubleshooting and updating.
– Filesystem abstractions and server management components (e.g., cli/Valet/Filesystem.php, cli/Valet/Server.php) provide additional support.

E. Testing & Stubs:
– The “tests” directory contains extensive test suites for each component, especially for validating each driver, server behaviors, and integration functionalities.
– Stub files (under “cli/stubs”) provide sample configurations and scripts used during installation – these are good references to understand default behaviors and configurations.

##### Relationships & Data Flow
- The user interacts with the CLI (via terminal commands). The CLI module then delegates tasks.
- Configuration settings are loaded by the CLI and affect the underlying service modules (Nginx, DnsMasq, PHP-FPM).
- The driver system is critical: when the CLI links a folder as a site, it uses the appropriate Driver (selected from the “Drivers” folders) to determine how to route HTTP requests.
- Services, once running, serve HTTP requests by Nginx that pipes PHP requests to PHP-FPM, while DNS resolution by DnsMasq directs all *.test requests to the local machine.
- External utilities like Cloudflared/Ngrok are optionally activated to expose sites publicly.

##### Architectural Patterns & Design Principles
- Modular Design: The clear separation between command-line processing, service configuration, and driver detection.
- Plug-in Architecture: The “Drivers” directory acts as an extension point for supporting various PHP frameworks and site structures.
- Service Orchestration: Actually “orchestrating” background services (Nginx, PHP-FPM, DnsMasq) that work collectively to serve local sites.
- Minimal Footprint: Emphasis on running a lean environment (using minimal RAM resources) which is reflected in the lightweight design and configuration stubs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    UI["User/Terminal"]:::user

    %% Valet CLI Core
    subgraph "Valet CLI Core"
        CLI["Valet CLI Controller"]:::cli
        CONFIG["Configuration Module"]:::config
        SERVICE_MANAGER["Service Manager"]:::service
        DRIVER_RESOLVER["Driver Resolver"]:::driver
    end

    UI -->|"enter_commands"| CLI
    CLI -->|"load_configs"| CONFIG
    CLI -->|"init_services"| SERVICE_MANAGER
    CLI -->|"resolve_driver"| DRIVER_RESOLVER

    %% Service Orchestration
    subgraph "Service Orchestration"
        NGINX["NGINX Service"]:::web
        DNS["DnsMasq Service"]:::dns
        PHPFPM["PHP-FPM Service"]:::php
        %% Tunnelling Utilities as a subgraph
        subgraph "Tunnelling Utilities"
            CLOUDFLARED["Cloudflared"]:::tunnel
            NGROK["Ngrok"]:::tunnel
        end
    end

    SERVICE_MANAGER -->|"configure"| NGINX
    SERVICE_MANAGER -->|"configure"| DNS
    SERVICE_MANAGER -->|"configure"| PHPFPM
    SERVICE_MANAGER -->|"optional"| CLOUDFLARED
    SERVICE_MANAGER -->|"optional"| NGROK

    %% Driver System
    subgraph "Driver System"
        BASIC["BasicValetDriver"]:::driverNode
        LARAVEL["LaravelValetDriver"]:::driverNode
        SPECIFIC["Specific Drivers"]:::driverNode
    end

    DRIVER_RESOLVER -->|"selects"| BASIC
    DRIVER_RESOLVER -->|"selects"| LARAVEL
    DRIVER_RESOLVER -->|"selects"| SPECIFIC

    %% Configuration & Utilities
    subgraph "Configuration & Utility"
        CONFIG_COMP["Configuration & Utilities"]:::config
    end

    CONFIG -->|"reads_writes"| CONFIG_COMP

    %% Testing & Stubs
    subgraph "Testing & Stubs"
        TESTS["Test Suites"]:::test
        STUBS["Configuration Stubs"]:::stub
    end

    NGINX -->|"uses_stub"| STUBS
    DNS -->|"test_config"| TESTS
    PHPFPM -->|"uses_stub"| STUBS

    %% Click Events for CLI/Control Module
    click CLI "https://github.com/laravel/valet/blob/master/cli/Valet/Valet.php"
    click CLI "https://github.com/laravel/valet/blob/master/cli/app.php"
    click CLI "https://github.com/laravel/valet/tree/master/cli/includes"

    %% Click Events for Nginx Service
    click NGINX "https://github.com/laravel/valet/blob/master/cli/Valet/Nginx.php"
    click NGINX "https://github.com/laravel/valet/blob/master/cli/stubs/nginx.conf"

    %% Click Events for DnsMasq Service
    click DNS "https://github.com/laravel/valet/blob/master/cli/Valet/DnsMasq.php"
    click DNS "https://github.com/laravel/valet/blob/master/tests/files/dnsmasq.conf"

    %% Click Events for PHP-FPM Service
    click PHPFPM "https://github.com/laravel/valet/blob/master/cli/Valet/PhpFpm.php"
    click PHPFPM "https://github.com/laravel/valet/blob/master/cli/stubs/etc-phpfpm-valet.conf"

    %% Click Events for Tunnelling Utilities
    click CLOUDFLARED "https://github.com/laravel/valet/blob/master/cli/Valet/Cloudflared.php"
    click NGROK "https://github.com/laravel/valet/blob/master/cli/Valet/Ngrok.php"

    %% Click Events for Driver System
    click BASIC "https://github.com/laravel/valet/tree/master/cli/Valet/Drivers"
    click LARAVEL "https://github.com/laravel/valet/tree/master/cli/Valet/Drivers"
    click SPECIFIC "https://github.com/laravel/valet/tree/master/cli/Valet/Drivers/Specific"

    %% Click Events for Configuration & Utility Components
    click CONFIG_COMP "https://github.com/laravel/valet/blob/master/cli/Valet/Configuration.php"
    click CONFIG_COMP "https://github.com/laravel/valet/blob/master/cli/Valet/Diagnose.php"
    click CONFIG_COMP "https://github.com/laravel/valet/blob/master/cli/Valet/Upgrader.php"
    click CONFIG_COMP "https://github.com/laravel/valet/blob/master/cli/Valet/Filesystem.php"
    click CONFIG_COMP "https://github.com/laravel/valet/blob/master/cli/Valet/Server.php"

    %% Click Events for Testing & Stubs
    click TESTS "https://github.com/laravel/valet/tree/master/tests"
    click STUBS "https://github.com/laravel/valet/tree/master/cli/stubs"

    %% Styles
    classDef user fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef cli fill:#66CCFF,stroke:#333,stroke-width:2px;
    classDef config fill:#CCFFCC,stroke:#333,stroke-width:2px;
    classDef service fill:#FFCCCC,stroke:#333,stroke-width:2px;
    classDef web fill:#FF9999,stroke:#333,stroke-width:2px;
    classDef dns fill:#FF6666,stroke:#333,stroke-width:2px;
    classDef php fill:#FF3333,stroke:#333,stroke-width:2px;
    classDef tunnel fill:#CC99FF,stroke:#333,stroke-width:2px;
    classDef driver fill:#FFCC99,stroke:#333,stroke-width:2px;
    classDef driverNode fill:#FFCC66,stroke:#333,stroke-width:2px;
    classDef test fill:#CCCCCC,stroke:#333,stroke-width:2px;
    classDef stub fill:#CCCCFF,stroke:#333,stroke-width:2px;
```
