# meilisearch/meilisearch-php architecture

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

- Interactive diagram: https://gitdiagram.com/meilisearch/meilisearch-php
- Repository: https://github.com/meilisearch/meilisearch-php

## Overview

##### Project type and purpose
- This is an open-source PHP SDK (API client) for Meilisearch, a standalone search engine.
- Its sole responsibility is to provide developers with a typed, PSR-compliant, high-level PHP interface to communicate with a Meilisearch server over HTTP.

##### File structure
- Top-level:
– src/Client.php – the façade entry point
– src/Contracts/… – interfaces defining queries, results, endpoints, etc.
– src/Endpoints/… – concrete implementations of each Meilisearch endpoint (Indexes, Documents, Tasks, Stats, etc.)
– src/Http/… – HTTP client implementation wrapper + serializer (PSR-18 + PSR-17 + JSON)
– src/Exceptions/… – typed exceptions for API, network, JSON, timeouts
– src/Meilisearch.php – convenience alias
- Tests and scripts are kept separate and not part of runtime; they validate each component.
- Configuration: composer.json, Dockerfile, CI workflows—support packaging, testing, and release.

##### Extract architecture notes from the README
- The SDK requires a PSR-18 HTTP client + PSR-17 HTTP factory.
- It exposes a single Client class: developers call `$client = new Client(url, key, optionalHttpClient)`
- All calls (indexing, searching, settings, tasks) funnel through endpoint classes which orchestrate query construction, HTTP invocation, and response deserialization.

a. Main components
- Application code (your PHP project using the SDK)
- Meilisearch PHP SDK
– Client façade
– Endpoint modules
– Contracts (interfaces)
– HTTP layer (PSR-18 client + serializer)
– Exception handlers
- PSR-18 HTTP Client (e.g., Guzzle, Symfony) & PSR-17 factory
- JSON Serializer (implements SerializerInterface)
- External Meilisearch server (hosted or self-hosted)
b. Relationships & interactions
1. App → Client: developer instantiates `Client` and calls methods (e.g., `index->addDocuments()`, `index->search()`).
2. Client → Endpoint: delegates call to the correct Endpoint class (Indexes, Documents, Tasks, etc.).
3. Endpoint → Contracts: assembles a Query DTO (implements appropriate Query interface).
4. Endpoint → HTTP layer:
– Uses PSR-18 client + PSR-17 factory to build an HTTP Request.
– Passes serialized JSON payload via Serializer.
5. HTTP layer ↔ Meilisearch server: actual network call over HTTP.
6. Response → HTTP layer: receives HTTP response, JSON → parse into Results DTO (implements Results interface).
7. Endpoint returns typed Results (or throws Exception).
8. Client returns to Application.
c. Architectural patterns & design principles
- Layered: Presentation (app) → SDK API → Domain (Endpoints) → Infrastructure (HTTP) → External service
- Dependency Injection: HTTP client and serializer are injected into Client.
- Delegation & Traits: common behaviors (e.g., batching, documents) are shared across endpoints via traits.
- Robust error handling: specialized exceptions for API errors, communication failures, JSON issues.
d. Key technologies & libraries
- PSR-18 (HTTP Client), PSR-17 (HTTP Message Factory)
- JSON Serializer (implements `SerializerInterface`)
- Composer for dependency management
- PHPUnit for tests
- Docker & CI workflows for packaging and releasing

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Application Code" 
        direction TB
        App["App: Uses SDK"] 
    end
    class App util

    %% SDK API Layer
    subgraph "SDK API Layer" 
        direction TB
        ClientFacade["Client"] 
        MeiliAlias["Meilisearch (alias)"]
    end
    class ClientFacade,MeiliAlias sdkapi

    %% Endpoints Layer
    subgraph "Endpoints (src/Endpoints)" 
        direction TB
        EndpointsGroup["Endpoint Modules"]
    end
    class EndpointsGroup sdkapi

    %% Contracts Layer
    subgraph "Contracts (src/Contracts)" 
        direction TB
        ContractsGroup["Interfaces"]
    end
    class ContractsGroup sdkapi

    %% Infrastructure Layer
    subgraph "HTTP & Serialization" 
        direction TB
        PSR18["PSR-18 HTTP Client Wrapper"]
        SerializerIface["SerializerInterface"]
        JsonSerializer["JSON Serializer"]
    end
    class PSR18,SerializerIface,JsonSerializer infra

    %% Exception Layer
    subgraph "Exceptions (src/Exceptions)" 
        direction TB
        Exceptions["Typed Exceptions"]
    end
    class Exceptions infra

    %% External Service
    subgraph "External Service" 
        direction TB
        MeiliServer["Meilisearch Server"]
    end
    class MeiliServer external

    %% Non-runtime/Support
    subgraph "Support Files" 
        direction TB
        Tests["Test Suite"]
        Composer["composer.json"]
        DockerConf["Dockerfile + docker-compose.yml"]
        CI["CI Workflows"]
    end
    class Tests,Composer,DockerConf,CI util

    %% Connections
    App -->|"calls"| ClientFacade
    ClientFacade -->|"delegates to"| EndpointsGroup
    EndpointsGroup -->|"uses interfaces"| ContractsGroup
    EndpointsGroup -->|"builds HTTP requests"| PSR18
    PSR18 -->|"serialize via"| SerializerIface
    SerializerIface -->|"implemented by"| JsonSerializer
    PSR18 -->|"sends HTTP"| MeiliServer
    MeiliServer -->|"responds HTTP"| PSR18
    PSR18 -->|"deserialized via"| JsonSerializer
    JsonSerializer -->|"returns DTO"| EndpointsGroup
    EndpointsGroup -->|"returns results or throws"| ClientFacade
    ClientFacade -->|"returns to"| App

    %% Click Events
    click ClientFacade "https://github.com/meilisearch/meilisearch-php/blob/main/src/Client.php"
    click MeiliAlias "https://github.com/meilisearch/meilisearch-php/blob/main/src/Meilisearch.php"
    click ContractsGroup "https://github.com/meilisearch/meilisearch-php/tree/main/src/Contracts"
    click EndpointsGroup "https://github.com/meilisearch/meilisearch-php/tree/main/src/Endpoints"
    click PSR18 "https://github.com/meilisearch/meilisearch-php/blob/main/src/Http/Client.php"
    click SerializerIface "https://github.com/meilisearch/meilisearch-php/blob/main/src/Http/Serialize/SerializerInterface.php"
    click JsonSerializer "https://github.com/meilisearch/meilisearch-php/blob/main/src/Http/Serialize/Json.php"
    click Exceptions "https://github.com/meilisearch/meilisearch-php/tree/main/src/Exceptions"
    click Tests "https://github.com/meilisearch/meilisearch-php/tree/main/tests"
    click Composer "https://github.com/meilisearch/meilisearch-php/blob/main/composer.json"
    click DockerConf "https://github.com/meilisearch/meilisearch-php/tree/main/Dockerfile"
    click CI "https://github.com/meilisearch/meilisearch-php/tree/main/.github/workflows"

    %% Styles
    classDef sdkapi fill:#e0ffe0,stroke:#008000,color:#000
    classDef infra fill:#e0f0ff,stroke:#0000ff,color:#000
    classDef external fill:#ffe0b3,stroke:#ff8000,color:#000
    classDef util fill:#f0f0f0,stroke:#888888,color:#000
```
