From ce8cdf6a47815c931a04ae37a7d04206328c1792 Mon Sep 17 00:00:00 2001
From: azjezz <azjezz@protonmail.com>
Date: Fri, 24 Jan 2025 02:23:48 +0100
Subject: [PATCH] docs: add composer installation guide

Signed-off-by: azjezz <azjezz@protonmail.com>
---
 docs/getting-started/installation.md | 51 ++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index f7c8baf..1505a4c 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -54,6 +54,57 @@ brew install mago
 
 ---
 
+## Installation via Composer
+
+If you're already using Composer in your PHP project, you can install Mago as a Composer dependency. Follow these steps:
+
+1. **Add Mago as a dependency**:
+   Run the following command in your terminal:
+
+   ```bash
+   composer require carthage-software/mago
+   ```
+
+2. **Enable the Mago plugin**:
+   Update your composer.json file to enable the Mago plugin by adding the following under the "config" section:
+
+   ```json
+   {
+     "config": {
+       "allow-plugins": {
+         "carthage-software/mago": true
+       }
+     }
+   }
+   ```
+
+3. **Install the Mago binary**:
+   Run the following command to install the Mago binary:
+
+   ```bash
+   composer mago:install-binary
+   ```
+
+4. **Run Mago**:
+   You can now use Mago through the vendor/bin directory:
+
+   ```bash
+   vendor/bin/mago --help
+   ```
+
+> ### Note on Performance
+>
+> When using Mago via Composer (`vendor/bin/mago`), performance on small-to-medium applications might seem slower compared to running the binary directly.
+> This is because the `vendor/bin/mago` script is a PHP file that proxies commands to the Mago binary. As a result, you're effectively running:
+>
+> - PHP (to process the script),
+> - The script itself,
+> - The Mago binary.
+>
+> This extra overhead might be noticeable in smaller applications, but it's less significant for larger projects.
+
+---
+
 ## Pre-compiled Binaries
 
 You can find precompiled binaries for various platforms on our [Releases page](https://github.com/carthage-software/mago/releases).