# justbetter/laravel-magento-client architecture

> Architecture diagram of the GitHub repository justbetter/laravel-magento-client, 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/justbetter/laravel-magento-client
- Repository: https://github.com/justbetter/laravel-magento-client

## Overview

This project is a Laravel package designed to integrate a Magento system into your Laravel applications. In other words, it “wraps” Magento’s API calls into a client that is easily usable within Laravel. The package supports multiple connections, provides built-in support for bearer and OAuth 1.0 authentication, and contains various components for building requests, processing responses, and handling Magento’s specific authentication flows.

##### Main Components
- Client Component:
- Located in src/Client/Magento.php – acts as the primary gateway for interacting with the Magento API.
- Supports multiple connections (each defined in the configuration) and provides methods such as get, post, patch, and graphql.
- Actions & Contracts:
- In src/Actions and src/Contracts. These encapsulate the logic for building and authenticating API requests.
- Includes actions for OAuth handling (e.g., src/Actions/OAuth/RequestAccessToken.php) and checking Magento availability.
- OAuth & Authentication:
- Contains both traditional bearer token and OAuth implementations.
- Components include: src/OAuth (which handles OAuth signing, key storage strategies like FileKeyStore and DatabaseKeyStore) and related contracts under src/Contracts/OAuth.
- The README outlines the specific flow for OAuth 1.0 (using endpoints defined in the routes and controllers).
- HTTP Layer:
- Controllers (e.g., src/Http/Controllers/OAuthController.php) manage callback and identity endpoints.
- HTTP Requests and Middleware (e.g., src/Http/Middleware/OAuthMiddleware.php) ensure the proper authentication of inbound requests.
- Query and Filtering:
- The Query folder (src/Query/Grammar.php and src/Query/SearchCriteria.php) is used to build and transform search criteria for Magento queries.
- Supporting Components:
- Providers (src/Providers) and Enums: Assist in managing different behaviors (like handling token providers).
- Models: For persisting OAuth keys (e.g., src/Models/OAuthKey.php).
- Events, Listeners, and Jobs: These components (e.g., src/Events/MagentoResponseEvent.php, src/Listeners/StoreAvailabilityListener.php, and job middleware) help chaining asynchronous processing, error handling and availability checks.
- Configurations & Migrations:
- The config folder (config/magento.php) and migrations (database/migrations) show that the package also requires certain persistent setups which are relevant for OAuth key storage and availability checking.

##### Relationships and Interactions
- The Laravel application (consumer) instantiates the Magento client.
- The client uses the Actions layer to build and authenticate the requests.
- It leverages the Query builder to generate proper search criteria for interacting with Magento endpoints.
- When OAuth is enabled, the client interacts with the OAuth endpoints handled by the HTTP controllers, using middleware to secure these endpoints.
- OAuth tokens and keys are stored via the key store implementations (either in files or in a database, as configured in src/OAuth/KeyStore).
- Provider components abstract and switch between authentication mechanisms (BearerTokenProvider vs OAuthProvider).
- Events and Listeners allow other parts of the system to respond to Magento's responses or availability issues.
- Job middleware (AvailableMiddleware) ensures that queued jobs wait or retry if Magento is temporarily unreachable.

##### Architectural Patterns and Design Principles
- Separation of Concerns:
- Each directory and component is dedicated to a specific aspect (request building, authentication, client communication, etc.).
- Dependency Inversion:
- Contracts (interfaces) define what is expected, while concrete implementations (in Actions, OAuth, Providers) are injected, increasing flexibility.
- Configurability and Multi-Connection Support:
- The design is tailored to support multiple Magento connections as defined in the configuration file.
- Extensibility:
- Use of events, listeners, and a provider pattern to allow easy integration of additional functionality or authentication methods.

##### Specific Elements
- Side notes that indicate configuration influence (env settings, publisher commands) on components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Level
    App["Laravel Application"]:::app
    Client["Magento Client"]:::client

    App -->|"Instantiates"| Client

    %% Subgraph: Actions & Contracts
    subgraph "Actions & Contracts"
        A1["BuildRequest"]:::actions
        A2["AuthenticateRequest"]:::actions
        A3["CheckMagento"]:::actions
        A4["RequestAccessToken"]:::actions
        C1["AuthenticatesRequest"]:::actions
        C2["BuildsRequest"]:::actions
        C3["ChecksMagento"]:::actions
        C4["RequestsAccessToken"]:::actions
    end

    %% Subgraph: Query Builder / SearchCriteria
    subgraph "Query Builder / SearchCriteria"
        Q1["Grammar"]:::query
        Q2["SearchCriteria"]:::query
    end

    %% Subgraph: OAuth & Authentication Module
    subgraph "OAuth & Authentication Module"
        O1["MagentoServer"]:::oauth
        O2["HmacSha256Signature"]:::oauth
        subgraph "Key Store"
            K1["KeyStore"]:::oauth
            K2["FileKeyStore"]:::oauth
            K3["DatabaseKeyStore"]:::oauth
        end
        O1 -->|"Uses"| K1
        K1 -->|"Implmentation"| K2
        K1 -->|"Implmentation"| K3
    end

    %% Subgraph: HTTP Layer
    subgraph "HTTP Layer"
        H1["OAuthController"]:::http
        H2["OAuthMiddleware"]:::http
        H3["CallbackRequest"]:::http
        H4["IdentityRequest"]:::http
    end

    %% Subgraph: Providers
    subgraph "Providers"
        P1["BaseProvider"]:::providers
        P2["BearerTokenProvider"]:::providers
        P3["OAuthProvider"]:::providers
    end

    %% Subgraph: Supporting Components
    subgraph "Supporting Components"
        S1["OAuthKey Model"]:::support
        S2["MagentoResponseEvent"]:::support
        S3["StoreAvailabilityListener"]:::support
        S4["Job Middleware"]:::support
    end

    %% Subgraph: Configurations & Migrations
    subgraph "Configurations & Migrations"
        CF["magento.php Config"]:::config
        MIG["Migration for OAuth Keys"]:::config
    end

    %% Connections from Magento Client
    Client -->|"Builds/Authenticates"| A1
    Client -->|"Builds/Authenticates"| A2
    Client -->|"Checks Availability"| A3
    Client -->|"Handles OAuth"| A4
    Client -->|"Uses Contracts"| C1
    Client -->|"Uses Contracts"| C2
    Client -->|"Uses Contracts"| C3
    Client -->|"Uses Contracts"| C4
    Client -->|"Generates Query"| Q1
    Client -->|"Generates Query"| Q2
    Client -->|"Calls OAuth Module"| O1
    Client -->|"Calls OAuth Module"| O2
    Client -->|"Routes via HTTP"| H1
    Client -->|"Secured by"| H2
    Client -->|"Handles Requests"| H3
    Client -->|"Handles Requests"| H4
    Client -->|"Selects Provider"| P1
    Client -->|"Selects Provider"| P2
    Client -->|"Selects Provider"| P3
    Client -->|"Emits Responses"| S2
    S2 -->|"Triggers"| S3
    Client -->|"Ensures Availability"| S4

    %% Configurations feeding into modules
    CF -->|"Configures"| Client
    CF -->|"Configures"| O1
    MIG -->|"Sets up"| S1

    %% Click Events
    click Client "https://github.com/justbetter/laravel-magento-client/blob/main/src/Client/Magento.php"
    click A1 "https://github.com/justbetter/laravel-magento-client/blob/main/src/Actions/BuildRequest.php"
    click A2 "https://github.com/justbetter/laravel-magento-client/blob/main/src/Actions/AuthenticateRequest.php"
    click A3 "https://github.com/justbetter/laravel-magento-client/blob/main/src/Actions/CheckMagento.php"
    click A4 "https://github.com/justbetter/laravel-magento-client/blob/main/src/Actions/OAuth/RequestAccessToken.php"
    click C1 "https://github.com/justbetter/laravel-magento-client/blob/main/src/Contracts/AuthenticatesRequest.php"
    click C2 "https://github.com/justbetter/laravel-magento-client/blob/main/src/Contracts/BuildsRequest.php"
    click C3 "https://github.com/justbetter/laravel-magento-client/blob/main/src/Contracts/ChecksMagento.php"
    click C4 "https://github.com/justbetter/laravel-magento-client/blob/main/src/Contracts/OAuth/RequestsAccessToken.php"
    click Q1 "https://github.com/justbetter/laravel-magento-client/blob/main/src/Query/Grammar.php"
    click Q2 "https://github.com/justbetter/laravel-magento-client/blob/main/src/Query/SearchCriteria.php"
    click O1 "https://github.com/justbetter/laravel-magento-client/blob/main/src/OAuth/MagentoServer.php"
    click O2 "https://github.com/justbetter/laravel-magento-client/blob/main/src/OAuth/HmacSha256Signature.php"
    click K1 "https://github.com/justbetter/laravel-magento-client/blob/main/src/OAuth/KeyStore/KeyStore.php"
    click K2 "https://github.com/justbetter/laravel-magento-client/blob/main/src/OAuth/KeyStore/FileKeyStore.php"
    click K3 "https://github.com/justbetter/laravel-magento-client/blob/main/src/OAuth/KeyStore/DatabaseKeyStore.php"
    click H1 "https://github.com/justbetter/laravel-magento-client/blob/main/src/Http/Controllers/OAuthController.php"
    click H2 "https://github.com/justbetter/laravel-magento-client/blob/main/src/Http/Middleware/OAuthMiddleware.php"
    click H3 "https://github.com/justbetter/laravel-magento-client/blob/main/src/Http/Requests/CallbackRequest.php"
    click H4 "https://github.com/justbetter/laravel-magento-client/blob/main/src/Http/Requests/IdentityRequest.php"
    click P1 "https://github.com/justbetter/laravel-magento-client/blob/main/src/Providers/BaseProvider.php"
    click P2 "https://github.com/justbetter/laravel-magento-client/blob/main/src/Providers/BearerTokenProvider.php"
    click P3 "https://github.com/justbetter/laravel-magento-client/blob/main/src/Providers/OAuthProvider.php"
    click S1 "https://github.com/justbetter/laravel-magento-client/blob/main/src/Models/OAuthKey.php"
    click S2 "https://github.com/justbetter/laravel-magento-client/blob/main/src/Events/MagentoResponseEvent.php"
    click S3 "https://github.com/justbetter/laravel-magento-client/blob/main/src/Listeners/StoreAvailabilityListener.php"
    click S4 "https://github.com/justbetter/laravel-magento-client/blob/main/src/Jobs/Middleware/AvailableMiddleware.php"
    click CF "https://github.com/justbetter/laravel-magento-client/blob/main/config/magento.php"
    click MIG "https://github.com/justbetter/laravel-magento-client/blob/main/database/migrations/2023_12_11_150000_create_magento_oauth_keys_table.php"

    %% Styles
    classDef app fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef client fill:#A9DFBF,stroke:#239B56,stroke-width:2px;
    classDef actions fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef query fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef oauth fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef http fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef providers fill:#AED6F1,stroke:#1ABC9C,stroke-width:2px;
    classDef support fill:#D5DBDB,stroke:#7DCEA0,stroke-width:2px;
    classDef config fill:#F2F3F4,stroke:#95A5A6,stroke-width:2px;
```
